@12-apps/discounts 1.1.0 → 1.3.0

package/README.md

@@ -131,7 +131,7 @@ bundle, if a host wants one, stays the host's.
 
 ## The admin surface
 
-`createApiDiscounts({ store, copy })` returns five `WireRoute` descriptors —
+`createApiDiscounts({ store, copy, logger })` returns five `WireRoute` descriptors —
 list, read, create, re-state, archive — each **declaring the permission it
 needs** (`discounts:read` / `discounts:write`), so a host's coverage gates can
 read the policy off the assembled table instead of scanning route files.
@@ -140,7 +140,11 @@ read the policy off the assembled table instead of scanning route files.
 import { createApiDiscounts } from "@12-apps/discounts/server";
 import { PT_BR_DISCOUNTS_SERVER_COPY } from "@12-apps/discounts/server/pt-BR";
 
-const { routes } = createApiDiscounts({ store, copy: PT_BR_DISCOUNTS_SERVER_COPY });
+const { routes } = createApiDiscounts({
+  store,
+  copy: PT_BR_DISCOUNTS_SERVER_COPY,
+  logger: createFeatureLogger("discounts"),
+});
 ```
 
 Or, through the contract:
@@ -152,7 +156,9 @@ import { discountsServerManifest } from "@12-apps/discounts/manifest/server";
 host.adoptServer({
   manifest: discountsManifest,
   server: discountsServerManifest,
-  bindings: { http: { mountPath: "/api/admin/:tenantSlug", config: { store, copy } } },
+  bindings: {
+    http: { mountPath: "/api/admin/:tenantSlug", config: { store, copy, logger } },
+  },
 });
 ```
 
@@ -160,24 +166,239 @@ Delete is a **soft archive**, and that is a product decision: the orders that
 already redeemed a discount keep their snapshot, and its redemption counter
 stays readable for reporting.
 
