Catalog Options and Modifiers v2

What this is. The design of the second generation of catalog options ("modifiers"), the effective-offer rule shared by every reader, the ownership fixes that must precede Sales and Pricing, the offline outline and the structured variant attributes. It extends CATALOG_USE_CASES.md (C12, C13, C17–C20) and plans the slices K9a to K15d and K16. Built, each with its As built section: K9a, K9b and K9c (§4.1), K9f (§4.2), K9g (§4.3), K9d (§4.4), K9e (§5.1), the satisfiability by units of K9h (§4.2, As built (F1)), K10a, K10b and K10c (§6.2), D1 (§18.1), B1 (§19.2), B2 (§20.2), M1 (§21.2), the standardization after M1 (§21) M2a (§21, "M2a as built"), K16 (§21, "K16 as built"), K14c ("K14c as built"), K14d ("K14d as built"), K15a ("K15a as built"), K12a ("K12a as built") and K12b ("K12b as built"). What is still a design, and in which order, is in §10 and its coverage snapshot (§10.1).

Reconciled with the architect's final review (owner's architect, Ninaku Core — revisión de Catálogo, contratos, SQL y offline, 2026-10-07, reviewed commit e0e9bdf; findings H1–H8 and the work order of its §13). Where this document follows the review it says so; where it decides something the review left open, the decision is marked; where it diverges, §3 says why.

Lead decision. Work follows the architect's order: H1 stable offer identities and retirement first (K9a–K9c), then H2/H3 quantified selection and the effective offer identity in the contract (K9d–K9e), then H4 variant overrides (K9f–K9h), then H7 SQL ownership (K10a–K10c), then the minimal Sales/Pricing integration proof (K11, which also measures H8), then H5 offline (K12a–K12c), then H6 structured variant attributes (K13a–K13b), then option and master-data specializations (K14, K15), and only then menus and bundles. Sales and Pricing must not reference offers before K9b ships, and must not call admit before K9e ships.

First implementation slice: K9a — one expand-only migration that adds the retired offer status, and every reader of offers taught to ignore a retired offer, with no writer of retired yet (§4.1, §10).

Owner direction (2026-10-07, translated). "The old backend was only a study. In this new backend we must do things correctly and add all of these things, taking into account inventory and everything else: pricing, discounts, all of it. It must be super powerful, even for other sectors. Catalog is super important." Kept as Decided: per-variant modifier offers in v1; a quantity-aware admission; no coupling between modules and no duplicated data (Catalog never stores prices, stock or tax).

Status words. Decided: taken by the owner's direction, by an executable authority (the canonical SQL), or already built; the owner only needs to object. Recommended: the designer's default; review may change it. Proposed: a shape kept for later, not scheduled. Open owner questions are in §15.

Ground truth. The canonical SQL under database/canonical/ (0080_catalog.sql, 0090_pricing.sql, 0100_commerce.sql, 0110_sales.sql, 0140_operations.sql, 0150_kitchen.sql, 0170_inventory.sql, 0180_production.sql, 0260_tax.sql, 0350_integrations.sql, 0360_events.sql, 0370_sync.sql), database/access/runtime_grants.sql, src/modules/catalog/, src/modules/organization/, docs/reference/ARCHITECTURE.md; the feature branch at migration 0083, baseline revision 93. Line numbers refer to these files in this branch. Legacy backend facts come from the owner's study of the old system (briefing of 2026-10-07): lessons, never code to copy.

---

Quick path

1. H1, K9a–K9c: offers keep their UUID for ever; removing a group retires the offer (a new retired status), never deletes it; suspending stays inactive; then DELETE on offers is revoked.
2. H2/H3, K9d–K9e: selections travel as { optionId, quantity }; groups are judged on the sum of units; admit answers the effective offer (itemModifierGroupId, modifierGroupId, source, min, max).
3. H4, K9f–K9h: one effective-offer rule for the till, the search, the scan and admit: an active variant override replaces the item offer, an inactive variant override opts the variant out, no override inherits.
4. H7, K10a–K10c: Catalog stops naming Organization and Platform tables; Organization stops writing Platform's table.
5. K11: a minimal Sales/Pricing proof over the real FKs, and the H8 admission budget measured on the real sale transaction.
6. H5, K12a–K12c; H6, K13a–K13b; then K14, K15; then menus and bundles.

---

1. Why a v2

Evidence	Source	Consequence
Saving an item's offers deletes every item-level offer and re-inserts the list with new UUIDs	src/modules/catalog/infrastructure/modifiers/modifier-group.queries.ts:158-175; modifier-group.repository.ts:338-344	Sales and Pricing reference offers with no cascade (0110_sales.sql:1229-1237, 0090_pricing.sql:470-478): once referenced, an edit fails (architect H1)
A required offer with status <> 'active' makes the item unconfigurable	src/modules/catalog/infrastructure/reads/sellable-rule.queries.ts:55-73	Retiring by setting inactive would hide the item: "no longer offered" and "offered but unavailable" need two states (architect H1)
admit takes modifierOptionIds: string[] and refuses repeats	src/modules/catalog/contracts/catalog-sellable.contract.ts:68-81; application/sellable/sellable-request.ts:27-35, :65-75	"Cheese × 2" cannot be expressed (architect H2)
Catalog counts distinct options; Sales sums quantity	src/modules/catalog/domain/sellable/sellability.ts:123-149; 0110_sales.sql:4229-4247	The same rule means two things (architect H2; the architect executed judgeSelection and got selection_below_minimum for cheese with minimum 2)
The snapshot carries modifierGroupId, not the offer id	catalog-sellable.contract.ts:26-33; infrastructure/sellable/sellable.queries.ts:31-53	Sales cannot fill item_modifier_group_id (0110_sales.sql:1184) without reading Catalog's tables (architect H3)
Admission and the till read only item-level offers	sellable.queries.ts:24-29; infrastructure/till/till-read.queries.ts:111, :139	Sales already prefers variant offers (0110_sales.sql:4120-4134, :4200-4225): the surfaces diverge (architect H4)
Catalog SQL names Organization and Platform tables	infrastructure/items/item.queries.ts:84; sellable/sellable.queries.ts:69, :109; barcodes/barcode-lookup.queries.ts:18-22; assortment/assortment.queries.ts:3, :55; reads/catalog-read.queries.ts:49-50; reads/item-list.queries.ts:64; till/till-read.queries.ts:43, :187	Against ARCHITECTURE.md:218-239 ("Ningún módulo tiene permitido acceder directamente a ... SQL de otro módulo") (architect H7)
Organization writes platform.business_unit_verticals	src/modules/organization/infrastructure/business-units/business-unit-vertical.repository.ts:22-45 (gone since K10c: the write is src/modules/platform/infrastructure/business-unit-verticals/platform-business-unit-verticals.repository.ts, §6.2)	Same rule (architect H7)
Legacy: sauce groups duplicated per size (×6, ×14, ×25); is_required contradicted min; 72 of 73 options priced 0; client-trusted prices	Owner briefing (legacy study)	Per-variant limits; required = min > 0 (0080_catalog.sql:1628); free defaults are normal; prices always resolved server-side

What the market does (verified sources in §19):

Concept	Who	Used here as
Quantity per option; group limits on the sum; max may exceed the option count when quantities are allowed	Square CatalogModifierList.allow_quantities, max_selected_modifiers	OV5
Per-item override of min/max, enabled, order, receipt visibility	Square CatalogItemModifierListInfo	Offers; per-offer overrides (K14)
Per-item override of one modifier's default and online visibility	Square CatalogModifierOverride	Offer defaults (exist); overrides (K14)
Text modifiers with maximum length and "text required"	Square modifier_type = TEXT, max_length, text_required	Text options (K14c)
Prefixes No / Add / Sub; required and allowed condiment groups with min and max	Oracle Simphony	Prefix hint (K14c)
Size and sequence pricing; portions with a price scale factor	Toast	Pricing's work; portions deferred
minRequired, maxAllowed, showByDefault	Clover	Same model
Modifiers separate from production instructions	Lightspeed K-Series	Prefix is a hint; effect is Production's
Charged once, per night, per person, per person per night	Mews	Pricing's charge basis, never Catalog
Up to 2,048 variants, 3 options per product	Shopify	Variants and structured attributes (H6), not modifiers
Combo choices with extra price	Odoo	Bundles (C22)

---

2. What exists today (as built, revision 93)

Fact	Where
modifier_groups (code, name, description, status)	0080_catalog.sql:1366-1411
modifier_options (kind instruction or catalog_variant with a target, max_quantity 1–999, sort_order, status)	0080_catalog.sql:1470-1574
item_modifier_groups, the offer (item, optional item_variant_id, group, min, max, sort order, status active/inactive); "required is derived from min_selections > 0"	0080_catalog.sql:1622-1704
One offer per (item, group) at item level and per (variant, group) at variant level, every status included	item_modifier_groups_item_scope_uq, _variant_scope_uq, 0080_catalog.sql:1706-1718
Offer defaults with composite FKs to the offer and to an option of the same group	0080_catalog.sql:4411-4488
Runtime may DELETE offers (revoked by K9c, migration 0091, revision 101)	database/access/runtime_grants.sql:118
The catalog version is bumped by statement triggers on 12 catalog tables (catalogs, items, item_variants, item_variant_barcodes, categories, item_categories, modifier_groups, modifier_options, item_modifier_groups, business_unit_catalogs, business_unit_items, item_modifier_group_defaults) plus the row created with each organization	0080_catalog.sql:4139-4272, :4174, :4480-4488
The till answers at most 2,000 items, with no SKU and no barcodes	src/modules/catalog/application/till/sellable-read.ts:7; CATALOG_USE_CASES.md:1450
Admission shares the catalog version row, then the business unit row	CATALOG_USE_CASES.md:1468
Catalog publishes no domain event (no outbox write in src/modules/catalog outside test doubles)	rg over the module; events.outbox_records exists (0360_events.sql:202)
Already correct, not defects: salesQuantityStep is in the published snapshot and the till (catalog-sellable.contract.ts:35-48); preselections live on the offer (item_modifier_group_defaults) since migration 0080, and 0082 dropped modifier_options.is_default	architect §12; CATALOG_USE_CASES.md:1409-1417, :1498

---

3. Decisions

#	Decision	Status	Alternatives weighed	Why
OV1	An offer is the link (item or variant) × group with its rules; its UUID is stable for ever: editing min, max, order or defaults updates the row in place; only a genuinely new link gets a new UUID	Decided (architect H1)	Delete and re-insert (today): breaks FKs	Sales, Commerce and Pricing reference offers
OV2	Offer status vocabulary becomes active | inactive | retired. Retired = no longer offered: kept only for references and history, ignored by every read, sellability and requirement check; re-offering the same group revives the same row (same UUID). Inactive = still offered but suspended (item level) or an explicit opt-out (variant level, OV9)	Decided (architect H1: "retirar ≠ suspender")	Retire as inactive (this document's first draft): requiredGroupsSatisfiable reads it as "required but unavailable" and hides the item	§4.1
OV3	Retired rows stay inside the two partial unique indexes: one row per logical link for ever	Decided (designer), diverging from the instruction to exclude retired rows from the unique indexes	Exclude retired rows (index WHERE status <> 'retired'): a re-offer could insert a second row for the same link instead of reviving, breaking OV1, and two rows would compete for one Pricing key	Revival is deterministic only with the full index; a separate partial index serves the live reads (§4.1)
OV4	Preserving a UUID does not freeze historical rules: Sales freezes names, quantities and charges on its own rows (0110_sales.sql:1187-1199); Pricing keeps dated price rows (0090_pricing.sql:442-443); Catalog keeps only the current rule	Decided (architect note)	Catalog revisions of offers: no consumer needs them while the consumers snapshot	—
OV5	Group min/max count units: the sum of quantity over the offer's selections; maxQuantity bounds one option; quantity is an integer count 1–999	Decided: the Sales SQL is the executable authority (0110_sales.sql:1190, :1271-1274, :4097-4101, :4229-4247)	(a) distinct options: contradicts Sales. (b) both rules in v1: no reader needs it yet	A separate maxDistinctOptions on the offer is Proposed (§4.4)
OV6	A measurable option amount (0.25 kg extra) is not a quantity; it would be a separate, unit-bearing value (§4.4)	Proposed	Decimal quantity: Sales stores smallint; "two nights" or "ten sessions" are counts or a vertical's validity, not measurable modifiers (architect §4)	—
OV7	A preselection is never an accepted selection: the sale command sends what the customer kept; admit never adds defaults	Decided (built in K8, CATALOG_USE_CASES.md:1474; architect §4)	—	—
OV8	The contract answers the effective offer: itemModifierGroupId, modifierGroupId, source: 'item' | 'variant', minSelections, maxSelections; Sales stores the offer admit returned, never one looked up later	Decided (architect H3)	Consumers query catalog.item_modifier_groups: breaks the module boundary	§5
OV9	Effective offer of variant V for group G: an active variant override replaces the item offer; an inactive variant override is an explicit opt-out (G not offered on V, no minimum); a missing or retired override inherits the item offer; an inactive item offer is suspended (if required, the variant is not configurable). One SQL fragment serves the till, the search, the scan, resolve and admit	Decided (owner, via coordinator; the review left the inactive override open)	(a) inactive override inherits (Sales until migration 0090): no way for one variant to drop an item-level group. (b) "offer only on the variants that have it" (first draft): fails when the item-level offer exists for many variants	Sales aligned (X13, migration 0090)
OV10	Overrides replace, never add: the variant rule is not summed with the item rule	Decided (architect H4)	—	—
OV11	A required group is satisfiable when its minimum is at most the sum of the effective maximum quantities of its available options	Decided (architect functional review, F1; built ahead of K9h, §4.2 As built (F1))	Count of options (before F1)	Same arithmetic as OV5
OV12	Catalog reads of Organization and Platform go through owner-published surfaces: TypeScript contracts sharing the opaque TransactionContext by default, and, as a documented normative exception, owner-published SQL read functions for the single-statement hot reads; Organization's vertical activation calls a Platform contract	Recommended (architect H7)	(a) contracts only: the till read and admit would lose their one-statement snapshot and statement budgets (CATALOG_USE_CASES.md:1453). (b) leave as is: violates ARCHITECTURE.md:219	§6
OV13	Option kinds: instruction, catalog_variant, new text; quantity-only = any option with maxQuantity > 1	Recommended	Text as a group type; generic input kind	§4.5
OV14	Prefix (add, extra, light, no, on_the_side, substitute) is a hint on the option; never a sale-time dimension	Recommended	Toast/Oracle pre-modifiers: need a Sales column and a Pricing multiplier	§4.6
OV15	Removed defaults are derived by admit (removedDefaults), not stored by Catalog	Recommended	Negative quantities: Sales refuses them	§4.7
OV16	Defaults carry a quantity; per-offer option overrides exclude an option or lower its maximum, never raise it	Decided; default quantities built in K14a ("K14a as built") and the per-offer option limits in K14b ("K14b as built")	—	Sales checks the option's own max_quantity (0110_sales.sql:4097)
OV17	Runtime availability ("86") of options is Operations'	Recommended	A catalog status flip invalidates every till	0140_operations.sql:4598-4622
OV18	Modules and data stay decoupled: no new cross-schema FK; no copy of a neighbour's fact (price, stock, tracking, tax, discount, channel mapping); neighbours get data through contracts or their own immutable snapshots	Decided (owner)	—	§17
OV19	Variant attributes are structured, neutral dimensions and values with persistent links; the matrix creates them; no shirt_size columns	Decided (architect H6)	Concatenated codes and names (today)	§8
OV20	Offline replay accepts a sale made under an earlier context only on explicit evidence (§7.3)	Recommended; owner question Q4	Re-admit against the current catalog: refuses legitimate past sales (architect H5)	—
OV21	item_kind is Proposed only, with named readers (§17.1) and the constraint that Catalog never decides kitchen, stock, tax or membership from it	Proposed (architect §12)	Add now	No reader exists yet
OV22	The admission line carries its quantity and Catalog judges it against the variant's sales quantity policy	Recommended	Leave to Sales	The policy is a catalog fact (0080_catalog.sql:140-200)
OV23	Portions and nested options: deferred with fixed shapes	Proposed	—	§4.8, §4.9
OV24	The catalog stays abstract and is administered per business unit or per outlet without per-channel flags: the business unit stays the unit of assortment and an outlet may only hide items from it (K16), never sell what its unit does not list	Decided (owner)	—	§10 (K16), §21 ("K16 as built")
OV25	The till read (C17) sends only the categories that hold something the outlet sells now: an item whose primary category is the category or one of its descendants, with the ancestors that lead to it; there is no parameter to show the others, and the till shows its own message from what it receives	Decided (owner), built	Keep empty categories (the earlier decision, so a folder the owner just filled is not hidden before the till refreshes); a flag to show them	CATALOG_USE_CASES.md C17

---

4. Capability model

4.1 Offer identity, retirement and suspension (H1)

States of an offer row.

State	Meaning	Sellability and reads	Sales/Commerce/Pricing see
active	offered	used	a valid target (their triggers require active, 0110_sales.sql:4090-4095, 0100_commerce.sql:1975-1980)
inactive at item level	suspended: still offered, temporarily unavailable	required → variant not configurable; optional → omitted	refused as a new selection; history intact
inactive at variant level	opt-out: group not offered on that variant (OV9)	group omitted for that variant, no minimum	no minimum; a selection through the item offer is refused as not offered (X13, migration 0090)
retired	no longer offered; kept for references	ignored everywhere (never "unavailable", never required)	refused as a new selection; history intact

Transitions. active → retired (the group left the list), inactive → retired (same), retired → active (re-offered: revival, same UUID; its defaults come from the request; the retired row's defaults were deleted at retirement), active ⇄ inactive (suspend / resume; opt-out / opt-in at variant level). A retired row is never deleted (K9c revokes DELETE).

Schema (K9a, expand-only). ALTER TABLE catalog.item_modifier_groups DROP CONSTRAINT item_modifier_groups_status_chk, ADD CONSTRAINT item_modifier_groups_status_chk CHECK (status IN ('active', 'inactive', 'retired')). Widening a CHECK is expand-safe: every existing row still satisfies it, the previous API never writes retired, and K9a ships no writer of retired, so during the rollout no previous-API instance can meet one. Indexes: the two scope indexes stay as they are (OV3); a new item_modifier_groups_live_idx (organization_id, item_id, item_variant_id, sort_order) WHERE status <> 'retired' serves the live reads. The retired offer keeps the FKs of item_modifier_group_defaults valid (none remain: retirement deletes them first).

Queries to fix (K9a: readers; K9b: writer).

Query	Today	Change
requiredGroupsSatisfiable	ro.status <> 'active' makes a required offer unsatisfiable (sellable-rule.queries.ts:62)	Exclude retired rows before judging; keep inactive (item level) as "required but suspended". K9f replaces it with the effective-offer fragment
itemLevelOffer / OFFERS / OFFERED_OPTION_IDS	status = 'active' (sellable.queries.ts:24-60)	Unchanged result (retired is not active); named explicitly in tests
Till groups and items	o.status = 'active' (till-read.queries.ts:111-112, :139-140)	Unchanged result; test that a retired offer never appears
Item read (C3) and the offer audit value	read every item-level row	Exclude retired
Where-used (modifier-group-offers.queries.ts:53-65)	every item-level row	Exclude retired
DELETE_OFFERS / INSERT_OFFERS (modifier-group.queries.ts:158-175)	delete all, insert all	K9b: UPDATE kept links in place (rules, order, status active), UPDATE ... SET status = 'retired' for removed links (after DELETE of their defaults), revive retired links by (item, group), INSERT only new links
Defaults removal on option/group/variant retirement (modifier-group.queries.ts:194-199)	delete from every offer	Unchanged

As built (K9a, migration 0084_catalog_offers_retired, baseline revision 94). The CHECK is widened and item_modifier_groups_live_idx is added exactly as above; the two scope indexes are unchanged (OV3). Three readers now skip retired: requiredGroupsSatisfiable (so the till lists, the search, the scan, resolve and admit keep an item sellable when its required group is retired, and still refuse it while the group is suspended), ITEM_OFFERS (the item read C3, hence the offer audit value and the comparison of the offer command) and the where-used read. The till and contract offer lists already read only active. No statement writes retired: the offer command still deletes and re-inserts every item-level row, retired ones included, so a group re-offered over a retired row gets a new row until K9b. Proofs: database/tests/contracts/catalog-offer-retired-contracts.ts (NINAKU_CATALOG_OFFER_RETIRED_OK) and the C13 rows of CATALOG_CASE_MATRIX.md.

As built (K9b, no migration, baseline revision 95). The offer command writes the item-level offers in place, in four statements under the item lock: it deletes the defaults of the item's offers, retires (UPDATE ... SET status = 'retired') every live link the list leaves out, then one INSERT ... ON CONFLICT (item_id, modifier_group_id) WHERE item_variant_id IS NULL DO UPDATE writes the list: a kept or retired link keeps its UUID and takes the rules, the place and active; only a new link gets a UUID; then it inserts the requested defaults. No statement deletes an offer row. The command judges a retired group like a new one (it must be active and the change is gated), since the item read leaves it out. The audit value is offerId:groupId:min:max:status, followed by the sorted defaults as before; the after list ends with the offers the change retired. ItemModifierGroup carries the offer id and status inside the application only: the item answer is unchanged. Not built in K9b: the suspended flag of §4.3 on the item route, which changes the request and the item answer and so the generated OpenAPI document (docs/generated/openapi.json); suspension is still written only in SQL. Proofs, with real referencing rows: a Pricing modifier_option_price_entries row survives an edit and a retirement of its offer; a Sales-shaped row (a test table whose foreign key copies the three real ones, each checked to be NO ACTION) survives a retirement, because a Sales or Commerce row needs an order or a cart with a dozen unrelated parents; the rollback test makes the audit record fail after the write and finds the offers, their ids, the item tag and the trail unchanged. Rows in CATALOG_CASE_MATRIX.md, C13. Rollout: no migration; the previous API (K9a) already ignores retired rows, so it reads correctly what K9b writes, but it still deletes and re-inserts the offers it edits: until every instance runs K9b an edit served by an old instance gives new ids, which is why Sales, Commerce and Pricing reference offers only after K9b is deployed and K9c revokes DELETE after that.

As built (K9c, migration 0091_catalog_offers_are_never_deleted, baseline revision 101). The contract step after K9b: the migration revokes DELETE on catalog.item_modifier_groups from ninaku_runtime, and database/access/runtime_grants.sql no longer grants it, so a fresh install and an upgraded database end with the same privileges (SELECT, INSERT, UPDATE). The runtime keeps DELETE on item_categories and on item_modifier_group_defaults (the offer command deletes the defaults of the offers it retires), and holds no DELETE on items, item_variants or modifier_groups, so no cascade reaches an offer either. A runtime DELETE of an offer, referenced or not, active, inactive or retired, fails with 42501; retiring, reviving and editing in place are UPDATEs and keep working. Only the administrator can still delete an offer (the contracts that prove the version trigger and the cascade to the defaults on delete now run as the administrator). Proofs: database/tests/contracts/catalog-offers-never-deleted-contracts.ts (NINAKU_CATALOG_OFFERS_NEVER_DELETED_OK). Rollout: the migrator runs first; revoking a privilege is irreversible only in that an image older than K9b, which deletes and re-inserts the offers of an item, would now fail that edit with 42501 (the whole edit rolls back, nothing is lost); the owner confirmed that staging and production run K9b, so no running instance deletes an offer.

Audit and events in the same transaction. One catalog.item.modifier_groups_set record per real change (as today), its value listing each offer as offerId:groupId:min:max:status; since K12a (built) the same transaction writes catalog.offer.changed events with the offer id and its new status, and a tombstone retiredAt when the offer is retired, into events.outbox_records through events.append_tenant_event, so a rollback leaves no row, record or event.

Acceptance criteria (architect §3).

Case	Required result	Planned test
Edit the maximum of O1	O1 keeps its UUID	test/e2e/catalog-modifier-offer-identity.e2e-spec.ts › keeps the offer id when its maximum changes
Reorder the offers	no existing link changes UUID	test/e2e/catalog-modifier-offer-identity.e2e-spec.ts › keeps every offer id when the offers are reordered
Add O2	only O2 gets a new UUID	test/e2e/catalog-modifier-offer-identity.e2e-spec.ts › gives a new id only to a newly offered group
O1 has a specific price (a Pricing-shaped referencing row)	the edit succeeds and the reference stays valid	src/modules/catalog/infrastructure/modifiers/modifier-group.repository.integration-spec.ts › edits and retires an offer that a pricing row references without breaking the reference
O1 has historical sales (a Sales-shaped referencing row)	history stays readable; retiring O1 succeeds	src/modules/catalog/infrastructure/modifiers/modifier-group.repository.integration-spec.ts › retires an offer that a sale row references and keeps the row readable
Retire a required O1	the item stays sellable; never read as "required but unavailable"	test/e2e/catalog-till-parity.e2e-spec.ts › keeps an item sellable after its required group is retired, but not after it is suspended
Re-offer a retired group	the same UUID returns to active	test/e2e/catalog-modifier-offer-identity.e2e-spec.ts › revives the same offer id when a retired group is offered again
Rollback of the edit	no link, audit record or event partially written	test/e2e/catalog-modifier-offer-identity.e2e-spec.ts › leaves the offers, their ids, the audit trail, the announced changes and the version untouched when the record fails after the write (built in K9b against PostgreSQL; since K12a it also proves that no event, outbox row or version move survives the rollback, and that the successful command announced its changes)
Runtime deletes an offer (after K9c)	42501	database/tests/contracts/catalog-offers-never-deleted-contracts.ts › NINAKU_CATALOG_OFFERS_NEVER_DELETED_OK (built in K9c)

4.2 Effective offers (H3, H4)

effective(V, G), for variant V of item I and group G offered on I or on V:
  if a variant row (V, G) exists with status 'active'   -> that row      (source 'variant')
  if a variant row (V, G) exists with status 'inactive' -> not offered    (opt-out)
  otherwise (no variant row, or a retired one):
    item row (I, G) 'active'   -> that row                                (source 'item')
    item row (I, G) 'inactive' -> suspended: min > 0 makes V not configurable; else omitted
    item row (I, G) 'retired' or missing -> not offered
order: sort_order of the effective row, then source 'variant' first, then id

Case (architect H4)	Result
Active override	replaces the item offer for that group
Missing override	inherits
Inactive override	explicit opt-out (OV9)
Required group with no available option (or fewer units than the minimum, OV11)	that variant is not sellable; the other variants of the item stay sellable
The till (C17), the search (C19), the scan (C18), resolve and admit	the same fragment, proven by one parity test

Example (architect): wings item, group Sauces, item rule max 2; variant ×6 inherits (2); variant ×25 has an active override max 6; variant ×3 has an inactive override (no sauces).

Sellability becomes per variant: an item is listed when at least one of its active variants is configurable; a variant that is not configurable is left out of variants[] in C17 and C19, refused by C18 like an unknown code, and refused by admit with required_modifier_unsatisfiable.

As built (K9f, no migration). The rule is one SQL fragment, effectiveOffer(offer, variant) in infrastructure/reads/sellable-rule.queries.ts: an offer row of the variant's item that is not retired and either belongs to the variant and is active, or is item-level with no live (active or inactive) row of the variant for the same group; the override probe uses item_modifier_groups_variant_scope_uq. variantConfigurable(variant) judges the required groups among those rows (a suspended item row, an inactive group or too few available options makes the variant not configurable), configurableVariantExists(item) lists an item while one active variant is configurable, and sellableVariant(scope, variant) is the verdict of the scan, resolve and admit. The till list and the search (C17, C19) keep only configurable variants in variants[] and count an item in omittedItems only when none is; the scan (C18) answers null for an unconfigurable variant; resolve and admit answer the effective offers of the requested variant, source: 'variant' and the override's id when it applies, in the order of this section, and the options an opted-out group holds answer option_not_offered. Proofs: test/e2e/catalog-variant-modifier-offers.e2e-spec.ts runs one table of cases (inherit, active override, opt-out, unsatisfiable required override, unsatisfiable inherited group, opt-out of it, retired override) through the scan, the till, the search, resolve and admit and finds the same verdict; the planned parity titles live there instead of catalog-till-parity.e2e-spec.ts, which is already at the file-size limit. The Sales rows built from an admitted active override pass the real Sales trigger and group check and fail with the item offer id. X13 is closed (K9g-0, migration 0090, baseline revision 100):sales.validate_line_modifier_insert and sales.assert_order_line_modifier_consistency choose the variant row among active and inactive first and only then drop the group when it is inactive, ignoring retired rows, so a variant that opted out of a required item-level group is admitted by Catalog with no selection and stored by Sales with no selection, and a selection through the item offer on that variant is refused with 23514 (Modifier Group is not offered on selected Order component Variant). Proofs: the opt-out parity case of the e2e file above and database/tests/contracts/sales-variant-offer-contracts.ts (active override, opt-out, retired override, inherited, suspended item offer and item-only offer against the real Sales functions). Variant rows are written by the K9g route (§4.3). EXPLAIN (ANALYZE, BUFFERS) on a local world of 20,000 items × 2 variants (two item offers each, 30 % with an active override, 10 % with an opt-out), in a rolled-back transaction as ninaku_runtime: the till read (2,000 items) went from 195 ms and 485,562 buffers to 230 ms and 607,577; resolve of 100 variants from 13 ms and 7,763 buffers to 11 ms and 8,037. One machine, not a capacity claim; perf:http must be re-run for C17 and C19.

As built (F1, satisfiability by units, no migration). The architect's functional review (F1) asked to bring forward the part of K9h that judges a required group by units; this fix delivers it. The effective maximum of an option was its own maxQuantity until per-offer limits could lower it (OV16); K14b did, and the same sum now takes the lower of the option maximum and the limit of that offer (see "K14b as built"). What a group can give an offer is the sum of the maxQuantity of its available options under the one availability rule (active option; for a catalog_variant option an active target variant of an active item, the structural activeOption of the writes; the reads add, since K16b, that the target is listed and shown, availableOption), the arithmetic of admit (K9d) and of sales.assert_order_line_modifier_consistency. Three places used to count options and now sum units, so they agree: the offer command (C13), whose SHARE_LOCK_GROUPS now hands judgeOffer every available option with its maxQuantity (before: the count of active options, which ignored the target of an extra) and whose domain rule refuses a minimum above that sum with selection_rule_invalid; variantConfigurable, the one fragment of the till, the search, the scan, resolve and admit, whose required-group test compares the minimum with coalesce(sum(max_quantity), 0) of the available options instead of count(*). The offer's own maximum caps nothing here: the minimum is never above it, and a maximum above the reachable units stays accepted as before (Square's allow_quantities rule, OV5; admit judges each option on its own maximum). Option writes still do not judge offers again (K5 design note): deactivating or archiving an option, pausing an extra's target or lowering a maxQuantity below an offered minimum succeeds, and the item leaves every reader with required_modifier_unsatisfiable until the units come back, while a changed rule with that minimum is refused by the command, so both ends use the same sum. The public activeOptionCount of the group reads (C12) is unchanged: it is a count shown to the back office, not a capacity. Proofs: test/e2e/catalog-unit-capacity.e2e-spec.ts (one Cheddar of maximum 2 offered with minimum and maximum 2 is accepted, sold by the scan, the till, the search and resolve, admitted × 2 and stored by the real Sales checks, refused × 1 and × 3; Gouda deactivated then archived keeps the item on sale; Cheddar lowered to 1 hides it everywhere and the minimum of two is refused again; an extra worth two units behind a paused item counts nothing), src/modules/catalog/domain/modifiers/modifier-offer.spec.ts › accepts a minimum that the available options can reach through their quantities, and the statement tests of SHARE_LOCK_GROUPS and variantConfigurable; reverting any of the three places to a count fails a named test. Rollout: no migration, no response shape changed; an offer stored in SQL whose minimum only units can reach becomes sellable, and an offer the command accepted before can only gain capacity, except one that counted an extra behind a paused target, which the readers already treated as unavailable.

4.3 Per-variant offers: writing them

PUT /catalog/items/{itemId}/variants/{variantId}/modifier-groups (K9g; since API v7 PR 5 the variantOverrides of the item route, see below) takes the same body as the item route plus a per-group optedOut: boolean (writes an inactive variant row). The item route gains a per-group suspended: boolean (writes an inactive item row). Both follow OV1–OV3. Archiving a variant leaves its overrides as they are (the variant is not sellable); archiving the item retires nothing (history).

As built (K9g, no migration). The item route and the new variant route share one command (OfferModifierGroupsUseCase, with an optional variantId) and one writer (infrastructure/modifiers/item-offer-writes.ts) whose three statements are generated per scope: the item scope keeps the K9b statements (item_variant_id IS NULL, ON CONFLICT (item_id, modifier_group_id) WHERE item_variant_id IS NULL), the variant scope binds the variant and upserts by item_modifier_groups_variant_scope_uq, so a kept, retired or opted-out link keeps its UUID in both (OV1–OV3); the upsert now writes the status of each row (active, or inactive for suspended/optedOut). Domain (domain/modifiers/modifier-offer.ts): an offer carries inactive; an opt-out is normalised to 0, 1 and no defaults and is never judged beyond the group existing (an inactive or archived group may be opted out of); a suspension of a kept offer whose rule is unchanged is not judged again, but every transition to active (a new offer, a resume from a suspension, an opt-in from an opt-out) judges the group status (422 · catalog.modifier_group_not_active) and the rule again, so no sequence of requests makes an inactive or archived group an active offer (review fix; only an offer that stays active with its rule keeps a group deactivated since). Plan: isUngatedOffer replaces isShrinkingOffer: a list is ungated when every group sent is unchanged or a free restriction and it drops a group or restricts one; on a variant an opt-out is always free, on the item a suspension only with the stored rule; an override, an opt-in, a resume and a pure reorder stay gated. The variant must belong to the item (404 · catalog.not_found otherwise, the same answer as unknown or foreign), an archived variant answers 422 · catalog.variant_archived (refuseAnArchivedVariant, as the variant and barcode commands), an inactive one may be configured; If-Match and the answer use the item ETag, a hash of the item read, which now holds the variant offers. Audit: no new action type (the action types are rows of audit.action_types, a migration): the variant route records catalog.item.modifier_groups_set on the item with catalog.item.variant (the variant id, before and after) and catalog.item.variant.modifier_groups (offerId:groupId:min:max:status lists). Reads: the item read (C3) reads every live row in its one offer statement and answers suspended on each item group and variants[].modifierGroupOverrides (optedOut plus the full group shape); the where-used read answers variantId (null for the item offer), lists active overrides but never an opt-out, and its keyset tie-break is now the offer id instead of the item id, so a cursor issued before the deploy may skip or repeat one row of a page once. Till (§5.2): C17 and C19 answer variants[].modifierGroupOverrides only on a variant with an opt-out or an active override whose group has an available option (its rows are chosen by liveVariantOffer, the same fragment effectiveOffer uses to let a variant row replace the item offer, so the till and admit cannot disagree on which rows count), and no key otherwise (zero bytes for an item without overrides, proven by the till e2e); the top-level modifierGroups include groups offered only by an active variant row; the ETag is unchanged (the catalog version moves on every offer write); the statement count is unchanged (one correlated subquery per listed variant, probing the variant scope index). Proofs: the K9g rows of CATALOG_CASE_MATRIX.md (C3, C12, C13, C17, C19). Sales parity of an opt-out written by the route (X13 closed by K9g-0, migration 0090): test/e2e/catalog-variant-offer-sales-parity.e2e-spec.ts writes the opt-out through the variant route, then admit answers no offer for that variant and the real Sales trigger and group check store its line with no selection and refuse a selection through the item offer, while the variant that inherits keeps the item minimum in both. Still open: K9c (revoke DELETE on offers) and a perf:http re-measure of C17 and C19. The new route is classified administrative and unmeasured in tooling/performance/http/route-classification-catalog.ts. Rollout: no migration; the previous API (K9f) reads variant rows and suspended item rows correctly, but its item route sets every row it keeps back to active (it knows no suspended), so a suspension made by a K9g instance can be undone by an edit served by a K9f instance until every instance runs K9g; and the two versions hash a different item read, so an If-Match taken from one version answers 412 on the other during the rollout (re-read and retry).

4.4 Quantity semantics (H2)

Concept (architect §4)	Example	Treatment here
Base quantity of a variant	0.25 kg	Existing decimal sales policy (0080_catalog.sql:153-187); judged by admit (OV22)
Count of an option	2 shots, 2 extras	quantity, integer 1–999 (OV5)
Measurable amount of an option	0.25 kg extra	Proposed (OV6): an option flag measured_unit_code plus measured_min, measured_step, measured_max; the selection carries amount (decimal string) instead of quantity; Sales needs amount and amount_unit_code columns; Production multiplies its add effect by it (0180_production.sql:6285-6289)
Validity of a service	a one-month membership	The Gym vertical's rule, not a quantity

Rules: group min/max on the sum of units; quantity ≤ the option's effective maximum; one option at most once per line; a preselection is not a selection (OV7). Proposed extension: maxDistinctOptions on the offer ("up to 2 different sauces, up to 4 portions in all"), judged beside the unit rule, when an owner names a menu that needs it.

Acceptance criteria (architect §4), all in K9d:

Case	Result
Cheese × 2	expressed once with quantity: 2, admitted when min ≤ 2 ≤ max
Same min/max in contract and SQL	proven by the parity database contract (§9.4)
Quantity above maxQuantity	option_quantity_above_maximum
Repeated option, quantity 0, negative, non-integer, malformed id	CatalogSellableRequestInvalidError (duplicate, invalid_quantity) before any SQL
Preselection	never added by admit; the command sends what was kept
Measurable amounts	not accepted in v1 (invalid_quantity for a decimal)

As built (K9d, no migration, baseline revision 95). AdmissionLine is { variantId, quantity, selections: [{ optionId, quantity }] } and each admitted line answers { snapshot, quantity, selections }: the line quantity in its shortest decimal form and the selections as sent (ids lowercase), so a preselection is never added (OV7). Before any lock: a line quantity that is not a positive decimal of at most 14 integer digits and 6 decimals, or a selection quantity that is not an integer from 1 to 999, throws invalid_quantity; an option twice in a line, in any case, duplicate; more than 100 selections too_many_options. Per line, after the sellable verdict: quantity_out_of_policy when the quantity is below the variant minimum, above its maximum or (quantity − minimum) mod step ≠ 0, the rule of the Sales order-line trigger (0110_sales.sql:3515-3527), computed exactly on integers scaled by 10⁶ (no decimal.js wrapper exists in foundation/ yet); then per selection, in request order, option_not_offered, option_unavailable or option_quantity_above_maximum (the effective maximum of the option in its offer: its own maxQuantity, lowered by the limit of that offer since K14b); then per offer selection_below_minimum or selection_above_maximum on the sum of units. A malformed option id still answers option_not_offered without reaching SQL, as in K8: the only new request problem the design names is invalid_quantity. Parity proof: test/e2e/catalog-sellable-quantities.e2e-spec.ts builds, in a rolled back admin transaction, a Sales order and line (only those two parents inserted with session_replication_role = replica, so their foreign keys and triggers are skipped), inserts the modifier rows a sale would store through the real sales.validate_line_modifier_insert trigger and calls the real sales.assert_order_line_modifier_consistency: for ten selections Sales accepts exactly what admit admits, and counting distinct options instead of units breaks the test. The line policy is not run through the Sales order-line trigger (skipped with the parents); the domain test proves the copied rule. Not built in K9d (K9e): offers[] with the effective offer identity, lineIndex, removed and reduced defaults, the database/tests parity contract and the remaining MODULE_CONTRACTS.md sentences of §16. Rows in CATALOG_CASE_MATRIX.md, C20. Rollout: no migration and no consumer yet besides the contract's test module and the perf:admission sale generator, so no compatibility window.

4.5 Option kinds

Kind	Meaning	Physical effect owner	Price owner
instruction	"No onion", "Medium rare", "Gift wrap"	production.recipe_modifier_effects (0180_production.sql:1237-1430), instruction options only (:4312-4317)	Pricing; 0 when no row (0090_pricing.sql:427-428)
catalog_variant	"Extra cheese", "Warranty 2y"	the target variant's stock link (0170_inventory.sql:410-460) or recipe	Pricing; the target's price when no row (0090_pricing.sql:429)
text (K14c)	engraving, cake message	none	Pricing, like an instruction

Text: textMaxLength 1–500, required for text only; a chosen text option carries a non-blank value without NUL or control characters; optional text = a group with min 0; quantity exactly 1; at most 10 text selections per line. Built in K14c (the option) and K14d (the selection): "K14c as built", "K14d as built".

4.6 Prefixes

Prefix	Production effect it names (0180_production.sql:1232-1235)	Rule
add	add	any quantity
extra	add (quantity multiplies, :6285-6289) or scale	scale needs quantity 1
light	scale < 1	maxQuantity = 1
no	remove	maxQuantity = 1, instruction only
on_the_side	none (kitchen hint)	maxQuantity = 1, instruction only
substitute	replace	maxQuantity = 1, instruction only

Production refuses remove/replace/scale unless the sale quantity is 1 (0180_production.sql:6300-6304).

4.7 Defaults and removal of a default

admit answers per effective offer removedDefaults (available defaults not selected) and reducedDefaults (selected with less quantity). Sales cannot persist a removed default today (quantity BETWEEN 1 AND 999, 0110_sales.sql:1271-1274; X4). Until it can, a removal the kitchen must see is modelled as a "No X" option. Default quantities (quantity on item_modifier_group_defaults) are built in K14a (see "K14a as built"): a default counts its quantity against the maxSelections of the offer and reducedDefaults names a default chosen with less than that quantity. Since K14b a default cannot be an option limited to 0 in its offer and its quantity cannot exceed the effective maximum of the option there.

4.8 Portions (deferred)

Needs a portion table per offer, a portion_code on the Sales and Commerce modifier rows, a uniqueness of (line, offer, option, portion) instead of order_modifier_options_base_selection_uq (0110_sales.sql:1309-1315), and a Pricing scale factor. Pattern meanwhile: two groups ("Toppings – 1st half", "– 2nd half").

4.9 Nested options (deferred)

Shape: catalog.modifier_option_offers (id, organization_id, catalog_id, parent_modifier_option_id, modifier_group_id, min_selections, max_selections, sort_order, status) with the same retire/suspend vocabulary, depth ≤ 2; the contract's selection gains child selections[]; Sales and Commerce need a parent_modifier_selection_id. Pattern meanwhile: bundles (C22).

4.10 Availability, allergens, routing, receipt, translations, tax, charge basis

Topic	Owner and mechanism
Option sold out at an outlet	catalog_variant: Operations on the target variant (0140_operations.sql:4598-4622); instruction: Operations twin table (Q2)
Option only at some business units	per-item or per-variant offers; per-option assortment Proposed
Option per daypart	menus (OD7)
Allergens of options	inherited from the target item for extras; instruction options wait for catalog_food (R12)
Kitchen routing	Kitchen (0150_kitchen.sql:607-637, :725-735); Catalog adds printsOnKitchenTicket (K14c)
Receipt	printsOnReceipt (K14c); Printing lays out
Translations	C23 (0080_catalog.sql:1413, :1576)
Tax	per variant (0260_tax.sql:646-663); no tax hint in Catalog
Charge basis (once, per night, per person, percentage)	Pricing; not expressible today (X6)

---

5. Contract shapes (H2, H3)

5.1 Admission (K9d, K9e)

admit(context, {
  businessUnitId,
  lines: [{                               // ≤ 100
    variantId,
    quantity,                             // decimal string, sales policy (OV22)
    selections: [{ optionId, quantity }]  // ≤ 100, integer 1..999, each option once
  }]
})
→ {
  catalogVersion,
  lines: [{
    lineIndex, snapshot, quantity,
    offers: [{                            // the effective offers of the variant (§4.2)
      itemModifierGroupId,                // stable (OV1); what Sales, Commerce, Pricing reference
      modifierGroupId,
      source,                             // 'item' | 'variant'
      minSelections, maxSelections,
      groupNameSnapshot,
      selections: [{ modifierOptionId, optionNameSnapshot, kind, quantity,
                     targetVariantId, targetSalesUnitCode }],
      removedDefaults: [{ modifierOptionId, optionNameSnapshot, defaultQuantity }],
      reducedDefaults: [{ modifierOptionId, optionNameSnapshot, defaultQuantity, quantity }]
    }]
  }]
}

resolve answers the same offers[] shape (without selections) inside each snapshot, so Pricing configures against the same identities.

Refusals, in order per line: today's sellable verdict (domain/sellable/sellability.ts:44-77); quantity_out_of_policy (new); option_not_offered; option_unavailable; option_quantity_above_maximum (new); selection_below_minimum / selection_above_maximum on the sum of units. Request problems: empty, too_many, too_many_options, duplicate (an option twice in a line), invalid_quantity (new). Whole or nothing, as today; the same two shared locks.

Sales mapping (0110_sales.sql:1177-1307).

Sales column	From
item_modifier_group_id	offers[].itemModifierGroupId
modifier_option_id	selections[].modifierOptionId
group_name_snapshot, option_name_snapshot	the snapshots
quantity	selections[].quantity
quantity_unit_code_snapshot	targetSalesUnitCode (required for catalog_variant, forbidden for instruction, :4103-4118)
charges	Pricing

As built (K9e, no migration, baseline revision 96). The snapshot of resolve carries offers[] instead of modifierGroups[]: each offer is { itemModifierGroupId, modifierGroupId, source, name, minSelections, maxSelections, defaultOptionIds, options }, and each option adds targetSalesUnitCode, the sales unit of its target variant (null for an instruction), read in the same statement. Each admitted line is { lineIndex, snapshot, quantity, offers }; every effective offer of the variant is answered, with or without selections, as the shape above (groupNameSnapshot, selections, removedDefaults, reducedDefaults), the selections in request order. The flat selections of K9d is gone: the offer holds them. The derivation is one domain function (domain/sellable/admitted-offer.ts): a removed default is an available preselection the line left out, a reduced one a preselection chosen with less than its default quantity; every default counted 1 until K14a gave defaults a quantity (a default without an entry in defaultQuantities still does), and a default no longer available is never named. The effective offer is the item-level offer: the reads still take only item_variant_id IS NULL rows, so source is always item; the override, opt-out and suspension rule of §4.2 is K9f, and until then a variant-level row (only writable in SQL) is invisible to Catalog while Sales already prefers an active one (0110_sales.sql:4120-4134), and Sales still lets an inactive variant row fall back to the item offer (X13). Parity proof: the K9d e2e harness, not the planned database/tests contract (that path is outside this slice's surfaces): test/e2e/catalog-sellable-offers.e2e-spec.ts builds Sales modifier rows from the admitted answer alone (offer id, group and option names, quantity, quantity_unit_code_snapshot from targetSalesUnitCode) for an instruction and a catalog_variant extra, and the real sales.validate_line_modifier_insert trigger and sales.assert_order_line_modifier_consistency store them; answering the group id instead of the offer id, or no unit for the extra, breaks it. MODULE_CONTRACTS.md takes the sentences of §16 (the effective-offer sentence qualified with "until K9f, source is always item") and the X12 correction. Rows in CATALOG_CASE_MATRIX.md, C20. Rollout: no migration; the contract has no consumer yet besides its test module and the perf:admission generator, so renaming modifierGroups to offers and moving the selections into the offers needs no compatibility window. Sales and Pricing may call admit from now on (§11).

5.2 Till

C17 keeps item-level modifierGroups per item and adds, only on variants that have overrides, variants[].modifierGroupOverrides: [{ modifierGroupId, optedOut, minSelections, maxSelections, defaultOptionIds }] (a delta). The offer id is not sent to the till; the till sends option ids, admit resolves the offer.

Not built in K9f, built in K9g (§4.3, As built (K9g)):modifierGroupOverrides on each listed variant that overrides or opts out, absent otherwise, so the till shows on each variant the rule admit judges.

5.3 What each neighbour receives

Neighbour	Receives through the contract	Never receives
Pricing	itemModifierGroupId, source, modifierOptionId, kind, targetVariantId, quantity	a price
Discounts	modifierGroupId, modifierOptionId, variantId, itemId (targets at 0090_pricing.sql:1638-1720)	rules
Inventory	targetVariantId × quantity for extras	stock
Production	modifierOptionId × quantity for instructions	recipes
Tax	line variant, targetVariantId	classes
Commerce	the same admission shape	—

---

6. SQL ownership (H7)

6.1 Accesses to replace

Catalog file	Owner table read	Use
infrastructure/items/item.queries.ts:84	organization.business_units	unit exists (filters)
infrastructure/sellable/sellable.queries.ts:69, :109	organization.business_units	unit operable; admission share lock
infrastructure/barcodes/barcode-lookup.queries.ts:18-22, :66	organization.effective_business_unit, outlets, sites	outlet → unit on the site date
infrastructure/assortment/assortment.queries.ts:3, :55	organization.business_units	unit state
infrastructure/reads/item-list.queries.ts:64	organization.business_units	listed filter
infrastructure/reads/catalog-read.queries.ts:49-50	organization.business_units, platform.business_unit_verticals	workspace units and verticals
infrastructure/till/till-read.queries.ts:43, :187	organization.structure_versions	till ETag
Organization: business-unit-vertical.repository.ts:22-45 (gone since K10c; Platform owns the write in platform-business-unit-verticals.repository.ts)	writes platform.business_unit_verticals	vertical activation

Also a catalog trigger on organization.organizations creates each organization's version row (0080_catalog.sql:4174).

6.2 Recommendation (OV12)

Default: in-process read contracts sharing the opaque TransactionContext (src/foundation/database/transaction-context.ts:13), exactly like TenantAuditContract. New, in src/modules/organization/contracts/ (the directory does not exist yet) and src/modules/platform/contracts/:

export abstract class OrganizationContextContract {
  abstract businessUnitStates(
    context: TransactionContext,
    input: { readonly businessUnitIds: readonly string[] },
  ): Promise<readonly BusinessUnitState[]>;
  abstract outletOperatingContext(
    context: TransactionContext,
    input: { readonly outletId: string },
  ): Promise<OutletOperatingContext | null>;
  abstract shareBusinessUnit(
    context: TransactionContext,
    input: { readonly businessUnitId: string },
  ): Promise<boolean>;
}
export interface BusinessUnitState {
  readonly businessUnitId: string;
  readonly name: string;
  readonly status: string;
}
export interface OutletOperatingContext {
  readonly outletId: string;
  readonly outletStatus: string;
  readonly siteLocalDate: string;
  readonly businessUnitId: string | null;
  readonly structureVersion: number;
}

export abstract class BusinessUnitVerticalsContract {
  abstract activeVerticals(
    context: TransactionContext,
    input: { readonly businessUnitIds: readonly string[] },
  ): Promise<readonly BusinessUnitVertical[]>;
  abstract activate(
    context: TransactionContext,
    input: BusinessUnitVertical,
  ): Promise<BusinessUnitVerticalChange>;
  abstract deactivate(
    context: TransactionContext,
    input: BusinessUnitVertical,
  ): Promise<BusinessUnitVerticalChange>;
}
export interface BusinessUnitVertical {
  readonly businessUnitId: string;
  readonly verticalCode: string;
}
export interface BusinessUnitVerticalChange {
  readonly outcome: 'changed' | 'unchanged' | 'unavailable' | 'last_active_vertical';
  readonly previousStatus: 'active' | 'inactive' | null;
}

Catalog's workspace, item list, assortment and the back-office reads call these (one extra statement each, within their budgets). Organization's vertical command calls BusinessUnitVerticalsContract.activate/deactivate in its own transaction; Platform owns the SQL.

Normative exception, documented in ARCHITECTURE.md §7 and MODULE_CONTRACTS.md: the single-statement hot reads (C17, C18, C19, resolve, admit) may call only owner-published SQL read functions, never owner tables: organization.outlet_operating_context(p_organization_id uuid, p_outlet_id uuid) RETURNS TABLE (outlet_id uuid, outlet_status varchar, site_local_date date, business_unit_id uuid, structure_version bigint) STABLE and organization.business_unit_is_operable(p_organization_id uuid, p_business_unit_id uuid) RETURNS boolean STABLE (written by Organization in its own migration, granted to ninaku_runtime, SECURITY INVOKER so RLS applies, covered by its contract tests). The admission share lock goes through OrganizationContextContract.shareBusinessUnit (one statement, as today). Why the exception: these reads take one snapshot for data, tree, groups and versions (CATALOG_USE_CASES.md:1453); splitting them would break the ETag-to-body guarantee. organization.effective_business_unit is already such a function; the exception names the rule it follows.

As built (K10a, migration 0092, baseline revision 102). Organization publishes OrganizationContextContract exactly as written above (src/modules/organization/contracts/organization-context.contract.ts, named input interfaces instead of inline object types), bound in OrganizationModule and exported, with OrganizationModule re-exported from src/modules/organization/contracts/organization.module.ts. Platform publishes BusinessUnitVerticalsContract with activeVerticals only (src/modules/platform/contracts/business-unit-verticals.contract.ts); activate and deactivate arrive with K10c, which moves the writes. The two SQL functions have the signatures above, SECURITY INVOKER, search_path fixed to pg_catalog, pg_temp, EXECUTE for ninaku_runtime only; outletOperatingContext reads organization.outlet_operating_context, so the contract and the hot reads share one definition. Catalog does not call any of them yet (K10b). Proofs: database/tests/contracts/organization-published-reads-contracts.ts (NINAKU_ORGANIZATION_PUBLISHED_READS_OK, parity with the inline fragment Catalog runs today), the integration specs of both repositories and test/e2e/organization-published-read-contracts.e2e-spec.ts (a module that imports only the contracts). Open for K10b: the workspace read (catalog-read.queries.ts:46-56) needs every active unit of the organization and its verticals, but businessUnitStates and activeVerticals take unit ids, so K10b needs a way to list the active units (a new OrganizationContextContract method, or businessUnitStates without ids) before it can drop organization.business_units there. K10b should call the functions through scalar subqueries ((SELECT organization.business_unit_is_operable(...))) so PostgreSQL evaluates them once per statement.

As built (K10b, no migration). Catalog names no table or function of Organization or Platform outside the published functions. The hot reads (C17, C18, C19, resolve, admit) call them inside their existing statements: assortmentModeAt and listedAt (infrastructure/reads/item-list.queries.ts) take the unit's operability as an SQL expression, and the hot reads pass operableUnit (infrastructure/reads/sellable-rule.queries.ts, (SELECT organization.business_unit_is_operable(org, unit))); OUTLET_STATE, OUTLET_EXISTS and MATCH_AT_OUTLET read organization.outlet_operating_context, and the till list joins it on its outlet ($5) for the structure version of its ETag. The statement counts of test/e2e/statement-budget.e2e-spec.ts are unchanged. admit shares the unit row through OrganizationContextContract.shareBusinessUnit (one statement, as before). The other reads go through the contracts: CatalogBusinessUnits (application/catalog-business-units.ts, over businessUnitStates) answers the read gates' unknown-unit check (one statement, as before), the unit status in the assortment ETag (one more statement per read, one more per command) and the operability behind the item list's listed filter, now a $N::boolean parameter (one more statement, only with that filter). The workspace warning units_with_different_verticals left WORKSPACE_FACTS: WorkspaceVerticals (application/reads/workspace-verticals.ts) asks OrganizationContextContract.activeBusinessUnits (new in K10b) and passes their ids to BusinessUnitVerticalsContract.activeVerticals, and the use case compares each unit's set of active verticals, only for an organization-wide curator, the only reader who ever saw the warning. That is no extra statement for any other reader, one for a curator in an organization with at most one active unit (Platform is not asked) and two otherwise; the workspace has no entry in the statement-budget e2e. A published SQL function would have kept one statement, but the workspace is not one of the single-statement hot reads §4.4 of MODULE_CONTRACTS.md names, so it uses the contracts. test/e2e/catalog-workspace-parity.e2e-spec.ts compares the catalog, the counts and the warnings with the statement that answered them before K10b through six mixes of units and verticals. The lint npm run lint:sql-ownership (tooling/repository/check-sql-ownership.ts, spec beside it) fails on any production SQL of a module that names another module's objects, outside the published functions, the tenant context functions and reference; the references other modules still hold are frozen in tooling/repository/sql-ownership-baseline.json, which only shrinks and holds no Catalog entry.

As built (K10c, no migration). BusinessUnitVerticalsContract gained activate and deactivate as sketched above, with one deviation: instead of { changed, status } they answer { outcome, previousStatus }, where outcome is changed, unchanged, unavailable or last_active_vertical (a const object in the contract file). Organization needs the previous status for its audit record (null for a first activation, inactive for a reactivation), Platform cannot throw Organization's failures, and Organization's use case does not catch, so the refusals travel as outcomes and Organization throws the same organization.vertical_unavailable (422) and organization.last_vertical_required (409) as before. Platform binds the contract to BusinessUnitVerticalsFacade (src/modules/platform/application/business-unit-verticals/), which hands reads to ReadBusinessUnitVerticalsUseCase and changes to ChangeBusinessUnitVerticalStatusUseCase; the SQL moved to PlatformBusinessUnitVerticalsRepository with three changes: every statement names (SELECT identity.current_organization_id()) (the insert takes it as the organization, the reads, the update and the lock filter by it, and the advisory lock key is the same organization.verticals:<id> the business unit trigger takes), the lock of the active rows filters with organization.business_unit_is_operable(...) instead of joining organization.business_units, and a write the database refuses as an unknown or unavailable vertical answers false instead of throwing. The write stays in Organization's tenant transaction, with its audit record. Statements per request: activation of a new pair or a reactivation 4 from Platform (advisory lock, catalog, status, write) plus the same permission, unit lock and audit as before; an activation already active 3; a deactivation 4 (status, advisory lock, FOR UPDATE, update); a deactivation already inactive 1; the last vertical 3; all unchanged. An activation on an inactive or archived unit is now refused before the catalog read (one statement fewer). src/modules/organization/infrastructure/business-units/business-unit-vertical.repository.ts is gone with its baseline entry, so Organization names no Platform table outside provisioning. Proofs: the Platform use case and repository specs (platform-business-unit-vertical-locks.repository.integration-spec.ts › reads, changes and locks only the activations of the organization in context, even for a session RLS does not restrict runs as the administrator, whom RLS does not restrict), the Organization use case specs and the business-unit-verticals-* e2e specs, unchanged.

Activating a vertical is not a subscription bypass (retracted from the earlier analysis): "No Organization command is capability-gated (D15)." (docs/reference/ORGANIZATION_USE_CASES.md:2070). Activating a vertical's configuration and authorizing an operation of that vertical are separate steps; H7 is only about who writes Platform's table.

---

7. Offline (H5): outline, not implementation

7.1 What exists and what is missing

Exists	Where
Till reads per outlet, ETags, catalogVersion, keyset search, 2,000-item cap with truncated	CATALOG_USE_CASES.md:1450-1454; sellable-read.ts:7
Sync SQL: devices, context assignments, bootstrap sessions, commands, conflicts, change streams and batches with acknowledgements	0370_sync.sql:185, :228, :272, :475, :498, :551, :727, :784-853
Events SQL: domain events, publications, outbox	0360_events.sql:127, :167, :202

Missing (analyst and architect findings)	Evidence
Catalog publishes no domain events	no outbox write in src/modules/catalog. Closed by K12a (migration 0114): the writes are SQL triggers of the catalog schema calling events.append_tenant_event, so src/modules/catalog still holds no outbox write by design (D40)
No tombstones: a retired or delisted thing produces no change a device can apply	no change feed; offers deleted until K9b. Closed by K12a: a retirement is a retired change with retiredAt
The version triggers cover 12 catalog tables only; menus, bundles, translations, item_assets, allergens, dietary tags and nutrition bump nothing	0080_catalog.sql:4139-4272, :4480-4488. Closed for every table a device reads (31 tables carry the triggers at K12a; the 17 translation, allergen, dietary tag and nutrition tables are read and written by no use case yet and get theirs with C23 and C24)
The till answer has no SKU and no barcodes, so a downloaded catalog cannot scan	sellable-read.ts. Closed by K12b: the bootstrap pages carry both
External ids exist for variants only	integrations.external_mapping_catalog_variants (0350_integrations.sql:563)
No Sync module, device grant or revocation, composed offline view, or replay	architect H5

7.2 Design outline

Piece	Responsibility
Catalog change feed (K12a, built, "K12a as built")	Every statement that moves the catalog version writes, in its transaction, typed events (catalog.item.changed, .variant.changed, .barcode.changed, .offer.changed, .listing.changed and, because the till reads them, .modifier.changed, .bundle.changed, .menu.changed and .category.changed, each with catalogVersion and, for retirements, a tombstone with retiredAt) to events.outbox_records, by SQL triggers through the Events function events.append_tenant_event; every table a device reads carries version triggers
Bootstrap (K12b)	A device bootstrap reads at one catalogVersion (a REPEATABLE READ snapshot per page set, or pages pinned to a version and restarted only for the pages a later delta touches), unlimited items in pages, including SKU and the barcode index (barcode → variant) of what the outlet sells
Deltas	Applied in version order by Sync batches; idempotent by event id
Historical verification (K12c)	CatalogSellableContract.verifyHistorical(context, { lines }): checks only immutable structure (variant belongs to item, option belongs to group, offer belongs to item/variant and group, tenant), never current status
Sales replay	Sales' command with a stable id (sync.commands, 0370_sync.sql:551), replayed through Sales' use case

7.3 The 10:00 / 10:05 / 10:15 case (OV20, Q4)

A device sells offline at 10:00; the item is retired at 10:05; the device syncs at 10:15. Recommended policy: accept the sale as a historical fact when all hold: (1) the sale command carries the catalogVersion its local snapshot was built from and the admitted identities (variant, offers, options); (2) Sync shows the device had not acknowledged a batch containing the retirement before the sale's device time (sync.change_batch_acknowledgements, 0370_sync.sql:853); (3) the device's context assignment covered that outlet at that time (0370_sync.sql:272); (4) verifyHistorical passes. Otherwise Sales records a conflict (sync.conflicts, 0370_sync.sql:727) for a manager to accept or void. Device clock skew is bounded by the session's server time (sync.sync_sessions, 0370_sync.sql:393).

7.4 Acceptance checklist (architect H5)

Criterion	Planned evidence
Bootstrap of more than 2,000 items with a consistent cut	e2e: 3,000 items, a write during the bootstrap, the device ends at one version with no duplicate or gap
Local barcode for a downloaded variant	e2e: scan resolved from the bootstrap index
Retiring an item removes it from the local offer	delta with a tombstone applied
Retrying a delta or a sale has no double effect	idempotency by event id and command id
Switching business keeps catalogs, prices and queues apart	device-scoped stores per business unit
A permission change rebuilds or invalidates the local scope by a defined policy	Recommended: revocation invalidates the device grant at the next session; a scope change forces a new bootstrap
Offline sales and printing survive a device restart	client persistence; out of the API
Stock, payments and fiscal consequences tested with their owners	Inventory, Payments, Fiscal
Stock oversell / reserve / offline allotment	Inventory's policy, owner question Q5

---

8. Structured variant attributes (H6)

Status: built (K13a migration 0109, K13b no migration; see "K13 as built" at the end of this file for what changed from the design below).

The matrix (domain/items/variant-matrix.ts:29-42) today writes concatenated codes and names (m-azul, M / Azul, CATALOG_USE_CASES.md:1401).

Design (K13a SQL, K13b matrix and filters), all inside catalog:

Table	Columns	Rule
variant_dimensions	id, organization_id, catalog_id, code, name, sort_order, status	catalog-level ("Size", "Color"), so "every blue variant" spans items
variant_dimension_values	id, organization_id, catalog_id, dimension_id, code, name, sort_order, status	value identity survives a rename and carries translations later
item_variant_dimensions	item_id, dimension_id, sort_order	which dimensions define this item's variants; at most 3
item_variant_dimension_values	item_variant_id, dimension_id, dimension_value_id	one value per (variant, dimension); the dimension must be one of the item's

Uniqueness of a combination: a deferred constraint trigger refuses two active variants of one item with the same set of values. The matrix command creates the dimensions it is given, the values, the variants and the links in one transaction; existing matrix variants are back-filled by parsing nothing (their codes are opaque): an owner re-applies the matrix, which links existing variants by code. Descriptive item attributes (material, fit) are not variant-defining and wait for a named reader. No shirt_size, shoe_color or vertical columns.

---

9. Concurrency, performance, security, tests

9.1 Concurrency and H8

• Offer commands: catalog version row FOR UPDATE, item FOR UPDATE, variant FOR SHARE (variant route), groups FOR SHARE in id order.
• Retire and revive are UPDATEs of a non-key column, compatible with the FOR KEY SHARE that Sales and Pricing FKs take.
• H8: admit shares the organization's catalog version row, so a catalog command of the organization (any business unit) waits for open admissions. The budget is ≤ 50 ms of transaction after admit (CATALOG_USE_CASES.md:1470-1471). K11 measures the real Sales transaction with npm run perf:admission; no admission may be held across remote payment, printing or fiscal calls. If the real hold exceeds the budget, the lock-free admission of CATALOG_USE_CASES.md:1471 is designed before Sales ships.

9.2 Performance

Effect	Estimate	Mitigation
K9d quantity judging	none measurable	—
K9f per-variant effective offers in C17	≈ +20 KB (+9 %) on the 300-item restaurant (214 KB) if 30 % of items override one group on two variants	delta overrides only; re-run perf:http; the known C17 p50 breach (CATALOG_USE_CASES.md:1456) grows with the body
Delta sync (K12)	needs stable ids (H1)	—
Per-variant satisfiability	evaluates effective offers per sellable variant	EXPLAIN (ANALYZE, BUFFERS) on the 20,000-item world (CATALOG_USE_CASES.md:1241-1243)
H7 contracts	+1 statement on back-office reads; 0 on hot reads (owner SQL functions)	statement-budget tests updated

9.3 Security

Risk	Control
Injection via text values (K14c)	bound parameters; ≤ 500 characters; NUL and control characters refused; NFC before length
Output injection on tickets, receipts, displays, LLM prompts	renderers encode for their medium and treat values as data
Resource exhaustion	≤ 100 lines × 100 selections; ≤ 10 text selections per line; quantities 1–999
Client-trusted prices	no price crosses the contract
Cross-tenant references	composite (id, organization_id) FKs; RLS with the scalar subquery; foreign ids answer like unknown ones
Offline replay abuse	§7.3 evidence; device grant revocation

9.4 Case-matrix rows (planned titles)

C13 (K9a–K9c): the nine rows of §4.1.

C20 (K9d–K9e):

Case	Expected	Planned test
3 × one sauce in a group of max 3; 4	admitted; selection_above_maximum	src/modules/catalog/domain/sellable/sellability.spec.ts › judges every group on the sum of the chosen quantities, as the sales schema does
Cheese × 2 with minimum 2	admitted	… › meets a minimum of two with one option chosen twice
Quantity above the option maximum	option_quantity_above_maximum	… › refuses a quantity above the option maximum, naming the option
0, 1000, 1.5, negative; an option twice	invalid_quantity, duplicate before any SQL	src/modules/catalog/application/sellable/catalog-sellables.spec.ts › rejects a selection quantity outside 1 to 999 or not an integer, and an option repeated in a line, before any lock
Line quantity off policy	quantity_out_of_policy	src/modules/catalog/domain/sellable/sellability.spec.ts › refuses a line quantity below the minimum, above the maximum or off the step of the variant
The answer carries the effective offer	itemModifierGroupId, modifierGroupId, source, min, max, names, kinds, target unit	test/e2e/catalog-sellable-contract.e2e-spec.ts › admits quantities and answers the effective offer identity and everything a sale line stores
Removed and reduced defaults	derived	src/modules/catalog/domain/sellable/sellability.spec.ts › derives the removed and reduced defaults of each offer from the final selection
Parity with the Sales trigger	rows built from the answer pass validate_line_modifier_insert and assert_order_line_modifier_consistency	database/tests/contracts/catalog-sales-admission-parity-contracts.ts › NINAKU_CATALOG_SALES_ADMISSION_PARITY_OK

C17/C18/C19/C20 (K9f–K9h):

Case	Expected	Planned test
Wings ×6 inherits max 2, ×25 overrides max 6, ×3 opts out	each variant its own rule	test/e2e/catalog-variant-modifier-offers.e2e-spec.ts › resolves sauces per variant: inherited, overridden and opted out
One variant's required override has no available option	that variant absent, the others sellable; scan, till, search and admit agree	test/e2e/catalog-till-parity.e2e-spec.ts › gives the scan, the till, the search and the contract the same per-variant verdict for an override, an opt-out and an unsatisfiable required override
A suspended item-level required group	every variant not configurable	… › hides every variant while a required item-level group is suspended and shows them again when it resumes
Minimum 3 with one option of maximum 3	satisfiable (OV11)	src/modules/catalog/domain/modifiers/modifier-offer.spec.ts › accepts a minimum that the available options can reach through their quantities

H7 (K10): as built in K10b, a separate lint over every production file of src/modules/**: tooling/repository/check-sql-ownership.spec.ts › reports a table of another module named in a query, with its file and line and fails with the file, the line and the foreign name it found.

---

10. Slices (architect order)

Forecasts count authored added plus deleted lines, tests and docs included, and the canonical mirror for migrations.

#	Slice	Finding	Migration	Forecast	Depends on
1	K9a (built) — retired status (widened CHECK, live index); every offer reader ignores retired; no writer yet	H1	<next>_catalog_offer_retirement_status (expand)	≈ 250	—
2	K9b (built) — stable offer identity: update in place, retire, revive, suspended flag, audit in one transaction; acceptance table of §4.1 with real referencing rows	H1	none	≈ 400	K9a deployed
3	K9c (built) — revoke DELETE on offers (built)	H1	0091_catalog_offers_are_never_deleted (contract step)	≈ 110	K9b deployed
4	K9d (built) — quantified selections: contract types, request validation, sum judging, option maximum, line policy	H2	none	≈ 380	K9b
5	K9e (built) — effective offer identity in resolve and admit, removed/reduced defaults, Sales parity contract, MODULE_CONTRACTS.md sentences	H3	none	≈ 360	K9d
6	K9f (built) — shared effective-offer fragment (override, opt-out, suspend) in C17/C18/C19/resolve/admit; per-variant sellability; parity e2e; EXPLAIN, perf:http	H4	none	≈ 420 (honest)	K9e
7	K9g (built) — variant route, C3 variant offers, where-used variantId	H4	none	≈ 400	K9f
8	K9h (built) — satisfiability by units (OV11); delivered ahead by F1 (§4.2, As built (F1))	H4	none	≈ 200	K9f
9	K10a (built, migration 0092) — Organization and Platform read contracts and SQL read functions	H7	<next>_organization_published_read_functions (expand)	≈ 350	—
10	K10b (built) — Catalog queries switched to them; SQL-ownership lint	H7	none	≈ 400	K10a
11	K10c (built) — BusinessUnitVerticalsContract; Organization calls it	H7	none	≈ 300	K10a
12	K11 (blocked: the Sales and Pricing modules do not exist) — minimal Sales/Pricing integration proof (a sale with options, a per-offer price, snapshots, rollback) and H8 measurement; owned with the Sales and Pricing designs	— / H8	per those modules	per those designs	K9e, K9g
13	K12a (built, 0114_catalog_change_feed, "K12a as built") — catalog change feed with tombstones; version triggers on every table a device reads	H5	0114_catalog_change_feed	≈ 400	K9b
14	K12b (built, "K12b as built") — device bootstrap with a consistent cut, barcode index; a Catalog read API, since the Sync module does not exist	H5	none	≈ 400	K12a
15	K12c — verifyHistorical and the replay policy	H5	none	≈ 300	K12b, Sales
16	K13a (built) — structured variant dimensions (SQL; migration 0109, "K13 as built")	H6	0109_catalog_variant_dimensions	≈ 350	—
17	K13b (built) — matrix creates them, the item read shows them, GET /catalog/variant-dimensions and the variantValue filter ("K13 as built")	H6	none	≈ 400	K13a
18	K16 (built) — outlet hidden items: hide-only exceptions of one outlet over the assortment of the business unit that operates it (C30); GET, PUT /catalog/outlets/{outletId}/hidden-items; one shared SQL fragment in the till list, the search, the scan, resolve and admit	owner request	0106_catalog_outlet_hidden_items (expand)	≈ 2,300 (tests and docs included)	M2a
19	K14a (built) / K14b (built) — default quantities, per-offer option limits; routes (customer_visible is dropped: it has no reader, no use case, and OV18 forbids channel facts in the catalog)	specialization	0108_catalog_offer_defaults_quantities_and_overrides / none	≈ 330 / ≈ 400	K9f
20	K14c (built) / K14d (built) — text kind, prefixes, print hints; the write route is the existing PUT /catalog/modifier-groups/{modifierGroupId} ("K14c as built"); K14d is the reads and the judging ("K14d as built")	specialization	0110_catalog_option_kinds_and_presentation / none	≈ 230 / ≈ 380	K9e; K14d after K14c deployed
21	K15a (built, 0111_catalog_master_data_hardening, "K15a as built") / K15c–K15d — master data (§17): bounds and hardening, product brands, intrinsic identifiers; K15b was never defined (the GS1 check digit of §17.3 is already enforced in code); item_kind only when one of its named readers ships (OV21)	specialization	per §17.7	≈ 300 / 380 / 300 / 300	—
22	Menus (C21; M1 structure built, §21, migration 0101; outlet assignment M2a built, C29, migration 0105; till read by menu M2b built; time windows S1 built, C31, migration 0107), bundles (C22; B1 built, §19, migration 0100; admission B2 built, §20, no migration; Pricing and Sales B3 next)	—	their own designs	—	verified needs

Migration numbers: the next free number after 0083 (revision 93) when each is written; the Assets stages also take numbers (ASSETS_STAGE_SPECS.md:68).

10.1 Coverage snapshot (baseline revision 117)

Measured against the code, not planned. The API v7 pull requests 1 to 7 (revisions 112 to 114) reshape routes and reads without adding a use case, a table read by TypeScript or a roadmap slice, so the counts are the ones measured at revision 111; PR 7 closes two findings of the plan, the category tree tag that any item write invalidated and the item list that needed one detail call per row for its image:

Measure	Built	Of	Share
Use cases (CATALOG_USE_CASES.md, C1 to C28)	23	28	82%
Catalog tables with TypeScript that reads or writes them	20	37	54%
Roadmap slices (this section and §18 to §21)	24	42	57%
Overall			about 58%

What is left, in order (B2b, B2c, M2a, M2b, K16 and S1 are built since the counts above were measured; the counts are not re-measured here):

1. K14c / K14d (built, "K14c as built" and "K14d as built") — the text kind with its prefixes and print hints, and the reads and the judging of text selections. K14a (default quantities, migration 0108, which also created catalog.item_modifier_group_option_overrides) and K14b (the per-offer option limits that read and write that table, no migration) are built.
2. K13a / K13b (built, "K13 as built") — structured variant dimensions; the matrix creates them, the item read shows them and the list filters by them.
3. K15c–K15d — master data (§17); K15a is built ("K15a as built").
4. S1 (built, §22 "S1 as built") — menu time windows; holidays and date ranges stay deferred.
5. K11 and B3 — blocked: they need the Sales and Pricing modules, which do not exist.
6. K12a–K12c — offline: the change feed, the device bootstrap, the replay policy.
7. C23 translations, C24 food declarations, C27 imports.
8. C25 additional catalogs — deferred (OD4).

---

11. What the neighbours must do

Sales: reference offers only after K9b; call admit (K9e) last and hold ≤ 50 ms; store the offer admit returned (the effective-offer rule is aligned since migration 0090, X13); add text_value (X3), a representation of removed defaults (X4) and, for offline replay, the catalogVersion (X7); bound special_instructions (0110_sales.sql:541, :999). Commerce: same admission; add the variant precedence and group sum check (X2). Pricing: price per itemModifierGroupId (exists); revival of an offer reuses its prices (Pricing decides whether dated rows still apply); sequence pricing, charge basis, percentage mode, removal credit are its own design (X5, X6). Discounts, Inventory, Production, Tax, Kitchen, Operations: as §5.3, §4.5, §4.6, §4.10. Organization and Platform: K10a–K10c. Sync and Events: K12.

---

12. Contradictions and findings

#	Finding	Evidence	Resolution
X1	Offers deleted and re-created on every edit; referencing FKs have no cascade	modifier-group.queries.ts:158-175; 0110_sales.sql:1229-1237; 0100_commerce.sql:1048-1056; 0090_pricing.sql:470-478	K9a–K9c
X2	Commerce's trigger lacks variant precedence and group min/max	0100_commerce.sql:1871-1990	Commerce
X3	No column for a text option value in Sales or Commerce	0110_sales.sql:1177-1307	Sales, Commerce
X4	A removed default cannot be persisted	0110_sales.sql:1271-1274	Sales (Q3)
X5	Pricing's delta may be negative; Sales refuses negative charges; no removal credit	0090_pricing.sql:424-425, :509-513; 0110_sales.sql:1276-1280	Pricing
X6	No charge basis beyond "per base unit of the line"	0090_pricing.sql:484-491; 0110_sales.sql:1198	Pricing
X7	No Sales column for the admitted catalogVersion	CATALOG_USE_CASES.md:1465	Sales
X8	An extra with its own tax class is taxed in the line subject	0260_tax.sql:1162-1180; 0110_sales.sql:1807	Tax
X9	Sales/Commerce accept inactive groups or targets; Catalog refuses them	0110_sales.sql:4090-4095	harmless while admit runs first
X10	Sales' kind check has no branch for text	0110_sales.sql:4103-4118	Sales must add a text branch before it consumes text options; K14c and K14d only publish them (Catalog-only: Sales does not exist yet)
X11	Production needs quantity 1 for remove/replace/scale	0180_production.sql:6300-6304	K14c prefix checks: light, no, on_the_side and substitute need maxQuantity 1; extra as a scale effect cannot be checked by Catalog because the effect is Production's (OV18) and Production refuses it at sale time
X12	MODULE_CONTRACTS.md names the lock timeout; the measured limit is the statement timeout	MODULE_CONTRACTS.md:357; CATALOG_USE_CASES.md:1469	K9e sentence update
X13	Sales ignores an inactive variant offer and falls back to the item offer (img.status = 'active' filters before DISTINCT ON), contradicting OV9's opt-out; it would require the item-level minimum on an opted-out variant	0110_sales.sql:4200-4225, :4120-4134 (before 0090)	Closed by K9g-0 (migration 0090): Sales chooses the variant row among active and inactive first, then drops the group when it is inactive, and ignores retired
X14	Catalog names Organization and Platform tables; Organization writes Platform's table	§6.1	K10
X15	Version triggers miss menus, bundles, translations, item_assets, allergens, dietary tags, nutrition	0080_catalog.sql:4139-4272	add with each table's first use case (K12a rule); item_assets closed by migration 0095, bundles by 0100 (B1, §19), menus by 0101 (M1, §21). Checked at K12a by a systematic query: every table the till and the sellable reads touch carries the triggers; the 17 tables without them (translations, allergens, dietary tags, nutrition) are read by nothing, and a database contract lists them so a table added without a decision fails
X16	No catalog events, no tombstones, external ids for variants only	§7.1	Closed by K12a (events and tombstones, migration 0114); other external mappings when a channel needs them

Not defects (qualified after the architect's review): activation of verticals without the plan (D15, §6.2); salesQuantityStep (published and applied); preselections (already on the offer since 0080, is_default dropped by 0082); item_kind (a proposal, OV21).

---

13. Minimum journeys (architect §14) as acceptance

Journey	Proves	Slice that makes it runnable
Restaurant: two wing variants, one sauce group, different limits	effective offer and override	K9f
Restaurant: cheese × 2, a per-offer price and history	quantities, offer identity, snapshots	K9e + K11
Retail: T-shirt size/colour, barcode and price by context	variants, attributes, composition	K13b + Pricing
Retail: 3,000 items and scanning offline	complete bootstrap, local index	K12b
Gym: membership + protein + T-shirt in one purchase	shared core, Gym's own consequences	future Gym vertical (criterion, not yet run)
Hotel: minibar charged to a stay	Hospitality integration without a room as an Item	Phase 10 (criterion)
Mixed organization: edit the master, offer per business	sharing without mixing assortments	built (K6), re-proven after K10b
Offline: sale before a retirement, then replay	explicit reconciliation	K12c
Concurrency: sales while another unit is edited	the real lock scope and admission budget	K11 (H8)

---

14. What stays out

Prices, charge bases, discounts, stock and tracking, recipes, tax classes, runtime availability and option allergens stay with their owners (OV18). Portions and nested options are deferred (OV23). Per-outlet or per-variant assortment waits for a business journey that needs it (architect §11). Menus and bundles come last, by use case with real consumers (architect §12, "Presencia de tablas SQL").

---

15. Open owner questions

#	Question	Recommendation
Q1	Free-text options (engraving, cake message) in the first options delivery? They need Sales and Commerce columns (X3).	Yes, K14c–K14d, after K11
Q2	When an ingredient runs out, should the till hide the instruction option at that outlet?	Yes, an Operations table beside the variant "86"
Q3	When a cashier deselects a default, must the kitchen ticket say "NO cheese"?	Yes: Sales persists removedDefaults; until then use "No X" options
Q4	Offline: accept a sale made before a retirement the device had not yet received (§7.3)?	Yes, on the four pieces of evidence; otherwise a conflict for a manager
Q5	Offline stock: allow oversell with later reconciliation, reserve an allotment per device, or block items without a confirmed balance?	Allow oversell with a flagged reconciliation for restaurants; allotments for retail items an owner marks as scarce

Decided and no longer asked: per-variant offers (owner), unit quantity semantics (Sales SQL), inactive override = opt-out (owner via coordinator). Pricing's tiered prices and charge basis move to the Pricing design (X6).

---

16. Sentences MODULE_CONTRACTS.md will need (row of CatalogSellableContract, line 357)

Changed in the slice that changes the contract (K9e), never before.

• Replace "admit recibe líneas (como máximo 100, cada una con sus opciones elegidas, sin repetir)" with: "admit recibe líneas (como máximo 100), cada una con su variante, su cantidad y sus selecciones { optionId, quantity } (como máximo 100 por línea, una opción una sola vez, cantidad entera de 1 a 999); juzga la cantidad de la línea contra la política de venta de la variante, la cantidad de cada opción contra su máximo efectivo y el mínimo y el máximo de cada grupo sobre la suma de las unidades, igual que el esquema de ventas."
• Add: "resolve y admit responden las ofertas efectivas de cada variante (itemModifierGroupId, modifierGroupId, source item o variant, mínimo y máximo), resueltas con una sola regla: la oferta activa de la variante reemplaza a la del artículo, la inactiva de la variante excluye el grupo y la ausencia hereda; la venta guarda la oferta que admit devolvió."
• Add: "Las ofertas nunca se borran ni cambian de identidad: editar sus reglas u orden conserva el UUID, quitar un grupo la retira (retired) y volver a ofrecerlo la revive con el mismo UUID; conservar el UUID no congela las reglas históricas, que cada consumidor guarda en su propia instantánea."
• Extend the refusals with quantity_out_of_policy and option_quantity_above_maximum, and the request problems with invalid_quantity.
• Replace "falla al vencer DATABASE_LOCK_TIMEOUT_MS" with "falla al vencer DATABASE_STATEMENT_TIMEOUT_MS" (X12).
• With K10: add rows for OrganizationContextContract and BusinessUnitVerticalsContract, and the normative exception of §6.2.

---

17. Column review of the catalog tables (owner requirement, 2026-10-07)

Rule (OV18). Catalog stores descriptive and classification facts and stable ids only. A column passes the coupling check when it adds no FK to another module's schema, repeats no fact another module owns, and reaches neighbours only through CatalogSellableContract or their own snapshots (as Sales does: item_code_snapshot, display_name_snapshot, sku_snapshot, 0110_sales.sql:517-522). Existing FKs to organization.organizations, organization.business_units, reference.units_of_measure and assets.assets stay; nothing below adds another one.

17.1 catalog.items (0080_catalog.sql:76-128, :3793-3827, :4490-4499)

Column	Verdict	Reason	Coupling check
id, organization_id, catalog_id, code, name, status, timestamps, idempotency and search-key columns	keep	—	existing FKs only
description	change (hardening, built in K15a, 0111)	unbounded text (:82) while the API bounds it to 2,000 (presentation/dtos/items/item-fields.ts:8, :36-38): add the same bound in SQL	—
index catalog_items_organization_status_idx (:123-128)	drop after EXPLAIN proves it unused	superseded by catalog_items_name_search_idx (:3978), as CATALOG_USE_CASES.md:1228 planned	—
item_kind	Proposed only (OV21): goods | service | digital | rental, added when one of its named readers ships: Tax (a service rate in some jurisdictions), Invoicing (fiscal line nature), Inventory (no stock link expected for a service), Kitchen (nothing to prepare for a digital item)	The review found no reader yet; the catalog already sells services (CATALOG_USE_CASES.md:1109)	it must never decide kitchen routing, stock, tax or membership inside Catalog; each reader applies its own rule to the snapshot value
product_brand_id	add (K15c): FK to new catalog.product_brands	manufacturer label for search and filters; distinct from organization.brands (0020_organization.sql:211)	FK inside catalog
regulatory flags	added (K15a, 0111): catalog.item_regulatory_flags (item_id, flag), flag IN ('age_restricted_alcohol','age_restricted_tobacco','prescription_only','pharmacy_only','hazardous_goods')	pharmacy, liquor, hardware	Catalog says what the product is; the rule belongs to Sales or a compliance module
lifecycle dates	not added (Proposed)	a second sellability rule beside status	—
weight, dimensions	not added	inventory.items (0170_inventory.sql:141)	—
stock tracking	not added	Inventory owns lot_tracking_mode, expiry_tracking_mode (0170_inventory.sql:131-200)	—

17.2 catalog.item_variants (0080_catalog.sql:140-260, :3841-3848, :3975)

Column	Verdict	Reason	Coupling check
identity, code, name, sku, is_default, status, timestamps	keep	the FK hub (CATALOG_USE_CASES.md:172-180)	—
sales_unit_code	keep	reference units with dimension and conversion (0010_reference.sql:189-214); packaging is Inventory's (:186-187)	existing FK
minimum_sales_quantity, maximum_sales_quantity, sales_quantity_step	keep; hardening CHECK that min and max are multiples of the step, built in K15a (0111)	not a defect: the step is published and applied (architect §12); the check only stops a policy that forbids its own minimum	—
net_content_quantity, net_content_unit_code	added (K15a, 0111), both or neither; unit validated by the application against reference data, no new FK	label content (500 ml)	unit price is Pricing's
variant dimensions	see §8 (K13)	structured, not concatenated	inside catalog
sale_capture (IMEI at sale)	not added (Proposed)	a Sales capture rule, never a stock-tracking copy	—
weight, dimensions, cost	not added	Inventory, Procurement	—

17.3 catalog.item_variant_barcodes (0080_catalog.sql:269-345, :3976)

Column	Verdict	Reason	Coupling check
every column	keep	unique while active (:3976); one active primary (:332-338)	—
barcode	change (domain rule, no SQL)	validate the GS1 check digit for ean13, ean8, upca, upce	—
units_per_scan	not added	packaging is Inventory's (:26)	—

17.4 Categories (0080_catalog.sql:354-483)

Column	Verdict	Reason	Coupling check
every column of categories and item_categories	keep	hierarchy and effective visibility are correct (architect §11)	—
categories.description	change (bound, built in K15a)	unbounded (:362)	—
tax or kitchen meaning	not added	owners map categories themselves (0150_kitchen.sql:637)	—

17.5 Modifier tables (0080_catalog.sql:1366-1733, :4396-4488)

Table.column	Verdict	Reason	Coupling check
item_modifier_groups.status	change: add retired (K9a)	OV2	keeps neighbour FKs valid without Catalog knowing them
item_modifier_groups.item_variant_id	keep, now used (K9f–K9g)	OV9	—
item_modifier_group_defaults.quantity	added (K14a, 0108)	OV16	—
item_modifier_group_option_overrides	added (K14a, 0108; read and written since K14b)	OV16	inside catalog
modifier_options.option_kind (+text), text_max_length, prefix, prints_on_receipt, prints_on_kitchen_ticket	change/add (built in K14c, 0110)	§4.5, §4.6	hints only
modifier_groups.description	change (bound, built in K15a)	unbounded (:1372)	—
price, charge basis, recipe effect, stock link	not added	Pricing, Production, Inventory	—

17.6 Assortment, item_assets, catalogs

Table.column	Verdict	Reason	Coupling check
business_unit_catalogs, business_unit_items: every column	keep	—	existing FK to organization.business_units; reads move behind K10
…updated_at on both	add with the next migration that touches them	R4 (CATALOG_USE_CASES.md:1553)	—
business_unit_items.item_variant_id	not added (Proposed)	per-variant assortment waits for a journey (architect §11)	—
item_assets.catalog_id	add in the A5b migration	every other link row carries it (:3853-3880)	inside catalog
item_assets other columns	keep	ASSETS_STAGE_SPECS.md:1192-1208	existing FK to assets.assets; no URL copied
catalogs.code pattern, catalogs.updated_at	change/add when OD4 brings more catalogs	R10 (CATALOG_USE_CASES.md:1559)	—

17.7 Migrations for K15

• <next>_catalog_master_data_hardening (K15a): description bounds (items, categories, modifier groups) and the variant step check, each NOT VALID then VALIDATE after a check query finds no breaking row; net content columns; item_regulatory_flags with RLS (scalar subquery), bump triggers, GRANT SELECT, INSERT, DELETE. Expand-only.
• <next>_catalog_product_brands (K15c): product_brands, items.product_brand_id, RLS, triggers, grants. Expand-only.
• <next>_catalog_variant_identifiers (K15d): item_variant_identifiers (item_variant_id, scheme, value), scheme IN ('mpn','isbn', 'manufacturer_code'); channel ids stay in integrations.external_mapping_catalog_variants (0350_integrations.sql:563). Expand-only.
• 0114_catalog_change_feed (K12a, built): events.append_tenant_event, nine catalog.*.changed event types with contract version 1, and the catalog.record_change_feed() triggers on 28 catalog tables. No table changes. Expand-only.

---

18. D1 design: what a new business unit sells

Status: built (revision 109, migration 0099). The owner approved A1 together with verticals on O9 (18.4) on 2026-10-10. What was built is in CATALOG_USE_CASES.md ("D1 as built") and ORGANIZATION_USE_CASES.md (O9); this section keeps the design record: the facts, the options weighed and why the others were rejected.

18.1 The decision and what exists

Owner decision. The assortment of a business unit is chosen when the unit is created (all, selected or none). Without a choice, the default is none for a unit whose vertical differs from the verticals of the organization's existing units, and all otherwise (same vertical, or first unit). Existing units keep selling what they sell today. It replaces OD5 (a) for new units.

As built (revision 108):

• A unit without a catalog.business_unit_catalogs row for the default catalog sells everything: variant_is_listed, listed_items, the listed filter and the till read treat "no row and a catalog in organization mode" as listed, and assortmentModeOf(undefined) answers all (src/modules/catalog/domain/assortment/assortment.ts).
• none is not a stored mode. It is an inactive row that keeps the mode it had (storedModeOf); selected with no listings also sells nothing.
• Catalog already owns a trigger on an Organization table: organizations_catalog_version_insert_trg creates the catalog.catalog_versions row (DOMAIN_MAP.md, row 0080_catalog). npm run lint:sql-ownership judges SQL text inside src/modules, not canonical triggers.
• Every vertical writer serialises per organization on the advisory lock organization.verticals:<organization id>, taken before it reads or writes platform.business_unit_verticals rows: Platform's activate (its first statement, lockOrganizationVerticals), Platform's deactivate (before it locks the active rows), the last-vertical guard of a unit deactivation (0020_organization.sql) and this trigger. The lock belongs to the transaction, so a registration that activates its verticals and then runs the trigger at commit takes it again without waiting for itself, and releases it at commit. Proven by platform-business-unit-vertical-locks.repository.integration-spec.ts › makes a business unit registered with a vertical another unit is activating wait for that activation, then counts it, and by database/tests/concurrency/catalog-default-assortment-concurrency.ts, which runs the repository's own SQL text (business-unit-verticals-sql.ts) instead of a lock of its own.

18.2 Blocker 1: a unit has no vertical when it is created

• Provisioning (POST /organizations) inserts the first unit and its verticals in one transaction (platform.provision_organization). That unit is always the first one, so its default is all.
• O9 (POST /business-units) carries only code and name (RegisterBusinessUnitRequestSchema is strict). Verticals arrive later, through O11 (POST /business-units/{id}/verticals/{code}/activation), in another transaction, or never.
• organization.business_unit_is_operable does not require a vertical: a unit with an outlet and no vertical can open a till and sell.

So for every unit after the first, "the vertical of the new unit" does not exist when the unit is created. "Decide at creation and store it" and "compare the unit's vertical" can both hold only if O9 receives the vertical, or if the rule names a value for "no vertical yet".

18.3 Blocker 2: an explicit choice on the O9 request

An assortmentMode field on POST /business-units must reach Catalog in the same transaction. Organization owns that route and must not depend on Catalog; Catalog already imports OrganizationModule (OrganizationContextContract), so the reverse import is also a module cycle.

Mechanism	Verdict
Organization calls a Catalog contract	Rejected: breaks the dependency direction and creates a Nest module cycle
Organization stores the requested mode in a column a Catalog trigger reads	Rejected: Organization would own a Catalog fact (MODULE_CONTRACTS.md §1)
A transaction-local setting (set_config) read by a Catalog trigger	Rejected: a hidden dependency that lint:module-boundaries cannot see
An extension point owned by Organization (an abstract class in its contracts/ that Catalog implements and registers)	Not built: dependency inversion, but a collaboration mode MODULE_CONTRACTS.md §4 does not list; it needs an architecture decision first
A command composer outside both modules (Organization, Platform and Catalog contracts in one tenant transaction)	Clean, but it needs a new module and a new or moved route: out of D1's scope
An outbox event	Rejected: not atomic, the unit sells the organization catalog until the event is handled
The client sends the choice to Catalog's existing route PUT /catalog/business-units/{id}/assortment (C14) right after registering	Recommended. No new mechanism, audited by C14 (catalog.assortment.mode_changed); safe because the default of 18.4 is already safe for the request in between

18.4 The default: options

A1 (recommended). A Catalog-owned deferred constraint trigger on the insert of a business unit, evaluated at commit:

• business_units_default_assortment_trg: AFTER INSERT ON organization.business_units DEFERRABLE INITIALLY DEFERRED FOR EACH ROW, calling catalog.materialize_default_assortment(), SECURITY DEFINER with a fixed search_path and revoked from PUBLIC. It must be a definer because it also runs at the commit of provisioning, which has no tenant context, and of admin fixtures.
• At commit: a unit that already has a row for the default catalog (an explicit choice in the same transaction) is left alone. Otherwise it takes the organization.verticals:<organization id> advisory lock, so two registrations in one organization cannot both be first (the second one's next statement runs after the first commit and sees it), creates the default catalog if missing (the insert of ensure_default_catalog, without its tenant assertion), and inserts one row. all when no other unit of the organization has an active vertical (first unit), or when the unit has at least one active vertical and each of them is active in another unit of the organization; none (an inactive row of mode all) otherwise, which includes a unit with no vertical at commit.
• Stored once. Later vertical changes never touch it; only C14 does. The insert bumps the catalog version through the existing statement trigger, so the assortment and till ETags move.
• Audit: a SQL trigger cannot use TenantAuditContract. The default is a consequence of the audited organization.business_unit.registered record; later changes are audited by C14.
• Migration 0099 at revision 109, expand-only: the function, the trigger and a backfill that gives every existing unit without a row an explicit active all row on its organization's default catalog, creating the default catalog where an organization has none (one version bump per organization). The behaviour is identical: in a catalog in organization mode, no row and an active all row list the same variants (variant_is_listed). Reads keep "no row means all", so other catalogs and any row the backfill could not see answer as today.

With A1 and today's O9, every unit registered through POST /business-units starts none, a second restaurant too. That is safe (it sells nothing until someone curates it) but it is not the owner's "same vertical, all". Two ways to close the gap:

• A1 + verticals on O9: an optional verticalCodes on POST /business-units; Organization activates them inside the registration transaction through BusinessUnitVerticalsContract.activate (already allowed since K10c) with the O11 audit records, and the trigger sees them at commit and applies the rule exactly. It changes the O9 API.
• A2: keep O9 as is and store the default at the first vertical activation instead (a Catalog trigger on the insert of an active platform.business_unit_verticals row), with "no row" meaning "sells nothing" for units created after 0099. Not recommended: the mode a client reads moves from none to all when a vertical is activated, which the owner called a bug; and it changes the meaning of "no row" in four predicates (variant_is_listed, listed_items, the listed filter, the till read) and their differential contract.

C (rejected). A default computed at read time from the verticals changes silently whenever a vertical is activated or deactivated.

18.5 What the build must prove

First unit, all; second unit with the same vertical, all; second unit with another vertical, or with none, none, and its till sells nothing until curated; an explicit C14 choice made in the same transaction or right after wins in each of the three modes; two registrations raced in one organization, exactly one first; an existing unit without a row keeps all across the migration (upgrade test from revision 108, till list identical before and after); the assortment routes and ETags still work; a curator switches the mode and the till follows; another organization's units never count. Mutations that must fail a named test: the default always all; the default recomputed at read time; the backfill skipped; the advisory lock removed.

18.6 Blast radius

• 13 test files insert business units through admin SQL (for example addUnit in test/support/offerable-roles-fixture.ts). With A1 every unit after the first without a shared vertical becomes none at commit, so assortment and till specs that add a second unit and expect it to sell must choose a mode or share a vertical.
• The workspace warning units_with_different_verticals keeps its meaning; its hint should say that such a unit starts at none.
• OpenAPI changes only if O9 gains verticalCodes.

18.7 Owner choice (decided 2026-10-10)

A1 + verticals on O9: POST /business-units takes the optional verticalCodes, activated in the registering transaction, and the explicit choice travels through C14 right after registering, not through a field on O9.

---

19. B1: the composition of a combo

19.1 B1 design

Decided by the owner (verified review). A combo is a normal Item that owns Bundle Groups (0080_catalog.sql, the comment above catalog.bundle_groups): no item kind, no parallel product identity, so it keeps its variants, categories, modifiers, images and its own price. Catalog stores no price for it: Pricing computes the base price of the item plus one surcharge per choice (pricing.bundle_group_item_price_entries). A combo may contain another combo, with the SQL cycle guard. Retail kits and service packages use the same concept with nothing restaurant-only. Menus, schedules, admission (B2) and the Pricing and Sales integration (B3) come later; sold out is Operations'.

Shape, chosen for the consumer. One task route per combo, the same style as the modifier offers (C13) and the images (AC1): GET and PUT /catalog/items/{itemId}/bundle-groups. The PUT replaces the ordered groups and the ordered choices of each group in one call, because a manager edits a combo as one screen and partial routes would let it pass through states nobody wanted. Names follow the existing answers: ids are xxxId (bundleGroupId, choiceId, variantId, itemId), the rule is minSelections and maxSelections as on modifier offers, a preselection is isDefault, an order is the position in the array (no sortOrder field). A row of bundle_group_items is called a choice: what the customer chooses in a group. Each choice answers the item and variant names, the SKU and both statuses, so a screen needs no second call; isAvailable and suspended on each choice, and isSatisfiable and suspended on the group, tell the manager what the till will not be able to sell. Quantities are decimal strings, as the sales quantities of a variant.

Identity (the K9b rule). Sales, Commerce and Pricing reference both tables by id (sales.order_line_bundle_selections, commerce.cart_item_bundle_selections, pricing.bundle_group_item_price_entries, all NO ACTION), so a group or a choice is never deleted: what the list leaves out is retired, and sending it again revives the same id. A group is identified by its id; a choice by its (group, variant) pair, the existing unique key, so it keeps its id even when the client forgets choiceId; a choiceId sent with another variant is refused instead of silently moving a priced or sold row to another product. The CHECK of both tables is widened to retired (expand-only, as K9a); the runtime gets no DELETE.

Validation. Everything that needs no lookup is a 400 at the schema with the field (bundleGroups[i].choices[j].variantId, the format of every other validation answer); what needs the database is a typed refusal with meta.errors[] like the images bulk route. Limits reuse existing ones: 20 groups (as offered modifier groups), 50 choices (as options per group), 999 selections (Sales' selection_count), a quantity at most 999.

Version and locks. The version triggers are added to both tables (X15, the K12a rule: with the first use case). The command takes the version row, then the combo item with its composition (one statement, FOR UPDATE OF the item), then the requested variants FOR SHARE in id order, the order of every catalog command; an admission holds the version row FOR SHARE, so an edit waits for open sales (K8).

The item answer (C3) is unchanged. Adding bundleGroups to the item would change the bytes and the hash of every item and add a statement to every item read and write; the composition lives on its own route with its own strong ETag, and If-Match on the PUT uses that tag, not the item tag (which does not cover the composition).

19.2 B1 as built (migration 0100, baseline revision 110)

As designed; the use case, the answers, the example and the proofs are in CATALOG_USE_CASES.md, "B1 as built", and the C22 rows of CATALOG_CASE_MATRIX.md. Migration 0100 widens the two status CHECKs, names the cycle guard (bundle_composition_acyclic), adds the six version triggers, grants SELECT, INSERT and UPDATE on both tables and EXECUTE on the two graph functions the triggers call as the invoker, and seeds catalog.item.bundle_groups_set. After review the cycle guard ignores retired groups and choices (a retired choice must not forbid a later nesting), its triggers also fire on UPDATE OF status so a revival is checked, and the use case's lookup of the combos that contain a variant reads the same live graph. Repetitions are refused by the request schema before any lookup, the ids are judged before the unchanged-composition answer, and a row suspended in SQL stayed suspended when the list was written again (until the standardization below made suspension writable). B1 left three questions for the owner, now closed: suspending a group or a choice from the API and a cap per choice (max_selection_count) were taken by the standardization after M1, and a component that is itself a combo with a group that cannot be completed makes its parent's choice unavailable since F1b (§20.3, down to the third combo level). Still open: whether descriptions or translations of a group are needed.

---

20. B2: admitting a combo

20.1 B2 design

The problem. B1 lets a manager say what a combo is made of; nothing yet lets a sale say which components the customer took. admit judged only modifier selections, so Sales could not freeze sales.order_line_bundle_selections from a Catalog answer, and the 0110_sales.sql triggers (validate_line_bundle_insert, assert_order_line_bundle_consistency) would be the first place a wrong choice is caught, with a 23514 instead of a typed refusal.

Shape, additive. An admission line gains an optional bundleSelections; nothing else in the contract changes, and a line without it, or a line of an item without active groups, is admitted and serialized exactly as before (no bundleGroups key). The input mirrors the modifier input one level up, with the business names B1 already uses:

lines[i].bundleSelections: [{               // per group, each group once per level
  bundleGroupId,
  choices: [{                               // in the order the customer chose
    choiceId,                               // the B1 choice (group, variant)
    quantity,                               // integer 1..999, Sales' selection_count
    selections?: [{ optionId, quantity }],  // modifiers of THIS component
    bundleSelections?: [...]                // the groups of a combo inside the combo
  }]
}]

The admitted line answers bundleGroups, every active group of the combo in catalog order, mirroring offers: { bundleGroupId, groupNameSnapshot, minSelections, maxSelections, choices, removedDefaults }, each choice { choiceId, quantity, quantityPerSelection, appliedByDefault, snapshot, offers, bundleGroups? }. snapshot is the component's own sellable snapshot (item and variant names, SKU, sales unit), offers its own admitted modifier offers, bundleGroups its own tree when it is a combo. That is every column Sales freezes (table in §20.2); Catalog still answers no price.

Judgement, the same rules as modifiers and as Sales.

• A group must be a live group of that combo (bundle_group_not_offered) and active (bundle_group_unavailable); a choice a live choice of that group (bundle_choice_not_offered) and active (bundle_choice_unavailable). Sales refuses the same rows (0110_sales.sql:4436-4446).
• Minimum and maximum on the sum of the chosen quantities, as Sales sums selection_count (0110_sales.sql:4526-4542) and as modifier groups sum units (bundle_selection_below_minimum, bundle_selection_above_maximum). The same choice may be sent twice in a group: two occurrences, two Sales rows (selection_number), for "Burger #1 no onion, Burger #2 extra cheese" (the comment above the Sales table).
• A choice's own cap, max_selection_count, on the sum of its entries (bundle_choice_above_maximum); Sales checks it per row.
• A required group whose available choices cannot reach its minimum (B1's isSatisfiable: choice, item and variant active, each worth its cap or 999) refuses bundle_group_unsatisfiable and its sum is not judged.
• Each component is judged by the same sellable rule as a line (sellableVariant: item and variant active, listed at the business unit, required modifiers satisfiable), read by the same SELLABLE_FACTS statement, and the refusal carries that line reason (not_listed, item_inactive, ...). Its modifier selections are judged against its own effective offers by judgeSelection, the K9f rule.
• quantity_per_selection is not judged: it is the component amount per selection (B1 answers it as the choice quantityPerSelection; it was quantity until the standardization after M1), copied into quantityPerSelection for quantity_per_selection_snapshot. The component sales policy is not judged either, as Sales does not.

Defaults. A group the client leaves out gets its available defaults, one each (appliedByDefault: true); a group the client sends gets exactly what it sends, and the available defaults it left out are answered in removedDefaults, as modifier offers do. Why not mirror modifiers exactly (defaults never applied): a modifier default is a preset the till shows ticked, but a combo default is a component the customer receives and Sales must store a row for; a quick "Combo" key at the till must sell the default drink without the till re-reading the composition. B1 already keeps the defaults of a group between its minimum and its maximum, so applied defaults fit. A combo sent without bundleSelections whose required group has no default refuses bundle_selection_below_minimum for that group, the same reason as a missing required modifier group. A default counts as available by the same rule the till applies to a choice in the unit and outlet of the call (active, listed at the unit, not hidden at the outlet sent): one that is delisted or hidden is simply not applied and no other choice takes its place, so an optional group is admitted with no choice and a required one refuses bundle_selection_below_minimum; a choice the client sends that is no longer sold keeps refusing not_listed.

Nesting and bounds. A choice that is itself a combo is judged recursively with its own bundleSelections and defaults, as Sales checks every component (0110_sales.sql:4505-4542). The cycle guard only promises the graph ends; admission adds a depth of 3 (CATALOG_SELLABLE_LIMIT.BUNDLE_DEPTH: a component of a combo of a combo of a combo; "family, kids, drink" uses 2) so the statement count is bounded: a request deeper than that is a request problem (too_deep), a catalog deeper than that (through defaults) refuses bundle_too_deep. At most 100 components per line (COMPONENTS_PER_LINE, request problem too_many_components, also at most 20 groups per level), and bundle_components_above_limit if defaults expand beyond it. Admission counts the components of each line while it builds each level and stops expanding that line as soon as the count passes 100: the line is refused at once and no deeper level is read for it, so one read carries at most 100 components per line whatever the fan-out of the defaults (nested defaults are not shared between branches, so 20 groups of 50 defaults would otherwise multiply level by level).

Refusals. Whole or nothing as today, in CatalogNotSellableError. A refusal inside a combo is a BundleAdmissionRefusal: the usual line, variantId (the line's), reason, modifierGroupId, optionId, plus path (lines[0].bundleSelections[1].choices[0]), bundleGroupId, choiceId and detail, a sentence that says how to fix it. A group or a default the client did not send points at the list where it belongs (lines[0].bundleSelections): that is where the fix goes. isBundleAdmissionRefusal narrows it. Line refusals keep their exact shape.

Statements and locks. The groups of every variant come in the same SELLABLE_FACTS statement (bundle_groups, one indexed probe); the components of all lines are read with that same statement, once per level of nesting, whatever the number of groups or lines: a combo costs one more statement, a combo in a combo two. Still one catalog version share lock; a B1 composition edit waits for open admissions (K8).

resolve (B2b, not built). Showing a combo's groups with availability on resolve would change the snapshot bytes of every variant (the snapshot is shared with admit and the till) or need a second statement with the component sellability; the till already reads the composition from B1's GET. Left for B2b with the till slice.

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

As designed. The use case, the Sales mapping, the example and the proofs are in CATALOG_USE_CASES.md, "B2 as built", and the C28 rows of CATALOG_CASE_MATRIX.md. Open for the owner: whether the depth of 3 is right; whether a group the client sends empty on a combo with defaults should mean "none" (built) or "defaults"; whether a component's sales quantity policy should bound quantity × quantityPerSelection. Whether bundle_group_unsatisfiable should also make resolve and the till call the combo not sellable is closed: B2b (§20.3) does.

20.3 B2b as built (no migration)

A combo whose required group cannot be completed is no longer sold anywhere while admit refuses it. The shared sellable rule (infrastructure/reads/sellable-rule.queries.ts) adds one fragment, bundleComposable, to sellableCandidate: no live group of the item with min_selections > 0 that is not active, or whose available choices (an active choice of an active variant of an active item) cannot reach the minimum in units, the sum of their max_selection_count (999 when absent). It is the one rule B1 answers as isSatisfiable (domain/bundles/bundle-satisfiability.ts), checked against the domain on the same rows by bundle-composable.integration-spec.ts. Since F1b it is recursive: a choice whose component is itself a combo is available only when that combo can be composed too, down to the third combo level; below it, a component combo the sale would have to open is not available, as admit refuses it with bundle_too_deep ("F1b as built" in CATALOG_USE_CASES.md). The domain twin is isComposable (domain/sellable/bundle-composability.ts). Since F1c an available choice also needs its component to be sellable on its own at the reader's unit, listed there and with its required modifiers satisfiable, the facts admit refuses it on ("F1c as built" in CATALOG_USE_CASES.md). It is written as a keyed scalar probe (anyRowOf, never EXISTS) on bundle_groups_item_idx and bundle_group_items_group_idx, so the plan does not depend on fresh statistics; the three levels are unrolled in the SQL text, never a recursive query.

Reader	Answer for a combo that cannot be completed
Till list (C17), search (C19), scan (C18)	left out, like an item that does not exist at the outlet; omittedItems does not count it
resolve	sellable: false, refusal: bundle_group_unsatisfiable (new value of the closed line domain, after required_modifier_unsatisfiable), from a new composable fact read in the same statement
admit	the bundle judgement explains it with the group and the path: bundle_group_unavailable for a suspended group, bundle_group_unsatisfiable for one whose choices cannot reach the minimum; if the groups it reads raise nothing, the line is refused bundle_group_unsatisfiable, never admitted

A plain item and a combo whose groups can be completed answer exactly the same bytes as before. Statement counts do not change: the fragment and the fact live inside the statements that already read the candidates.

20.4 B2c as built (no migration, baseline revision 114)

"B2b" names the sellable rule of §20.3; B2c is the till side. A cashier holds catalog.sellables.view but not catalog.items.view, so it could not see what a combo holds. The till read (C17) and the till search (C19) now answer bundleGroups on every item with an active group, using the field names of the B1 read: the active groups, each with only the choices admit accepts now at that outlet; a plain item has no key at all, byte for byte. The per-choice check is one exported fragment, choiceAvailable, which bundleComposable itself counts each choice with, so the set of choices the till shows and the set the rule counts are the same SQL text. A choice names its item, itself in items with its own bundleGroups, so nested trees are never duplicated; inside the third combo level the till offers only choices whose item has no bundleGroups key. No route, migration or statement is added; the ETag already moves with the catalog version. Details, the JSON and the measured cost in CATALOG_USE_CASES.md, C17 and "B2c as built".

21. M1: the structure of a menu

21.1 M1 design

Decided by the owner. A menu says what is shown: ordered sections, subsections and the items each one shows. Catalog owns its structure and, later (M2), which outlet shows which menu; Pricing owns the price by menu or time (pricing.price_book_assignments, price_rules.menu_id), Operations owns sold out, and Commerce keeps only the online storefront publication. Two menus may later be active together on one till in a fixed order (M2), and a line keeps the time it was added (S1). A retail kit or a service package uses the same menus: nothing in M1 is restaurant-only. Out of M1: outlet assignment (M2), time windows (S1), translations, tags, the till read by menu and admission by menu.

Shape: a few task routes, one replace for the tree. A manager builds a menu as one screen, so the tree is written in one call, like the combo (§19.1): PUT /catalog/menus/{menuId}/structure replaces the ordered top sections, their subsections and the ordered entries of each section. The rest are small task routes: list (GET /catalog/menus), create (POST, with an Idempotency-Key like every catalog create, a draft), read (GET /catalog/menus/{menuId}), rename (PATCH, name or code), and the two lifecycle routes POST .../activation and POST .../archival. Seven operations (six since API v7 PR 3, which folds the lifecycle into one transitions route with unpublish and restore).

Question	Decision and why
Depth	Two levels: a section and its subsections (Entradas › Frías). The SQL allows any depth with a cycle guard; two levels cover a restaurant card and a retail catalogue page, and a fixed depth keeps the request and the screen simple. A deeper menu is a later, additive change
Names	menuId, sectionId, entryId, itemId, variantIds, variantMode (all or selected, the SQL words); order is the position in the array (no sortOrder)
Section identity	sectionId when sent, else the section that holds the code sent (retired ones included), else a new id. A section keeps its id when it moves (top ↔ subsection); Kitchen rules name sections (kitchen.*.menu_section_id), so moving one keeps its routing. Each requested section is resolved to its stored identity before anything else, and two that resolve to the same one are refused as a repetition at the alias field
Entry identity	An entry is the pair (section, item), the SQL unique key: an item sent again in the same section keeps its entry even without entryId. An entry does not move between sections; entryId sent under another section or with another item is refused (catalog.menu_entry_mismatch) rather than moving a sold row (sales.order_lines.menu_entry_id)
Retire, never delete	Sales (order_lines.menu_entry_id), Commerce (cart_items), Kitchen and Pricing reference menus, sections and entries, so what the tree leaves out is retired (status = 'retired', widened CHECK) and sending it again revives the same id. The runtime gets no DELETE on them
Selected variants	menu_entry_variants has no status and nothing references it, so a changed selection deletes and inserts rows; the runtime gets DELETE on that table only. The deferred SQL check (selected needs one variant, all needs none) stays the backstop
Eligible items	A new entry shows an item of the menu's catalog that is not archived; a newly selected variant must not be archived. An entry already in that section keeps its place if its item is archived later (as B1)
Derived state	Each entry answers isAvailable (entry, section chain and item active, and one offered variant active); the menu answers entryCount and availableEntryCount. No money, no sold out
Lifecycle	draft → active (activation, gated by the plan; refused with a typed reason when the menu has no entry, catalog.menu_empty, or none available, catalog.menu_nothing_available) → archived (never gated, final, read-only). An active menu cannot be emptied (archive it instead). Back to draft is not in M1
Limits	100 menus per organization, archived ones included (the list is never paged); 50 sections and subsections, 200 entries per section, 1,000 entries per menu, 50 selected variants per entry
Version, locks, audit	Version triggers on the four tables (X15 for menus). Every command takes the version row, then the menu with its tree in one statement FOR UPDATE OF the menu. One audit action per command: catalog.menu.created, .updated, .structure_set, .activated, .archived
ETag	A strong hash of the menu answer, item and variant names and statuses included; If-Match on every write of the menu, If-None-Match answers 304

21.2 M1 as built (migration 0101, baseline revision 111)

As designed; the routes, the answers, the example and the proofs are in CATALOG_USE_CASES.md, "M1 as built", and the C21 rows of CATALOG_CASE_MATRIX.md. Migration 0101 widens the two status CHECKs, adds the creation key and hash to catalog.menus, adds the twelve version triggers, grants the runtime SELECT, INSERT and UPDATE on menus, menu_sections and menu_entries, DELETE too on menu_entry_variants, and EXECUTE on catalog.assert_menu_entry_variant_configuration(uuid) (the deferred entry triggers call it as the invoker), and seeds the resource kind catalog.menu and the five audit actions. Open for the owner: whether an active menu may go back to draft; whether display_name_override, description_override, default_variant_id and the menu description are needed on the screen; whether archived menus should stop counting toward the 100. Whether a section or an entry may be suspended from the API is closed: the standardization below takes suspended on both.

---

Standardization after M1 (no migration, baseline revision 111)

The owner closed the questions B1 and M1 left open and asked the three slices to speak one API:

• Suspension from the API. PUT .../bundle-groups takes suspended on a group and on a choice, PUT /catalog/menus/{menuId}/structure on a section and on an entry, with the modifier offer's meaning: true writes inactive, false or absent writes active (so a suspended row resumes and a retired one revives as sent). The answers carry suspended instead of status; retired stays internal. A required suspended combo group leaves the combo unsellable (bundle_group_unavailable at the list), an optional one is not offered; a suspended section takes its entries out of availableEntryCount. Suspending is gated like any other change.
• A cap per choice. maxSelectionCount (1 to the group's maxSelections, absent for no cap) is written to max_selection_count, so bundle_choice_above_maximum is reachable. B1's isSatisfiable and B2's bundle_group_unsatisfiable are one function (domain/bundles/bundle-satisfiability.ts): a required group is satisfiable when it is not suspended and its available choices, each counted up to its cap, reach the minimum.
• One name per meaning. B1's choice quantity is quantityPerSelection (the column and B2's snapshot already said so); B2's choice quantity stays the number of picks. Modifier options answer and take variantId (was itemVariantId), as combos and menus do.
• Codes. A new combo group, menu section or menu without code takes one derived from its name, like items and modifier options, instead of its id.
• Lifecycle and documentation. Activating an archived menu answers catalog.transition_invalid like every lifecycle route; PATCH on a menu is "Edit a menu" (update); the menu reads document their own 404s.
• Tables. None changed: quantity_per_selection, max_selection_count, item_variant_id and the active / inactive / retired vocabulary are already the same in bundle_groups, bundle_group_items, menu_sections, menu_entries and item_modifier_groups, and each maps one to one to the API name.

OpenAPI moves to 6.0.0 (the renames are breaking, accepted while nothing is in production).

API v7 PR 2 as built (no migration, baseline revision 111)

Items and variants change status through one route each, POST /catalog/items/{itemId}/transitions and POST /catalog/items/{itemId}/variants/{variantId}/transitions, with { "transition": "deactivate" } (or reactivate, archive, restore) and a lean answer, { itemId, status } or { variantId, status }, plus the item ETag. An archived variant can now be restored (to inactive), so archiving a variant is no longer final; a variant that sells as a modifier option (catalog_variant) still loses its offer defaults on deactivation and archival, and a restore brings none back. Choosing the default variant moved to PATCH /catalog/items/{itemId} with defaultVariantId. Details in CATALOG_USE_CASES.md, "API v7 PR 2 as built".

API v7 PR 3 as built (migration 0102, baseline revision 112)

Categories, modifier groups, modifier options and menus change status through one route each, POST .../transitions with { "transition": ... }, and answer { <id>, status } with the ETag of the category, the group or the menu. Archiving is no longer final for any of them: restore brings a category, group or option back as inactive and a menu back as draft; unpublish takes an active menu back to draft. Moving a category folded into PATCH /catalog/categories/{categoryId} with parentCategoryId. Migration 0102 seeds the six missing audit actions, and a variant restore is now recorded as catalog.item.variant_restored. Details in CATALOG_USE_CASES.md, "API v7 PR 3 as built".

API v7 PR 4 as built (migration 0103, baseline revision 113)

The barcodes of a variant are replaced as one set, PUT /catalog/items/{itemId}/variants/{variantId}/barcodes, under a required If-Match on the item tag: a barcode keeps its id, one left out is archived (status archived, migration 0103), never deleted, and suspended keeps one inactive; one catalog.item.barcodes_set record per change replaces the per-barcode added, updated, deactivated and reactivated records, and the four per-barcode routes are gone. The images of an item and of its variants are set through one route, PUT /catalog/items/{itemId}/images with { images, variants? } under one required If-Match on the item tag; a variant not sent keeps its images, and PUT /catalog/items/{itemId}/variants/{variantId}/images is gone. Each entry of the bulk PUT /catalog/item-images may carry ifMatch, and a stale one refuses the whole request with 412. Modifier offers are untouched. Details in CATALOG_USE_CASES.md, "API v7 PR 4 as built".

API v7 PR 5 as built (no migration, baseline revision 113)

A modifier group and its whole option set are replaced in one PUT /catalog/modifier-groups/{modifierGroupId} under a required If-Match on the group tag, replacing the PATCH of the group and the POST and PATCH of an option: an option keeps its id when sent back or when its code is sent again, one left out is archived, never deleted, suspended keeps one inactive, the kind and the variant of an option never change (catalog.modifier_option_target_fixed), refusals point at the option, and one catalog.modifier_group.updated record keeps the live options before and after. The options transitions route stays for taking one option off sale. The item offers and the overrides of its variants (OV1 to OV3) travel in one PUT /catalog/items/{itemId}/modifier-groups with { offers, variantOverrides? } under the item tag: a variant not sent keeps its overrides, one sent with an empty list clears them, and the variant route is gone. Every rule of §4 is unchanged. Details in CATALOG_USE_CASES.md, "API v7 PR 5 as built".

API v7 PR 7 as built (migration 0104, baseline revision 114)

Listing and delisting at a business unit travel in one POST /catalog/business-units/{businessUnitId}/assortment/listing-changes with { list, delist } (up to 200 ids each, never the same id in both); the two former routes are gone (Catalog 43 to 42 operations). Every rule of C15 is kept: the plan gates the change only when list names an item, an archived item is refused only in list, If-Match stays optional, and one items_listed and one items_delisted record are kept, each only when its direction changed. GET /catalog/items takes several statuses (status=active,inactive), includeDescendants with categoryId and hasImage, and every row, the workspace first page included, carries primaryImage { assetId, thumbnailUrl } or null, from one Assets call per page; every filter is bound into the cursor and a page stays 7 statements (8 with images). Both category filters now read the classified items once per statement, which keeps a page under 2,500 rows read on stale statistics instead of about 88,000. Migration 0104 gives the category tree its own version, catalog_versions.categories_version, moved only by category writes, and GET /catalog/categories derives its tag from it. OpenAPI moves to 13.0.0. Details in CATALOG_USE_CASES.md, "API v7 PR 7 as built".

M2a as built (migration 0105, baseline revision 115)

Which menus an outlet shows, and in what order, read and replaced as one list: GET and PUT /catalog/outlets/{outletId}/menus with { "menuIds": [...] } (Catalog 42 to 44 operations). The owner decided that these menus only organize: they never limit what the outlet sells, the assortment and the sellable rule stay the single rule, and admit is unchanged. Migration 0105 adds catalog.outlet_menus (position 0 to 9, each menu once per outlet, composite foreign keys to the outlet and the menu of the same organization), whose rows are links deleted and inserted again; its statement-level triggers move the catalog version, so the till tag changes with the assignment. The write needs catalog.assortment.manage at the outlet and, like the sibling assortment writes, the plan for any list but the empty one, so taking every menu off an outlet always works; the read needs catalog.items.view or catalog.assortment.manage at the outlet. If-Match is required on the write. A menu that starts being shown must be a draft or an active menu of the organization (404 catalog.not_found, 422 catalog.menu_archived, pointed at menuIds[i]); one already shown keeps its place when archived later, and archiving or unpublishing it keeps working, serialized through the catalog version row both take first. One catalog.outlet.menus_set record per real change keeps the ids before and after. OpenAPI moves to 13.1.0 (additive). Details in CATALOG_USE_CASES.md, "M2a as built" (C29). Next: M2b, the till read grouped by the menus of the outlet.

M2b as built (no migration, baseline revision 115)

The till snapshot, GET /catalog/outlets/{outletId}/sellable-items, gains a top-level menus key: the active menus assigned to the outlet, in its order, with their active sections and subsections and the entries whose item is in the same answer's sellable set, by ids only (variantIds only on a selected entry, and only its active configurable variants). Empty sections and menus are dropped; an outlet without menus answers menus: [] and every other key is byte for byte as before (a golden e2e). Menus still never limit what sells, and neither C19 nor C18 carries them. No migration and no route: the menus are composed inside the existing statement, so the 200 stays at 8 statements and the 304 at 7, and the tag already moves with every menu and assignment write. The item check is one lookup in a set built once from the statement's own sold set, which keeps the SQL equal to the sellable rule by construction and cheap to plan; a plan spec on stale statistics bounds it per shown entry. The payload grows about 9 % for a 300-item restaurant with two menus. OpenAPI moves to 13.2.0 (additive). Details in CATALOG_USE_CASES.md, "M2b as built".

K16 as built: outlet hidden items (migration 0106, baseline revision 116)

The owner decided (OV24) that the catalog is abstract, administered per business unit or per outlet, with no per-channel flags, and that the business unit stays the unit of assortment. Several outlets may share one unit, and until K16 nothing said "this item is not sold at this outlet". Option A was chosen: a per-outlet layer of hide-only exceptions. 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 never sell what its unit does not list; hiding an item hides all its variants; the rows stay when the outlet moves to another unit and simply apply to the new unit's assortment. Menus remain presentation: they never limit what sells.

Migration 0106 adds catalog.outlet_hidden_items (organization_id, outlet_id, item_id, created_at; primary key in that order, composite foreign keys to organization.outlets and catalog.items, the same technique as outlet_menus), its three statement-level version triggers, RLS with scalar subqueries, SELECT, INSERT and DELETE for the runtime, the audit action catalog.outlet.hidden_items_set and catalog.variant_is_listed_at_outlet(org, unit, outlet, variant), which is catalog.variant_is_listed plus two checks, that the unit operates the outlet today and that the outlet does not hide the item, without touching any existing signature. The primary key is the only index: the till probe asks for one (organization_id, outlet_id, item_id), and items and outlets are never deleted, so a reverse index would serve nobody.

One shared SQL fragment, hiddenAtOutlet, lives in sellable-rule.queries.ts and rides the SellableScope (a new optional outlet). listedInScope composes it with the assortment, so listedCandidate, the component of a combo at every level (componentSellableAt) and the listed column of resolve/admit all judge it once, in the same text; the till list and search take the outlet they already carry ($4), the scan its resolved outlet. It is a keyed anti-lookup per candidate item (anyRowOf), never an IN over the table. Correction (K16b, owner decision): PR #597 said that a combo or an option whose component is hidden at an outlet is unavailable there. For options that was not true, and the line this paragraph used to carry ("not judged by listing, kept on purpose") is withdrawn. A local must never sell what its business unit does not list or what its outlet hides, so a modifier option whose target is an item is judged like the component of a combo: its target must be active, listed by the unit, not hidden at the outlet and a plain item (an item that opens no combo group, so a combo, composable or not, is not sold as an option). availableOption takes the same scope as the rest of the sellable rule (organization, unit, optional outlet) and judges the target with the existing listing and hiding fragments, written once in targetSellable: where the option is read (the scan and the filter of the search), or in a jsonb set that the statement builds once for the many options it shows (the list, the page of the search, resolve); the structural activeOption stays for the writes, which have no unit. Without an outletId only the delisting applies. The write path refuses what the read no longer offers: creating a group or adding an option (the set) whose variantId belongs to a combo, an item with a live bundle group, answers 422 catalog.option_target_not_plain, judged in the same transaction as the write, in the statement that share-locks the variant and its item (the composition command locks the item row for update, so the two serialize; a composition that commits just before the lock is the same as one right after the write, which the reads neutralize). Rows written before this rule that point to a combo stop being offered; nothing rewrites them and the repository holds no fixture, seed or test that uses a combo as an option target (an offering item that is a combo is a different thing and is unaffected). A plain item that is composed into a combo after it became a target stops being offered the same way; there is no database constraint, which would need a migration. Details in CATALOG_USE_CASES.md, "K16b as built".

CatalogSellableContract.resolve and admit accept an optional outletId. With it, a hidden item is refused as not_listed (the vocabulary of an unlisted one), and an outlet that does not exist, belongs to another organization or is not operated by the given business unit on the date of its site is refused in the same statement with the new reason outlet_not_operated_by_unit, right after business_unit_unavailable, so hiding is never skipped by a wrong outlet; a malformed outlet answers as no unit. Without an outletId the contract judges the unit alone, a documented mode for a caller that does not know the outlet yet, and nothing changes for existing consumers. catalog.variant_is_listed_at_outlet fails closed the same way (false for a NULL, unknown, foreign or other-unit outlet). The Sales order-line trigger still calls the unit-keyed catalog.assert_variant_listed; moving it to the outlet-aware function is a Sales decision.

Routes: GET and PUT /catalog/outlets/{outletId}/hidden-items with { "itemIds": [...] } (Catalog 44 to 46 operations), at most 500 items per outlet (a restaurant outlet hides tens, a store a few hundred; the bound keeps the set one read and one ETag), If-Match required (428/412), the same gate, plan rule and closed-outlet rule as the menus of an outlet, and one audit record per real change. A set has no repeats: the schema refuses an item sent twice at the position of the repeat, and the use case compares, writes and records the distinct items. The answer repeats the item reference every other route uses (itemId, code, name, status). Whole-set PUT was chosen over a {hide, unhide} delta: the assortment of a unit uses listing-changes because its set is unbounded, while this set is bounded and, like the menus of an outlet and the structure of a menu, is replaced under the tag of the list that was read. OpenAPI moves to 13.3.0 (additive). Details in CATALOG_USE_CASES.md, "K16 as built" (C30).

S1 as built: the hours of the menus of an outlet (migration 0107, baseline revision 117)

The owner decided that a business shows different menus at different times at an outlet and that menus only organize the till screen: they never limit what is sold, admit ignores them, and the catalog stays abstract with no per-channel flag (OV18, OV24). A window decides which of the menus assigned to an outlet (M2a) the till shows now. Holidays and date ranges are out of S1 and stay deferred.

The window lives on the assignment of the menu to the outlet, not on the menu: the menu stays reusable and organization-wide, and the same "Breakfast" may open 06:00 to 11:00 at one outlet and 07:00 to 12:00 at another. A window is a set of ISO weekdays (every day when omitted) and a local from (inclusive) and until (exclusive); until earlier than from crosses midnight and the window belongs to the weekday it starts on. A menu with no window is always shown.

Migration 0107 adds catalog.outlet_menu_windows (primary key (organization_id, outlet_id, menu_id, window_number), composite foreign key to outlet_menus, number 0 to 13, the time check of pricing.price_rules_time_window_chk without any foreign key to Pricing) and catalog.outlet_menu_window_weekdays (one row per weekday of a window), with the same triggers, RLS and grants as outlet_menus. Columns on outlet_menus were rejected (a menu needs several windows and each window a repeating set of weekdays). organization.outlet_operating_context returns the site time zone as a trailing column, the smallest change that lets Catalog read the local time without reading organization tables (MODULE_CONTRACTS.md §4.4).

The route is the existing GET and PUT /catalog/outlets/{outletId}/menus (C31): windows is an optional list in the request, each entry naming its menuId, and each menu of the answer carries its windows. Overlapping windows of one menu are refused (422 catalog.menu_windows_overlap), not merged; at most 14 per menu; a body without windows shows every menu always. OpenAPI moves to 13.4.0 (additive).

The server evaluates the windows in SQL at read time, in the time zone of the site of the outlet, at an instant a Clock gives the use case once per request, so tests inject it. The till read keeps the menus open now, in the outlet order, adds menusValidUntil (the next instant the set changes) and its entity tag gains -m<mask>[-u<instant>]: the mask of the open menus by position (exact, not a hash) and that instant, so the tag moves with the clock without any write and never answers 304 for a stale set. The 304 costs no new statement. Performance in PERFORMANCE_BASELINE.md §14.11. Details in CATALOG_USE_CASES.md, "C31".

22. Sources

• Owner's architect, Ninaku Core — revisión de Catálogo, contratos, SQL y offline, 2026-10-07 (commit e0e9bdf), findings H1–H8, §12–§14 (owner's file, not in the repository)
• Square CatalogModifierList: https://developer.squareup.com/reference/square/objects/CatalogModifierList
• Square CatalogItemModifierListInfo: https://developer.squareup.com/reference/square/objects/CatalogItemModifierListInfo
• Square CatalogModifierOverride: https://developer.squareup.com/reference/square/objects/CatalogModifierOverride
• Toast size/sequence price: https://doc.toasttab.com/doc/platformguide/adminSizeSequencePrice.html
• Toast pricing strategies: https://doc.toasttab.com/doc/devguide/apiUsingPricingRulesAndPricingStrategyToCalculatePrices_V2.html
• Toast portions: https://doc.toasttab.com/doc/platformguide/adminPortionsOverview.html, https://doc.toasttab.com/openapi/menus/tag/Data-definitions/schema/Portion/
• Oracle Simphony condiments: https://docs.oracle.com/en/industries/food-beverage/simphony/simcg/t_condiments_assign_condiments_to_parent_classes.htm, https://docs.oracle.com/en/industries/food-beverage/simphony/19.5/simcg/c_condiments.htm
• Lightspeed K-Series modifiers: https://k-series-support.lightspeedhq.com/hc/articles/1260804656389
• Clover modifier groups: https://docs.clover.com/dev/docs/managing-modifier-groups-modifiers
• Shopify 2,048 variants: https://changelog.shopify.com/posts/we-ve-increased-the-product-variant-limit-to-2048
• Odoo combo choices (secondary source): https://www.cybrosys.com/odoo/odoo-books/v18/sales/combo-choices/
• Mews per person / per time unit products: https://help.mews.com/s/article/Configuring-the-pricing-details-of-a-product-based-on-age-category

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

An offer preselects options; K14a lets a preselected option start with more than one unit (two slices of cheese on the burger). The default of an option is still stored on the offer of the item (or of a variant override), never on the reusable option, and a default without a stated quantity counts one unit, so every existing offer and every payload that never uses the feature is unchanged byte for byte.

Migration 0108 adds catalog.item_modifier_group_defaults.quantity (integer NOT NULL DEFAULT 1, check 1 to 999; every existing row becomes 1) and creates catalog.item_modifier_group_option_overrides for K14b: one row per offer and option with max_quantity 0 to 999, where 0 means the option is not offered in that offer and the effective maximum will be LEAST(option max_quantity, override), so an override can never raise it. The table is a table because an offer needs one limit per option, which no column of the offer or of the option can hold. It follows the defaults table exactly: composite foreign keys to the offer (ON DELETE CASCADE) and to the option, scalar-subquery row level security, the three statement-level catalog version triggers, and SELECT, INSERT, DELETE for the runtime (rows are replaced by delete and insert). No application code reads or writes it in K14a; its contract is database/tests/contracts/catalog-offer-quantities-and-overrides-contracts.ts.

The route is the existing PUT /catalog/items/{itemId}/modifier-groups: each offered group, on the item and on a variant override, keeps defaultOptionIds and gains the optional defaultQuantities, a map { "<optionId>": quantity } for the defaults that start above one unit (integers 1 to 999). Reads that emit defaultOptionIds (the item, the offers of a group, the till list, search and scan, and the resolve snapshot) emit defaultQuantities only when at least one default is above one unit. OpenAPI moves to 13.5.0 (additive).

Judgement (judgeDefaults, then judgeQuantities): the defaults are judged first, exactly as before (422 catalog.default_options_invalid); then every default quantity must not exceed the maxQuantity of its option and the units of all the defaults (the quantity of each, one for a default without an entry) must not exceed maxSelections; a key of defaultQuantities that is not a default of the same offer is a 400 at the door (the schema), the domain refuses it too; a violation of the other rules is the new 422 catalog.default_quantities_invalid, pointing at offers[i].defaultQuantities, whose message names the three rules. A sibling code was chosen over reusing the old one because the old message says "at most as many options as the maximum" and would mislead a caller who sent one option with a quantity. A quantity change alone is a change of the offer: the change-detection key and the audit summary (o1*3 after the option id) carry it, so the item tag moves and a second identical request writes nothing. It is never a shrinking edit, so it needs the plan like any change of defaults, even when the quantity goes down (the tests are named after this decision).

admit: EffectiveOffer carries defaultQuantities; a default counts its quantity, so reducedDefaults names a default chosen with less than its quantity (defaultQuantity and quantity as in section 5.1), removedDefaults names one left out with its quantity as defaultQuantity, a default that is no longer available is never named and a preselection is never added (OV7). The bundle components use the same function.

An option write still does not judge offers again (K5 design note): lowering the maxQuantity of an option below a stored default quantity succeeds. The till, search, scan and resolve read the effective quantity least(default quantity, option maxQuantity) and leave it out when it falls to one, so a till never preselects more than the option allows; the read of the offer for the back office answers what was stored until the next offer write judges it again.

Cost: the quantities are one more keyed probe on the defaults table per offer, in the same statements as the ids and only through rows above one unit joined to the option; data without quantities above one unit pays the probe only. The till plan spec keeps its ceilings (PERFORMANCE_BASELINE.md §14.12 records the buffers before and after). Proofs: test/e2e/catalog-offer-default-quantities.e2e-spec.ts and the unit specs of modifier-offer, admitted-offer, the request schema and the responses. Details in CATALOG_USE_CASES.md, "K14a as built" (C13).

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

An offer can now lower the maximum of an option for itself, or withhold the option altogether: a burger offers bacon at most once while the combo of the same burger offers it up to three times, and the kids' variant does not offer it. The limit lives on the offer (the item's or a variant override's), never on the reusable option, so the option and every other offer of it are untouched, and an offer without limits behaves and answers exactly as before, byte for byte. No migration: the table catalog.item_modifier_group_option_overrides that 0108 created is read and written now (one row per offer and option, max_quantity 0 to 999, runtime SELECT, INSERT, DELETE).

The route is the existing PUT /catalog/items/{itemId}/modifier-groups: each offered group, on the item and on a variant override, gains the optional optionLimits, a map { "<optionId>": maxQuantity } of integers 0 to 999. The body stays strict. The effective maximum of an option in an offer is LEAST(option max_quantity, limit); a limit can never raise it, so one that is equal to or above the maximum of its option is refused as a limit that would raise or do nothing, with the new 422 catalog.option_limits_invalid pointing at offers[i].optionLimits.<optionId> and a message that names the option and its real maximum (a limit on an option that is not an available option of the group is refused with the same code). 0 means the option is not offered in that offer.

Judgement (judgeOne): the limits first, then the rule, the defaults and their quantities, all against the effective maximum. The units an offer can reach (reachableUnitsOf) are the sum of the effective maximum of the available options, so a minimum above them is selection_rule_invalid, as before, and a group whose every option is limited to 0 cannot be required; a default cannot be an option limited to 0 (default_options_invalid) and a default quantity cannot exceed the limit (default_quantities_invalid). A limit already stored for the same option in the same offer is not judged again: lowering an option below a stored limit makes the limit moot (the LEAST wins) and is not an error, and reading an offer and sending it back never fails because of it. The change-detection key and the audit summary carry the limits (;limits=o1=1+o2=0 after the status and the defaults), so a limit-only edit moves the item tag and is audited, and, like a quantity-only edit, it needs the plan, lifting limits included.

Writes: the limits are replaced as a set in the same transaction as the offer, after the defaults: the statements of the scope delete the limits of the offers of the scope and insert the sent ones (a group that leaves the list loses its limits). The lock order is unchanged (catalog version, then the item, with FOR SHARE on the groups of SHARE_LOCK_GROUPS), so there is no new race: an option written meanwhile is judged by the existing rule that option writes do not judge offers again (K5 note), and the lost-option race maps to the same 422 as an invalid limit.

Reads: the item read, the offers of a group (C12) and the till list and search answer optionLimits only when the offer limits an option. The item and group-offer reads answer what is stored. The till answers only the limits of available options that really lower their option (limit < maxQuantity), as a map on the offer (of the item and of a variant override), so the client takes the lower of the maxQuantity listed once per group and the limit of the offer; 0 means the option is not offered in that offer. This is the leanest correct shape: the options of a group are shared by every item of the page and listed once, and repeating them per offer would multiply the payload for a rare feature. resolve and admit answer per effective offer, so there the options are already reduced: an option limited to 0 is absent (a selection of it is option_not_offered, since it also leaves the offered ids) and maxQuantity is the effective maximum (more is option_quantity_above_maximum); an offer left with no option is dropped. domain/sellable/sellability.ts keeps its single map by option: an option belongs to one group and a variant has one effective offer per group, so no option can sit in two offers of a line. The Sales and Commerce triggers check only the option's own maximum; a limit is stricter, never looser.

Sellability: variantConfigurable, the one fragment of the till, the search, the scan, resolve and admit, sums least(option max, limit of the offer); a required offer the limits leave unable to reach its minimum makes the variant unsellable everywhere with required_modifier_unsatisfiable, the same answer as a lowered option.

Cost: the shared sellability fragment asks once per offer with a minimum whether the offer has any limit (a one-row keyed probe) and only offers with limits probe each option; the till offers and the offers of resolve and admit ask once per statement which groups of the organization have limits (a one-row probe on the group index per group); the item read asks once per group of the item. Data without limits pays those probes and nothing per option: about +6 % buffers on the till read of 2,000 items and +12 % on resolve of 100 variants, against +24.5 % and +53 % for the first version that probed per option and per offer. Putting the group set also inside the shared fragment was cheaper (+0.44 %) but inflated the estimated cost of the nested combo plans and made the menu plan spec unstable, so it was not kept. PERFORMANCE_BASELINE.md §14.13 records the numbers. OpenAPI moves to 13.6.0 (additive). Proofs: test/e2e/catalog-offer-option-limits.e2e-spec.ts, the unit specs of modifier-offer-limits, option-limits, offer-list-judgement, the request schema, the responses and the statements. Details in CATALOG_USE_CASES.md, "K14b as built" (C13).

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

The matrix (POST /catalog/items/{itemId}/variant-matrix) used to write only concatenated codes and names (m-azul, M / Azul). It now also persists the dimensions it names, their values and the link of every variant to its values, so "every blue variant" and "the items that have an M" are questions SQL can answer. The four tables, their keys, grants and triggers are in database/README.md (revision 119) and justified in DECISIONS.md D34; the routes and payloads in CATALOG_USE_CASES.md, "K13 as built" and C32.

What changed from section 8:

Design	As built
"At most 3 per item, enforced in the database (trigger)"	No trigger: item_variant_dimensions.sort_order is 0 to 2 and unique per item, so a fourth dimension has no free position and the check constraint and the unique key refuse it, with no read and no lock. The matrix schema also refuses more than three dimensions with a 400
"A deferred constraint trigger refuses two active variants of one item with the same set of values"	Built as two triggers sharing one function: a deferred constraint trigger on the links and an immediate trigger on a variant that becomes active. The first version compared the whole item on every link row and a 500 variant item exceeded the 5 s statement timeout; it now checks once per variant (only the row of the first dimension of the variant reads, the others return) and compares only with the active variants that share that value, through item_variant_dimension_values_value_idx. It serializes per item with FOR NO KEY UPDATE on the item row, the lock the item commands already hold after the version row, so the lock order is unchanged. Variants with no links (the default variant, the ones made before dimensions) are tolerated. Completeness (a linked variant holds a value of every dimension of the item) is the application's: the matrix always links every dimension
Failure of the check	A deferred trigger would fail at COMMIT, after the use case returned. The matrix therefore runs SET CONSTRAINTS ... IMMEDIATE for the trigger of the links right after it writes, inside the repository. The trigger of a variant that becomes active is immediate (a plain AFTER UPDATE OF status row trigger), so the status UPDATE itself fails and the transition keeps its statement budget. Both map the 23505 of item_variant_dimension_combination_uq to 409 · catalog.variant_combination_taken
"Find-or-create the dimensions by derived code"	The code of a dimension is its name reduced like an item code (itemCodeFromName, lowercase letters and digits joined by hyphens, dimension when nothing is left); two dimensions of one matrix that reduce to the same code are a 400. A dimension is found by that code ignoring case in the default catalog; a value by the code the request sends (the matrix always sent value codes), ignoring case, inside its dimension. What exists keeps its stored name and its stored code case
"Value identity survives a rename"	The value has its own id and code; renaming and archiving a dimension or a value is not built (the runtime holds SELECT, INSERT only), so nothing can yet move or retire one
Re-apply links old variants	A cell whose code exists, not archived, with exactly the name, SKU and quantity policy of the cell and no links is linked; one already linked to the same values is in effect; any other case is 409 · catalog.code_taken. A matrix that only links answers 200, one that creates answers 201, one with nothing to do answers 200 and writes nothing
Dimensions of an item are fixed	The first matrix attaches them; a later matrix names the same dimensions in the same order (it may add values) or answers 422 · catalog.variant_dimensions_locked, whose detail names the dimensions the item has
Filter	variantValue=<dimension code>:<value code>, repeatable up to three times for different dimensions, asks for one active variant carrying every value. The design said "AND across dimensions"; a per-variant meaning is the one a shopper means by "blue M", and the other (an item with a blue variant and an M variant) is one request per value away. The same dimension twice is a 400, because one variant holds one value of it

Statement budget of the matrix: 18 for the first matrix of an item, 16 for one that adds values, 16 for one that only links, whatever the number of cells (catalog-variant-matrix-statement-budget.e2e-spec.ts). Plan evidence and the before and after of the item read and the item list are in PERFORMANCE_BASELINE.md, section 17.

Not built, in the order they will probably be needed:

1. Renaming, archiving and ordering dimensions and values (needs UPDATE grants and a route per use case), and a value translation table.
2. A cap on dimensions per catalog and values per dimension. The matrix itself caps three dimensions of fifty values per command, and GET /catalog/variant-dimensions answers every active one; no creation limit exists yet.
3. Dimension values in the till and sellable payloads (the variant code and name remain what a till sells by), and the filter in the till search.
4. perf:http scenarios that seed dimensions, to measure GET /catalog/variant-dimensions and the filter over HTTP with 1 and 16 clients.
5. Descriptive attributes that do not define a variant (material, fit) wait for a reader with a name, as section 8 already said.

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

A modifier option can now be a text the customer types (an engraving, a cake message) and can carry a prefix and two print hints. Everything is a column of catalog.modifier_options: no table, policy, trigger or grant is added (DECISIONS.md D36). The write route is the existing PUT /catalog/modifier-groups/{modifierGroupId} (and the create POST /catalog/modifier-groups, which shares the option schema); each option of the set gains kind: "text", textMaxLength, prefix, printsOnReceipt and printsOnKitchenTicket. The set is a replacement, so a field left out means its default: an option sent back without its textMaxLength or prefix loses it, and the group read answers every field to send back.

What Catalog enforces (the domain judges every option of the sent set, in option-presentation.ts, and the database backs each rule with a CHECK; the 422 · catalog.modifier_option_presentation_invalid names the option and the rule at the field):

Rule	Field	CHECK
kind is instruction, catalog_variant or text; a text option names no variant	kind, variantId	modifier_options_kind_chk, modifier_options_kind_target_chk
textMaxLength is a whole number from 1 to 500 for a text option and absent for any other kind	textMaxLength	modifier_options_text_max_length_chk
A text option holds exactly one unit (maxQuantity 1) and no prefix or add	maxQuantity, prefix	modifier_options_text_shape_chk
prefix is one of add, extra, light, no, on_the_side, substitute	prefix	modifier_options_prefix_chk
light, no, on_the_side and substitute need maxQuantity 1	maxQuantity	modifier_options_prefix_quantity_chk
no, on_the_side and substitute apply to instruction options only	prefix	modifier_options_prefix_kind_chk

What Catalog does not enforce. extra accepts any maxQuantity; "extra as a scale effect needs quantity 1" (X11) is Production's rule on its own effect, refused when the sale quantity is not 1, and Catalog does not read Production (OV18). The prefix never changes a price, a stock movement or a sale. The print hints are hints: Catalog does not print and no sale rule reads them; both default to true, there is no per-channel flag (OV18, OV24). The kind of an option never changes (catalog.modifier_option_target_fixed), so an instruction option cannot become text.

Per K5, an option write does not judge the offers that already hold the option: a prefix that needs maxQuantity 1 is judged when the option is written, and the database refuses the state anyway.

Reads: the group read, the group write answer and the item read carry the new fields on an option only when they differ from the default (kind is always there; textMaxLength and prefix when set; printsOnReceipt and printsOnKitchenTicket only as false), so every payload and tag of existing data is byte-identical. The till, the search, the scan, resolve and admit are K14d. Sales must add a text branch to its kind check (X10) and a column for the typed value (X3) before it consumes text options; until K14d no reader outside the group and the item read can see a text option.

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

Reads. The till read (GET /catalog/outlets/{outletId}/sellable-items, its modifierGroups[].options[]), the snapshot of resolve and admit (offers[].options[]) and, since K14c, the item read answer an option's textMaxLength, prefix, printsOnReceipt: false and printsOnKitchenTicket: false only when they differ from the default (kind is always there, so a text option says kind: "text"). Existing data therefore answers the same bytes, tags and golden files as before. The search and the scan carry no option, so they are unchanged. The four columns join the SELECT that already reads the option (the available_options CTE of the till and the option subquery of the snapshot), so no statement and no probe is added; the plan specs of the till, the search and the sellable facts pass with their ceilings untouched. The database hands the presentation of an option as one stripped JSON object (presentation) and the repository flattens it, so a default option has no extra key and no null.

The selection. OptionSelection gains an optional text; AdmittedSelection carries it back. All of it is additive and optional in CatalogSellableContract, and a consumer that never sends text sees no difference. Before any lock, the request normalizes every text to NFC (a composed and a decomposed é are one text, and the length is counted after normalizing, in characters and not code units) and refuses a line with more than 10 selections carrying text, those of the components of a combo included, with the request problem too_many_texts. After the sellable verdict, per selection and after the option is found and its quantity is within its maximum, the domain judges the text with the same refusal list as any other selection (optionId names the option):

Reason	When
text_required	the option is of kind text and the selection carries no text
text_not_allowed	the option is not of kind text and the selection carries text
text_invalid	the text is blank (only white space) or holds NUL or any control character, a line break and a tab included
text_too_long	the text has more characters than textMaxLength, which never exceeds 500

A text option is held to one unit by its maximum, so a selection of two is option_quantity_above_maximum before its text is judged. Sellability needed no change: a text option has no target variant, so it is available while it is active, and a required group whose only option is text is satisfiable with quantity 1 (proved by catalog-text-selections.e2e-spec.ts). Defaults are not refused for text options in this slice: a text option preselected on an offer would have no value to preselect, and admit never adds a default (OV7); the offer writer does not forbid it yet.

What stays outside. Catalog does not store the text: Sales will. Sales must add the text branch to its kind check (X10) and a column for the value (X3) before it consumes text options; until then nothing consumes text. The refusal details a combo component answers (bundle-refusal-detail.ts) have a sentence for each new reason.

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

Decision DECISIONS.md D41; routes in CATALOG_USE_CASES.md, "K12b as built". The Sync module does not exist, so the bootstrap is a Catalog read API (owner decision); what Sync must add is listed below.

Design (§7.2, §7.4)	As built
Read at one catalogVersion: a REPEATABLE READ snapshot per page set, or pages pinned to a version and restarted only for the pages a later delta touches	Pages pinned to a cut, restarted when the cut moves. Each request runs in its own REPEATABLE READ read-only snapshot (runReadOnlySnapshot), so permission, cut check and data are coherent; across requests the pin is an equality check of (catalog version, structure version, unit) against the cut the opening call answered, made in the same snapshot as the page. If every page of a walk saw the same cut, no catalog or structure write committed between the first and the last read, so the pages are exactly the catalog at that version. Rejected, with evidence: a snapshot per page set cannot span HTTP requests (a PostgreSQL snapshot lives in one transaction on one pooled connection; holding it for a whole download pins a connection and the vacuum horizon per device), and "restart only the pages a delta touched" needs the rows as they were at the cut, which rows updated in place do not keep. Cost: a write during a download restarts it; with pages of 100, 3,000 items are 30 pages
Unlimited items in pages	Keyset on (name_search_key, id), 1 to 100 per page (the HTTP contract), no ceiling; the same sellable rule as the till reads (OV24: the unit decides, the outlet only hides)
SKU and the barcode index of what the outlet sells	sku and the active barcodes[] on each variant of a sold item; the device builds barcode -> variant locally. An archived barcode, an inactive variant and an item the outlet does not sell are never in it
Deltas applied in version order, idempotent by event id, no gap and no duplicate	The cut carries the catalog version V; the device applies the feed events with catalogVersion > V, in publication order, and skips the rest. A retry of a page is a GET with no effect (same cut and cursor, same page); a retried event is idempotent because a retired change deletes by id and an upserted change rereads by id
Tombstones	The bootstrap holds only live data. A retired or removed change deletes what its id names: an item event the item with its variants and barcodes; a variant event the variant with its barcodes; a barcode event the barcode
Brands and variant dimensions	Not in the bootstrap. They move the catalog version and write no event (K12a). No till screen and no till read shows them, so including them would leave devices stale without anything announcing it; excluding them is the sound option. The slice that shows them on a till adds them to the bootstrap and maps their tables to events together
Permission change or revocation	Each call decides catalog.sellables.view at the outlet again: a revoked permission or a scope moved to another outlet stops the next page with the plain 403. What the device already holds is not erased by the API: invalidating a device grant is Sync (next session) and K12c
Switching business unit	The cut names the unit; the cut of another unit is refused with 409, the data of two units never mix, and a cursor is bound to the cut, the outlet and the organization

What Sync must add. (1) A delta read: the catalog.* events of the organization after a version or a publication position, which catalogVersion already orders. (2) A reread by id of one aggregate (an item with its variants and barcodes, resolved from an item, variant, barcode or offer id; the reference data again for a modifier or category event). (3) The device grant and its revocation. (4) The rule for what a device does with local sales when its grant is revoked (K12c). The feed's ids are enough to delete; they are not enough to reread a new variant or barcode whose item the device does not know, which is why the reread belongs to the server.

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

Decision DECISIONS.md D40; no route and no OpenAPI change (the feed is written, not served: serving it to a device is K12b and the Sync module).

Design (§7.2)	As built
Every catalog command writes typed events in its transaction	Not in each command: statement-level triggers <table>_change_feed_{insert,update,delete}_trg on 28 tables call catalog.record_change_feed(). They sort after the table's version trigger, read the version the statement just produced and write one event per changed aggregate through events.append_tenant_event (the function Events publishes, MODULE_CONTRACTS.md §4.5). catalog.record_change_feed() is SECURITY DEFINER, so the runtime role needs no privilege on events. Catalog writes no events table (OV18) and a command cannot forget to announce a write
item, variant, barcode, offer, listing	Nine types, contract version 1: those five and catalog.modifier.changed, catalog.bundle.changed, catalog.menu.changed and catalog.category.changed, because the till reads categories, modifier groups and options, combos and menus (C17) and a device that cannot learn that an option was renamed cannot apply the delta. The mapping is the table below
Payload with catalogVersion, ids and a tombstone { id, retiredAt }	{ schemaVersion: 1, catalogVersion, change, <id>, status?, retiredAt? }. change is upserted, retired (the aggregate's status became archived or retired) or removed (the row was deleted); retiredAt (UTC, microseconds, Z) is present exactly when change is not upserted; status is present when the event comes from the aggregate's own row (an inactive item is an upsert that says inactive). No names, prices, barcode values or secrets: the device rereads by id. The ids are itemId, variantId, barcodeId, offerId, modifierGroupId, bundleGroupId, menuId, categoryId and, for a listing, one of { catalogId }, { businessUnitId, catalogId }, { businessUnitId, itemId }, { outletId, itemId }, { outletId, menuId }. The executable contract is src/modules/catalog/contracts/catalog-change-event.ts
The version assigned and the event written under the same lock	A command takes the version row FOR UPDATE first (the existing lock order); the bump trigger updates it; the feed trigger reads it and appends the event, then Events takes the publication counter of the organization. A reader that sees catalogVersion = N committed sees every event of version at most N, and the publication position follows the version because both are taken in that order. The lock order is now: catalog version row, then the item and the rest of the catalog, then the publication counter (DECISIONS.md D40: another module that emits events must do so after admit)
An event per aggregate, not per command	One event per distinct aggregate per statement, at the version that statement produced; a command of several statements announces each version it produced, so, for a command that writes only the mapped tables, the versions of its events cover its whole range
Idempotent retry	A retried create returns the stored answer and runs no write, so it announces nothing (Idempotent-Replayed: true); inside Events the idempotency key catalog-change:<version>:<event>:<md5 of the payload> makes the same event append once
Version triggers on every table a device reads	Checked by a query, not by memory: every table that till-read, till-menus, till-scopes, till-bundle-groups and the sellable reads touch already carried the three triggers (menus, bundles and item_assets by 0101, 0100 and 0095). 31 tables carry them; 28 write events. The 17 tables without version triggers (allergens, allergen_translations, dietary_tags, dietary_tag_translations, item_allergens, item_dietary_tags, item_nutrition_profiles, item_nutrition_facts and the nine other *_translations) are read and written by no use case: they get their triggers and their mapping with C23 (translations) and C24 (food data)

Mapping (root rows carry status and can retire; child rows always report their root as upserted):

Event	Root	Children
catalog.item.changed	items	item_categories, item_assets, item_regulatory_flags, item_variant_dimensions
catalog.variant.changed	item_variants	item_variant_identifiers, item_variant_dimension_values
catalog.barcode.changed	item_variant_barcodes
catalog.offer.changed	item_modifier_groups	item_modifier_group_defaults, item_modifier_group_option_overrides
catalog.modifier.changed	modifier_groups	modifier_options
catalog.bundle.changed	bundle_groups	bundle_group_items
catalog.menu.changed	menus	menu_sections, menu_entries, menu_entry_variants
catalog.category.changed	categories
catalog.listing.changed	catalogs, business_unit_catalogs, business_unit_items	outlet_hidden_items, outlet_menus, outlet_menu_windows, outlet_menu_window_weekdays

product_brands, variant_dimensions and variant_dimension_values move the version and write no event: no till read uses them yet. K12b decides whether the bootstrap carries brand and dimension labels, and maps them then.

What the feed does not promise.

• A write outside a tenant context (a migration, an administrative tool) moves the version and writes no event, because Events requires the tenant. A device whose version is behind a version with no event must bootstrap again; a migration that changes catalog data says so.
• An update that changes no column still bumps the version and announces its rows: the version triggers never compared values, and the feed follows them.
• One event per aggregate per statement: a statement over 500 rows writes 500 events, and a command of ten statements writes at least ten.
• catalog.listing.changed for a business_unit_items or outlet_hidden_items row names the item, not the variants it covers; the device rereads the item.

Evidence.

Claim	Proof
Statement order, version per event, tombstones, children, no tenant context, rollback, other tenants, immediate constraints, the event function's refusals, no direct access to events	database/tests/contracts/catalog-change-feed-contracts.ts (NINAKU_CATALOG_CHANGE_FEED_OK)
Every table that bumps the version writes events or is on the exclusion list; the feed trigger fires after the version trigger; the tables without version triggers are exactly the pending ones	the same contract
Two commands that lock the version row: distinct increasing versions, events in the same order, the second waits	database/tests/concurrency/catalog-change-feed-concurrency.ts
Over HTTP: create, archive and restore, offers and their tombstone, modifier groups, idempotent replay, four parallel creates, a business unit registered (a deferred trigger that writes at commit)	test/e2e/catalog-change-feed.e2e-spec.ts
A command that fails after its write leaves no event, no outbox row and no version move	test/e2e/catalog-modifier-offer-identity.e2e-spec.ts › leaves the offers, their ids, the audit trail, the announced changes and the version untouched when the record fails after the write
The payload contract	src/modules/catalog/contracts/catalog-change-event.spec.ts
The runtime role has no privilege on the events schema, its tables or the function (the trigger is SECURITY DEFINER)	database/tests/prepare/prepare-database-contracts.ts (NINAKU_PREPARE_RUNTIME_PRIVILEGES_OK) and the contract above

For K12b. The feed gives a device the ids that changed after a version; it does not serve them. K12b needs: a read of the events after a position or version for a device (Sync owns the cursor and the acknowledgements); the bootstrap at one catalogVersion with SKU and barcode index; whether brands and dimensions are part of it; and the rule for a device whose version is behind a gap with no event (bootstrap again).

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

Decision DECISIONS.md D39; routes in CATALOG_USE_CASES.md, "K15d as built".

Design (section 17)	As built
item_variant_identifiers (item_variant_id, scheme, value), scheme mpn, isbn or manufacturer_code, unique per variant	As designed, with the denormalized item_id, organization_id and catalog_id of the K13 tables, an index by item for one probe per item, and the primary key (item_variant_id, scheme); SELECT, INSERT, DELETE for the runtime
Value bounded and NUL-free, not unique across variants	varchar(100), not blank; the schema trims it and rejects NUL (PostgreSQL cannot store it); two variants may hold the same value
Set inside the existing variant write	identifiers (optional) on defaultVariant of the item create, on the variant add and on the variant edit, where it replaces the set and an empty list clears it; the variant matrix does not take it
Shown in the item read	identifiers on a variant only while it has any, so every existing payload, tag and golden file is byte-identical. Channel identifiers stay out

Not built: lookup by identifier, GTIN checks (barcodes keep them) and identifiers on the matrix.

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

Decision DECISIONS.md D38; routes in CATALOG_USE_CASES.md, "K15c as built".

Design (section 17)	As built
catalog.product_brands, not the organization.brands of Organization	Table with a unique case-insensitive name per catalog, active/archived status, idempotent creation and a composite key; items.product_brand_id is a nullable composite foreign key and Catalog never references organization.brands
List, create, rename, archive	GET/POST /catalog/product-brands, GET/PATCH /catalog/product-brands/{id} (renaming needs the strong tag) and POST /catalog/product-brands/{id}/transitions (archive, restore)
Item side	productBrandId on the item create and edit (null clears it); the item read answers productBrand { id, name } only when set; GET /catalog/items?productBrandId= is a candidate filter, part of the cursor binding
Archiving a brand that active items use	Allowed: the item keeps its brand and stays listed under it; only giving an archived brand to an item is refused (422 · catalog.product_brand_archived)

Not built: a brand on a variant, merging brands, and brand logos.

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

One expand-only migration, four hardenings, no new route. The decision for the flags table is DECISIONS.md D37; the routes and payloads are in CATALOG_USE_CASES.md, "K15a as built".

Design (section 17)	As built
Description bounds on items, categories and modifier groups, NOT VALID then VALIDATE after proving no row breaks them	catalog_items_description_chk, categories_description_chk and modifier_groups_description_chk: description IS NULL OR char_length(description) <= 2000, each added NOT VALID. The routes stop at 2000 characters (ITEM_DESCRIPTION_MAX_LENGTH, CATEGORY_DESCRIPTION_MAX_LENGTH, shared by the modifier groups), but an imported or hand-loaded row is not proved, so the migration validates the constraint only when an audit query finds no breaking row (a DO block); otherwise it keeps it NOT VALID, raises a WARNING with the count and changes no data
CHECK that the minimum and the maximum are multiples of the step	item_variants_sales_quantity_step_chk: minimum_sales_quantity % sales_quantity_step = 0 and, when there is a maximum, maximum_sales_quantity % sales_quantity_step = 0. Unlike the descriptions this one cannot be proved against stored data: the API accepted any policy that satisfied item_variants_sales_quantity_policy_chk, so a stored variant with a minimum of 0.1 and a step of 0.25 would fail the VALIDATE. The migration therefore audits first: with no such row it validates, with one it keeps the constraint NOT VALID (new writes are checked) and warns with the count, and the owner of the data corrects the rows (SELECT id FROM catalog.item_variants WHERE minimum_sales_quantity % sales_quantity_step <> 0 OR maximum_sales_quantity % sales_quantity_step <> 0); an unrelated update of such a row is refused until it is corrected. Note the domain rule fitsSalesPolicy measures the grid from the minimum, so a minimum off the step was a legal, if odd, policy before; the check makes the grid start at zero. A violation answers 422 · catalog.quantity_policy_invalid
net_content_quantity, net_content_unit_code on the variant, both or neither, the unit validated by the application, no foreign key	numeric(20,6) and varchar(30), item_variants_net_content_chk (both null, or a positive quantity with a non-blank unit). The unit is checked against reference.units_of_measure by one statement that runs only when a request sends a unit (422 · catalog.unit_unknown, the code of an unknown sales unit, so no new code for it); a pair with one half is 400 at the schema and 422 · catalog.net_content_invalid if it ever reaches the database. Written with the create of an item (defaultVariant), the add of a variant and the edit of a variant (null in both clears it); the matrix does not carry it. Answered on the variant only while set; the audit of a variant edit names catalog.item.variant.net_content_quantity and catalog.item.variant.net_content_unit. The price per unit stays Pricing's
item_regulatory_flags (item_id, flag) with the five flags, RLS, version triggers, GRANT SELECT, INSERT, DELETE	As designed, with the composite foreign key (item_id, catalog_id, organization_id) of the K13 tables. Written with the create of an item and by PATCH /catalog/items/{itemId} with regulatoryFlags (the whole set, an empty list clears it; each flag once, kept in the order of the vocabulary); the item read answers regulatoryFlags only on an item that has any. One audit record per edit, catalog.item.updated, with catalog.item.regulatory_flags before and after next to the profile changes. Catalog declares and enforces nothing
Drop catalog_items_organization_status_idx only after EXPLAIN proves it unused	Decided at the end of the delivery from the plans; see PERFORMANCE_BASELINE.md

Not built: a route to list items by flag (no reader needs it yet), a flag on a variant, and any enforcement at sale time, which belongs to Sales or a compliance module reading the flag through a contract.