+### Nothing it does is silent
+
+`logger` is **required config, with no default**, for the reason `copy` is: the
+default would be a no-op, and a no-op is the exact silence it exists to end.
+Every route is wrapped, and there are three outcomes:
+
+| outcome | level | what the line names |
+|---|---|---|
+| a write that succeeded | `info` | the verb, the discount id, the tenant |
+| a refusal this package decided (400 / 404 / 422) | `warn` | the route, the status, and for a 422 the **field** a form paints red |
+| anything thrown — and it is re-thrown unchanged | `error` | the route, the tenant, the cause's message |
+
+Every line is a **string**. A host's logger is a Winston child in practice,
+whose formatter runs `util.inspect(…, { depth: 5 })` over an extra argument —
+which is how a provider error's retained response body, buyer name and CPF
+included, reaches a third party. The cause is folded into the sentence instead.
+A line names the tenant, the route, the discount id and the field; never the
+body, never a coupon code, never a name an operator typed.
+
+The `error` case **re-throws**. A uniqueness clash, a foreign target and a dead
+connection are the store's to raise in the host's own error vocabulary; a
+surface that folded one into a tidy response would turn a broken database into a
+refusal nobody investigates.
+
+A host adopting through `@12-apps/wiring/consumer` already has the logger the
+binder built from this package's declared namespace — pass
+`assembled.loggers["@12-apps/discounts"]`. A host on no wiring passes any
+`createFeatureLogger`-shaped child of its own.
+
+The evaluator is deliberately **not** wired to it. `evaluateCart` is a pure
+function called once per cart render; a logger there would file a line per
+keystroke on the storefront and would need a logger threaded through a browser
+bundle. A rejected coupon is already a `DiscountRejection` in the result, which
+is the host's to report if it wants to.
+
+## Letting a host table opt in — `DiscountableCollection`
+
+A discount points at rows this package will never see: a store's categories, its
+products, and — the day a host wants it — its suppliers or its shelves. Every
+question about them ("which exist", "are they this tenant's", "what is this one
+filed under") is answerable only by the host, so the host DECLARES the table:
+
+```ts
+const categories: DiscountableCollection = {
+  targetType: "CATEGORY",
+  slug: "categories",
+  label: "Categorias",          // host vocabulary, host language
+  nests: true,
+  ops: {
+    list: (clientId) => …,      // the picker's rows
+    ownsAll: (clientId, ids) => …,   // the cross-tenant guard
+    parents: (clientId) => …,   // child → parent, for the ancestry walk
+  },
+};
+
+createApiDiscounts({ store, copy, logger, collections: [categories, products] });
+```
+
+Three pieces of hand-written host code collapse into it:
+
+| host code | becomes |
+|---|---|
+| a per-table cross-tenant `count` before every write | `ops.ownsAll`, run once per write for every dimension |
+| the tenant's category tree loaded, and an ancestor walk with a cycle guard | `ops.parents` + the package's own `buildTargetPath` |
+| an admin page side-loading two catalogs at `?pageSize=500` to feed a picker | `GET /discounts/targets`, one round trip |
+
+Two things it fixes as a side effect. The ownership check now covers the ids
+inside a **combo's slots** — a combo scope drops the top-level target pair and
+carries its targets in the slots, so a host checking only the pair let a crafted
+combo name another store's products. And the ancestry walk stops being a second
+implementation: the host builds the cart lines this package prices, so both
+sides now read the same `buildTargetPath`.
+
+The check runs OUTSIDE the store's transaction, and that is enough for the leak
+that matters: a catalog row's tenant never changes, so an id owned by this
+tenant now cannot belong to another one by the time the write lands. The only
+race left is a target deleted in between, whose outcome is a discount pointing
+at a row that no longer exists — which the evaluator already tolerates.
+
+`collections` is **optional**, and the omission is a real configuration: a host
+that sells one undifferentiated thing has no dimension to register. What it
+costs is stated rather than defaulted around — with nothing registered,
+`GET /discounts/targets` answers `[]` and the cross-tenant check stays the
+store's job.
+
+### Why this is not a wiring capability yet
+
+`@12-apps/wiring`'s contract folder holds http, web, mcp, db, env, jobs, email,
+notifications and permissions — there is no registration or extension concept,
+so promoting this would mint a new capability on two instances that are less
+alike than they look: `@12-apps/entity-lifecycle` registers a collection it
+DRIVES, with write ops, while this registers a catalog dimension it only
+QUERIES. Abstracting one contract over both risks fitting neither. It ships
+here, shaped deliberately like its sibling so the family resemblance is visible,
+and a third consumer is what would earn it a place in the contract.
+
+`DISCOUNT_TARGET_TYPES` is closed at two today. That is a boundary, not a
+principle: a third dimension is expressible the moment targets are stored **by
+value** (`(target_type, target_id)`) instead of as a join table per member, and
+the registration is shaped so that widening the array plus registering one more
+collection is the whole change.
+
+## The schema travels too
+
+The package ships a **composed Prisma partial** and its migrations
+(`prisma/discounts.prisma`, `wiring.db`). A host syncs the partial into its
+schema folder and discovers the migration structurally:
+
+```bash
+pnpm --filter @12-apps/discounts prisma:sync         # copy the partial
+pnpm --filter @12-apps/discounts prisma:sync:check   # drift gate, for CI
+```
+
+Three tables — `discounts`, `discount_combo_slots`, `discount_targets` — and
+what makes them shippable at all is that **nothing in them names a host table**:
+
+| the origin had | the partial has | why |
+|---|---|---|
+| `client Client @relation(...)` | a scalar `client_id` | this package cannot know a host's tenant model's name |
+| `discount_categories` + `discount_items`, one FK each | one `discount_targets`, keyed `(target_type, target_id)` | a partial naming `product_categories` only compiles inside a host that has that table |
+| the scope's targets and a combo slot's, separately | one table, told apart by a nullable `slot_id` | they are the same fact; two tables need every reverse read, ownership check and cascade written twice |
+
+Which collections are discountable is answered at RUNTIME by a
+`DiscountableCollection` registration, not by the schema. That is the whole
+move, and it is `@12-apps/entity-lifecycle`'s, applied here.
+
+**The redemption snapshot stays with the host.** `order_discounts` is a child of
+the host's own order, with a cascade, and its purpose is to freeze what a buyer
+received on an order the host owns. Shipping the rule and leaving the receipt is
+the clean cut.
+
+**What the by-value target costs**, stated plainly: the schema no longer
+guarantees that deleting a category cannot leave a rule pointing at a ghost.
+Three things carry that instead — the evaluator already tolerates an unmatched
+target (it covers nothing), `DiscountableOps.ownsAll` refuses a foreign or
+missing id on every write, and a host that wants the constraint back may add it
+in its own migration.
+
+### The migration adopts an existing table
+
+Every statement is idempotent, because the first host to adopt this package
+already HAS a `discounts` table from its own, earlier migration — and a package
+migration sorts AFTER the host's by name, so a bare `CREATE TABLE` would fail
+`migrate deploy` on every database that already has one. A fresh host gets
+everything; an existing host gets only what it is missing (the three combo
+columns, the two new tables, and the widened `type`/`scope`/value CHECKs);
+replaying the whole folder is a no-op.
+
+It deliberately does NOT move a host's existing target rows into
+`discount_targets`. Only that host knows what its catalog tables are called, so
+backfilling and dropping the old join tables is one migration in the host,
+written once, sorting after this one.
+
+`src/prisma/__tests__/migration.test.ts` applies the SQL to real Postgres
+(PGlite) in all three situations — 17 cases, including the partial uniques, both
+cascades, and the CHECK widening a schema diff cannot see.
+
+## The admin screens travel too — `@12-apps/discounts/react`
+
+```ts
+// ONCE, at module scope. The members are component TYPES.
+export const discounts = createWebDiscounts({
+  apiBase: `/api/admin/${slug}`,
+  copy: PT_BR_DISCOUNTS_WEB_COPY,   // required, no defaults
+  locale: "pt-BR",
+  currency: "BRL",
+  currencyField: MyCurrencyField,   // currency entry is a host decision
+  onError: reportToSentry,          // required — see below
+  breadcrumb: [{ label: "Início", href: "/admin" }, { label: "Descontos" }],
+});
+
+// <discounts.Screen /> is the whole promotions admin.
+```
+
+What that one call replaces: a server-driven grid with eight columns, five
+filter pills and a CSV/JSON export; a create/edit form of fourteen inputs, four
+of which appear only when another says so; the target pickers; two card
+layouts; four confirmation popups; and every wire call between them.
+
+**Build it once, at module scope.** The members are component TYPES, so
+rebuilding per render gives React new types every time and remounts the whole
+tree below — a form then cannot be typed into, and nothing says why.
+`useWebDiscounts` is the memoised form for a genuinely dynamic mount path.
+
+### `onError` is required, and it is the browser twin of the server's logger
+
+These screens already tell the OPERATOR what went wrong. That is not the same as
+anybody knowing. A refused write, a catalog that would not load, a page read
+that failed — each reaches a person only if a host routes it somewhere, and a
+no-op default would make *nothing is broken* and *nothing is watching* look
+identical. `context` is a stable dotted token (`discounts.list`,
+`discounts.create`, `discounts.targets`) so a reporter can group on it.
+
+### One vocabulary, in English, on the wire
+
+`DISCOUNT_WINDOW_STATES` are `RUNNING` / `SCHEDULED` / `ENDED`, and the words on
+the pill come from the copy pack. They are read in three places that must agree
+— the filter pill, the query the backend receives, and the badge on a row — and
+the moment one of those is a word in a language, the set stops being a set. The
+origin filtered on `Vigente`, so its wire protocol *was* its language.
+
+`discountWindowState()` lives in the engine rather than in this surface for the
+same reason: the badge and the backend filter must answer "has it ended" the
+same way, and two implementations is how a grid shows a rule as running on a row
+the filter excludes.
+
+### What a host still supplies, and why each one
+
+| config | why it cannot be defaulted |
+|---|---|
+| `copy` | a default in one language reads as finished to the next host until a user sees it |
+| `locale` + `currency` | "12,5" is not a translation of "12.5" — it decides PARSING as much as rendering |
+| `currencyField` | masking, which side the symbol sits on, whether cents are typed — no neutral answer exists |
+| `onError` | above |
+| `breadcrumb` | the host owns its own information hierarchy |
+
+### Storybook
+
+`pnpm --filter @12-apps/discounts dev` (port 6009). Every ported component has
+stories, including the states nobody can produce on demand in a real
+environment: a refused write, a backend that will not answer, a catalog that
+failed while the grid loaded fine. The stories substitute a **transport**, not a
+stubbed client, so they exercise the real path building and envelope unwrapping
+and only the bytes are pretend.
+
 ## What the host still owns
 
-**The database.** A discount's rows relate to a host's own catalog and orders —
-targets point at its categories and items, redemptions at its orders and its
-buyers — so neither wiring `db` mode qualifies and the manifest declares none.
-The host owns the schema, the tenant scoping, the transactions and the
-uniqueness conflicts, and answers the `DiscountStore` port. What travels is the
-RULE, not the storage.
-
-Combos add three nullable columns to that table — `bundle_price_cents`,
-`free_units`, `max_combo_applications` — and one child table for the slots, each
-row carrying a quantity plus its own product and category id lists. `DiscountWrite`
-hands a store exactly that: the columns on `scalars`, the slots on
-`targets.comboRequirements`, already validated and narrowed to the scope. A host
-that does not sell combos adds nothing: the fields are optional on everything
-this package asks a host to BUILD (`DiscountRule`, `DiscountRecord`) and
-complete on everything it PRODUCES, so adopting the version that introduced them
-is a no-op until a `COMBO`-scoped row exists.
+**Persistence itself.** The package owns the schema; the host owns the client,
+the tenant scoping, the transactions and the uniqueness conflicts, and answers
+the `DiscountStore` port. `toTargetRows` / `fromTargetRows` do the fold between
+the id arrays this package speaks and the by-value rows the schema stores, so a
+store stays persistence and nothing else — that mapping is exactly where a
+dropped `slotId` produces a combo whose slots have silently merged.
 
 **Every sentence a human reads.** `DiscountRejectionCopy` (buyer-facing) and
 `DiscountsServerCopy` (operator-facing) are required config with **no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "The discount/promotion domain: a host-agnostic evaluator (percentage or fixed amount, order/category/item scope, automatic or coupon-triggered, stacking and exclusivity, integer-cent allocation) plus the admin CRUD surface as wiring-contract route descriptors over a store port. No database, no framework, no baked user copy.",
   "exports": {
@@ -8,38 +8,78 @@
     "./pt-BR": "./src/engine/pt-BR.ts",
     "./server": "./src/server/index.ts",
     "./server/pt-BR": "./src/server/pt-BR.ts",
+    "./react": "./src/react/index.ts",
+    "./react/pt-BR": "./src/react/pt-BR.ts",
     "./manifest": "./src/manifest/index.ts",
     "./manifest/server": "./src/manifest/server.ts",
+    "./manifest/web": "./src/manifest/web.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
+    "check-types": "tsc --noEmit",
     "clean": "rm -rf node_modules coverage dist",
+    "dev": "storybook dev -p 6009",
+    "lint": "eslint src --max-warnings 0",
+    "prisma:sync": "node scripts/sync-discounts-schema.mjs",
+    "prisma:sync:check": "node scripts/sync-discounts-schema.mjs --check",
+    "storybook:build": "storybook build",
     "test": "node ../../scripts/vitest-with-teardown.mjs run",
     "test:watch": "vitest watch",
-    "lint": "eslint src --max-warnings 0",
-    "check-types": "tsc --noEmit",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@12-apps/app-shell": "^5.1.0",
+    "@12-apps/forms-core": "^1.20.0",
     "@12-apps/shared-helpers": "^2.0.2",
+    "@12-apps/ui": "^6.2.0",
+    "@mui/icons-material": "^6.5.0",
     "zod": "^4.3.5"
   },
   "peerDependencies": {
-    "@12-apps/wiring": ">=1.3.0"
+    "@12-apps/wiring": ">=1.3.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "react-router-dom": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "@12-apps/wiring": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
     "@12-apps/typescript-config": "^1.20.1",
-    "@12-apps/wiring": "^1.7.0",
+    "@12-apps/wiring": "^1.10.0",
+    "@electric-sql/pglite": "^0.2.17",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.0",
+    "@mui/material": "^6.5.0",
+    "@storybook/addon-docs": "^9.1.10",
+    "@storybook/addon-links": "^9.1.10",
+    "@storybook/react-vite": "^9.1.10",
+    "@testing-library/react": "^16.1.0",
     "@types/node": "^22.10.6",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
     "eslint": "^9.39.1",
+    "eslint-plugin-storybook": "9.1.10",
     "eslint-plugin-test-flakiness": "^1.4.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.0.0",
+    "storybook": "^9.1.10",
     "typescript": "^5.9.2",
+    "vite": "^6.4.1",
     "vitest": "^3.2.4"
   },
   "engines": {
@@ -58,6 +98,8 @@
   "files": [
     "src",
     "dist",
+    "scripts",
+    "prisma",
     "*.js",
     "*.mjs",
     "*.md",
@@ -68,6 +110,13 @@
     "!**/*.spec.*",
     "!**/*.stories.*",
     "!**/*.test-story.*",
-    "!**/test-helpers.*"
-  ]
+    "!**/test-helpers.*",
+    "!**/__stories__/**"
+  ],
+  "wiring": {
+    "db": {
+      "partial": "prisma/discounts.prisma",
+      "migrations": "prisma/migrations"
+    }
+  }
 }

package/prisma/discounts.prisma

@@ -0,0 +1,181 @@
+// ---------------------------------------------------------------------------
+// @12-apps/discounts — CANONICAL Prisma model partial (plug-and-play).
+//
+// The single source of truth for the three tables a promotions surface owns. A
+// host does NOT copy these models into its schema by hand: it uses Prisma's
+// multi-file schema folder and SYNCS this file into it
+// (`scripts/sync-discounts-schema.mjs`), then discovers the migrations beside
+// it structurally.
+//
+// Host-agnostic by design, and this is the whole reason the shape differs from
+// the origin's:
+//
+//   - The TENANT is a by-value `client_id` scalar — no relation to the host's
+//     tenant model, whose name this package cannot know.
+//   - A TARGET is named BY VALUE via (target_type, target_id) — no FK into the
+//     host's catalog tables, so any collection plugs in with zero schema change
+//     here. That replaces one join table per dimension, which is what made the
+//     old shape unshippable: a partial literally naming `product_categories`
+//     and `menu_items` only compiles inside a host that has tables under those
+//     names. Which collections are discountable is answered at RUNTIME by a
+//     `DiscountableCollection` registration (`src/server/collections.ts`), not
+//     by the schema.
+//   - `type` / `scope` / `trigger` / `target_type` are Strings; the migration
+//     adds the CHECK constraints for the closed sets `src/engine/kinds.ts`
+//     declares. Those arrays and these CHECKs are two halves of ONE set.
+//
+// WHAT THE HOST STILL OWNS: the REDEMPTION snapshot (`order_discounts`). It is
+// a child of the host's own order with a cascade, and its whole purpose is to
+// freeze what a buyer received on an order the host owns. Shipping the rule and
+// leaving the receipt behind is the clean cut.
+//
+// WHAT THE BY-VALUE TARGET COSTS, stated plainly: this schema no longer
+// guarantees that deleting a category cannot leave a discount pointing at a
+// ghost. Three things carry that instead — the evaluator already tolerates an
+// unmatched target (it simply covers nothing), `DiscountableOps.ownsAll`
+// refuses a foreign or missing id on every write, and a host that wants the
+// constraint back may add it in its own migration.
+// ---------------------------------------------------------------------------
+
+// The rule itself: what it takes off, from what, when, and how often.
+//
+// `usage_count` is the live redemption counter, incremented inside the host's
+// PAID confirmation transaction by a predicated UPDATE. That predicate is what
+// makes `usage_count <= usage_limit` an invariant the CHECK can assert; a plain
+// read-then-write under READ COMMITTED would lose increments and break it.
+model Discount {
+  id                   String    @id @default(uuid())
+  // BY VALUE — no relation to the host's tenant model. Every read and every
+  // write carries it: a discount is a direct lever on what a buyer is charged,
+  // so a query that forgot its tenant would let one store reprice another's.
+  clientId             String    @map("client_id")
+  name                 String
+  // PERCENTAGE | FIXED_AMOUNT | BUNDLE_PRICE | FREE_UNITS (CHECK in migration).
+  type                 String
+  // Basis points off, 1..10000. Set iff type = PERCENTAGE.
+  percentOffBp         Int?      @map("percent_off_bp")
+  // Cents off. Set iff type = FIXED_AMOUNT. Clamped at application time to what
+  // is left, so it can never credit the buyer.
+  amountOffCents       Int?      @map("amount_off_cents")
+  // The matched combo group costs exactly this. Set iff type = BUNDLE_PRICE.
+  bundlePriceCents     Int?      @map("bundle_price_cents")
+  // The cheapest N units of the matched group are free. Set iff type =
+  // FREE_UNITS, and always fewer than the units one application requires — a
+  // combo that gives away everything it asks for sells nothing.
+  freeUnits            Int?      @map("free_units")
+  // How many times one cart may claim this combo. NULL = as often as it matches.
+  maxComboApplications Int?      @map("max_combo_applications")
+  // ORDER | CATEGORY | ITEM | COMBO (CHECK in migration). ORDER carries no
+  // targets; CATEGORY/ITEM resolve through `discount_targets`; COMBO resolves by
+  // MATCHING the cart against its quantified slots.
+  scope                String
+  // AUTOMATIC | CODE (CHECK in migration).
+  trigger              String
+  // The coupon the buyer types, upper-cased and unmasked. Non-null iff
+  // trigger = CODE. Unique per tenant among LIVE rows only — see the note below.
+  code                 String?
+  // Active window, half-open [starts_at, ends_at): `ends_at` is EXCLUSIVE, so
+  // an operator setting midnight of the next day means exactly that. Null on
+  // either side = open-ended.
+  startsAt             DateTime? @map("starts_at")
+  endsAt               DateTime? @map("ends_at")
+  // Minimum PRE-DISCOUNT cart subtotal, in cents. Always compared against the
+  // untouched subtotal, never a running total — which is what makes the result
+  // independent of the order the discounts are applied in.
+  minSubtotalCents     Int?      @map("min_subtotal_cents")
+  // Redemptions allowed across every buyer, and per buyer. Null = no cap.
+  usageLimit           Int?      @map("usage_limit")
+  perBuyerLimit        Int?      @map("per_buyer_limit")
+  usageCount           Int       @default(0) @map("usage_count")
+  // When false this rule stacks with nothing: if it wins it is the only one
+  // applied to the order ("best single discount wins").
+  stackable            Boolean   @default(true)
+  // The operator's on/off switch, ORTHOGONAL to `archived_at` (deleted) and to
+  // the window (scheduled).
+  active               Boolean   @default(true)
+  createdAt            DateTime  @default(now()) @map("created_at")
+  updatedAt            DateTime  @updatedAt @map("updated_at")
+  // Change attribution: the host's user id, by value, nullable for system rows.
+  createdBy            String?   @map("created_by")
+  updatedBy            String?   @map("updated_by")
+  // Accent/case-insensitive search key over `name`, written by the host.
+  searchName           String?   @map("search_name")
+  // Soft delete. A non-null timestamp hides the rule from every live read while
+  // its redemption history and its counter survive. Null = live.
+  archivedAt           DateTime? @map("archived_at")
+
+  targets   DiscountTarget[]
+  comboSlots DiscountComboSlot[]
+
+  // NO @@unique here, and that is an honest declaration rather than an
+  // omission. The tenant uniques on (client_id, name) and (client_id, code)
+  // exist in the database as PARTIAL indexes, both `WHERE archived_at IS NULL`.
+  // Prisma cannot express a filtered unique, and declaring an unconditional one
+  // here would be a lie the generated client acts on: it would expose a
+  // `clientId_code` findUnique the index cannot serve.
+  //
+  // Partial because deleting is a SOFT archive: an unconditional unique lets a
+  // soft-deleted coupon squat its code forever, so an operator could never
+  // recreate a code they had deleted. Live rows still own one name and one code
+  // per tenant; archived rows leave the index.
+  @@index([clientId, active, archivedAt])
+  @@map("discounts")
+}
+
+// One quantified slot of a combo: "2 units of anything in Drinks".
+//
+// A child table rather than a JSON column, for the reason the target rows are
+// rows: the slot's own targets need the same by-value shape and the same
+// reverse read, and a JSON blob would put half the combo behind a scan.
+//
+// `position` is the operator's order, which is also the order a card describes
+// the combo in — a stable order matters because two slots of the same size are
+// otherwise indistinguishable in a UI that lists them.
+model DiscountComboSlot {
+  id         String @id @default(uuid())
+  discountId String @map("discount_id")
+  position   Int
+  // Units of this slot ONE application consumes. Bounded by
+  // MAX_COMBO_SLOT_QUANTITY (CHECK in migration).
+  quantity   Int
+
+  discount Discount         @relation(fields: [discountId], references: [id], onDelete: Cascade)
+  targets  DiscountTarget[]
+
+  @@unique([discountId, position])
+  @@map("discount_combo_slots")
+}
+
+// What a discount points at, BY VALUE.
+//
+// One table for both jobs, told apart by `slot_id`: NULL means a SCOPE target
+// (what a CATEGORY- or ITEM-scoped rule covers), non-null means the target of
+// one combo slot. One table because they are the same fact — "this rule cares
+// about this row of this collection" — and two would need every reverse read,
+// every ownership check and every cascade written twice.
+//
+// The uniques are PARTIAL (`WHERE slot_id IS NULL` / `IS NOT NULL`) and
+// therefore live only in the migration, for the same reason the tenant uniques
+// on `Discount` do: NULLs are distinct in Postgres, so one unconditional unique
+// over a nullable column would not constrain the scope rows at all.
+model DiscountTarget {
+  id         String  @id @default(uuid())
+  discountId String  @map("discount_id")
+  // NULL = a scope target. Non-null = a target of that combo slot.
+  slotId     String? @map("slot_id")
+  // CATEGORY | ITEM (CHECK in migration) — which host collection `targetId`
+  // names. Widening this set is a host registering one more
+  // `DiscountableCollection`, plus this CHECK.
+  targetType String  @map("target_type")
+  // The host row's id. No FK: see the partial's header.
+  targetId   String  @map("target_id")
+
+  discount Discount           @relation(fields: [discountId], references: [id], onDelete: Cascade)
+  slot     DiscountComboSlot? @relation(fields: [slotId], references: [id], onDelete: Cascade)
+
+  // The reverse read a menu badge does: "which rules touch this row".
+  @@index([targetType, targetId])
+  @@index([discountId])
+  @@index([slotId])
+  @@map("discount_targets")
+}