@12-apps/discounts 1.0.0 → 1.2.0

package/README.md

@@ -11,7 +11,7 @@ No database, no framework, no clock, and **no baked user copy**.
 
 | entry | what it is |
 |---|---|
-| `@12-apps/discounts` | the engine: `evaluateDiscounts`, `previewItemDiscount`, the vocabulary, the rejection copy port |
+| `@12-apps/discounts` | the engine: `evaluateDiscounts`, `previewItemDiscount`, `comboOffersForItem`, `matchCombo`, the vocabulary, the rejection copy port |
 | `@12-apps/discounts/pt-BR` | the pt-BR rejection pack, imported by hand |
 | `@12-apps/discounts/server` | `createApiDiscounts`, the `DiscountStore` port, the permission contribution, the MCP tools |
 | `@12-apps/discounts/server/pt-BR` | the pt-BR pack for the admin surface's sentences |
@@ -21,10 +21,11 @@ No database, no framework, no clock, and **no baked user copy**.
 ## The model
 
 A discount is a **percentage** (basis points, 1..10000) or a **fixed amount**
-(integer cents), scoped to the whole **order**, to **categories**, or to
-specific **items**, fired either **automatically** when its conditions hold or
-by the buyer typing a **coupon code**. Money is integer cents throughout; a
-percentage is basis points, so "12,5%" needs no decimal column anywhere.
+(integer cents), scoped to the whole **order**, to **categories**, to specific
+**items**, or to a **combo**, fired either **automatically** when its conditions
+hold or by the buyer typing a **coupon code**. Money is integer cents
+throughout; a percentage is basis points, so "12,5%" needs no decimal column
+anywhere.
 
 The evaluator is a pure function of `{ lines, rules, couponCode, now }`:
 
@@ -53,9 +54,84 @@ Three properties it holds to the cent, and the suite pins each:
 strike through *before* there is a cart — from the same rules, so a card and a
 cart cannot quote different numbers.
 
+## Combos
+
+A **combo** is a discount scoped to a group the merchant defines: a list of
+**slots**, each naming products and/or categories and how many units it needs.
+The evaluator matches those slots against the cart's **units**, repeatedly, and
+prices each match.
+
+```ts
+// "1 pipoca grande + 2 refrigerantes por R$ 25,00"
+{
+  scope: "COMBO",
+  type: "BUNDLE_PRICE",
+  bundlePriceCents: 2_500,
+  comboRequirements: [
+    { menuItemIds: ["popcorn-lg"], categoryIds: [], quantity: 1 },
+    { menuItemIds: [], categoryIds: ["drinks"], quantity: 2 },
+  ],
+}
+
+// "3 hambúrgueres pelo preço de 2" — one slot of three, the cheapest one free
+{
+  scope: "COMBO",
+  type: "FREE_UNITS",
+  freeUnits: 1,
+  comboRequirements: [{ menuItemIds: ["burger"], categoryIds: [], quantity: 3 }],
+}
+```
+
+Four rewards, and the type picks which column is read:
+
+| type | column | the group's discount |
+|---|---|---|
+| `BUNDLE_PRICE` | `bundlePriceCents` | its value above the bundle price |
+| `FREE_UNITS` | `freeUnits` | its N cheapest units |
+| `PERCENTAGE` | `percentOffBp` | that rate off it |
+| `FIXED_AMOUNT` | `amountOffCents` | that many cents off it |
+
+The last two are the ordinary columns, doing the ordinary thing against a group
+instead of against a line. The first two only mean something against a matched
+group, so they are legal at `COMBO` scope and nowhere else — the write path
+refuses the combination and a host's CHECK constraint should too.
+
+Every reward is **per application**. A cart of seven burgers takes "3 for the
+price of 2" twice and pays full price for the seventh; `maxComboApplications`
+caps that when a merchant wants it capped.
+
+Four decisions worth knowing before you wire it up:
+
+- **Combos run first.** The pass order is `COMBO → ITEM → CATEGORY → ORDER`.
+- **What a combo consumed is opaque to `ITEM` and `CATEGORY`.** A combo price is
+  a number the merchant set deliberately; a component-targeted promotion
+  stacking on top of it is a double discount. So a line of five burgers with
+  three inside a combo offers exactly two burgers, at full price, to an
+  item-level promotion. **`ORDER` is not blocked** and applies to the combo
+  price, because an order-wide promise is about the basket, not the components.
+- **One pool.** Every combo draws from the same units, so two combos can never
+  both be paid for the same burger. The richer one claims them first.
+- **A combo is not badged.** Its price does not exist until the other components
+  are in the cart, so `previewItemDiscount` skips it. `comboOffersForItem` is
+  what a card can honestly show instead — that the item takes part in a combo,
+  as a label rather than a price.
+
+A combo the cart cannot assemble is rejected `COMBO_NOT_MATCHED`, which is the
+one rejection reason this package refuses to coarsen: a buyer one soda short
+can finish the combo, and telling them so is the difference between a dead end
+and a sale.
+
+### What a combo is NOT, here
+
+It is a **pricing rule**, not a catalog entity. There is no `Combo` product with
+its own menu card, its own single cart line and its own order snapshot — that is
+a host table with foreign keys into the host's own catalog, which is exactly why
+this package declares no `db` capability. What travels is the rule; the sellable
+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.
@@ -64,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:
@@ -76,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 } },
+  },
 });
 ```
 
@@ -84,6 +166,41 @@ 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.
+
 ## What the host still owns
 
 **The database.** A discount's rows relate to a host's own catalog and orders —
@@ -93,6 +210,16 @@ 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.
+
 **Every sentence a human reads.** `DiscountRejectionCopy` (buyer-facing) and
 `DiscountsServerCopy` (operator-facing) are required config with **no
 defaults** — `createApiDiscounts` throws at construction naming every missing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.0.0",
+  "version": "1.2.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": {
@@ -21,7 +21,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@12-apps/shared-helpers": "^2.0.1",
+    "@12-apps/shared-helpers": "^2.0.2",
     "zod": "^4.3.5"
   },
   "peerDependencies": {
@@ -33,9 +33,9 @@
     }
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.21.0",
-    "@12-apps/typescript-config": "^1.20.0",
-    "@12-apps/wiring": "^1.5.0",
+    "@12-apps/eslint-config": "^1.21.1",
+    "@12-apps/typescript-config": "^1.20.1",
+    "@12-apps/wiring": "^1.10.0",
     "@types/node": "^22.10.6",
     "eslint": "^9.39.1",
     "eslint-plugin-test-flakiness": "^1.4.0",

package/src/engine/allocate.ts

@@ -22,14 +22,29 @@ import type { DiscountRule } from "./types";
  * drifting negative. `FIXED_AMOUNT` is clamped to the base, so "R$ 20 off" on a
  * base of R$ 12 removes R$ 12 and never issues a credit. A result of 0 means
  * the discount must NOT be applied — an `R$ 0,00` line is not a promotion.
+ *
+ * The two COMBO reward types return 0 here, and that is deliberate rather than
+ * a gap: `BUNDLE_PRICE` and `FREE_UNITS` are not functions of a base at all.
+ * One needs to know which UNITS the combo matched (the cheapest of them are the
+ * free ones) and the other needs to know how many TIMES it matched, and a
+ * single `baseCents` has thrown both facts away. `applicationReward` in
+ * `./combo-match.ts` is where they are computed, per application, and it calls
+ * back into this function for the two types that ARE a function of a base.
+ *
+ * Returning 0 rather than throwing keeps the failure the safe one: a combo
+ * reward that somehow reached this path removes nothing, which the evaluator
+ * reports as `ZERO_VALUE`, instead of a wrong number reaching a charge.
  */
 export function rawAmountCents(rule: DiscountRule, baseCents: number): number {
   if (baseCents <= 0) return 0;
-  const raw =
-    rule.type === "PERCENTAGE"
-      ? Math.floor((baseCents * (rule.percentOffBp ?? 0)) / MAX_PERCENT_OFF_BP)
-      : (rule.amountOffCents ?? 0);
-  return Math.max(0, Math.min(raw, baseCents));
+  if (rule.type === "PERCENTAGE") {
+    const raw = Math.floor((baseCents * (rule.percentOffBp ?? 0)) / MAX_PERCENT_OFF_BP);
+    return Math.max(0, Math.min(raw, baseCents));
+  }
+  if (rule.type === "FIXED_AMOUNT") {
+    return Math.max(0, Math.min(rule.amountOffCents ?? 0, baseCents));
+  }
+  return 0;
 }
 
 /**

package/src/engine/combo-match.ts

@@ -0,0 +1,370 @@
+import { rawAmountCents } from "./allocate";
+import type { ComboRequirement, DiscountCartLine, DiscountRule } from "./types";
+
+/**
+ * COMBO matching (FUT-268): which UNITS of a cart satisfy a combo's slots, how
+ * many times, and how many cents that is worth.
+ *
+ * This is the one part of the engine that counts UNITS rather than lines. A
+ * discount scoped to an item takes a percentage off a whole line and never
+ * needs to know it holds five burgers; a combo does — "3 for the price of 2"
+ * on a line of five applies once and leaves two burgers at full price, and the
+ * cents that fall out of that are not a function of the line's total.
+ *
+ * Pure, like the rest of the engine: no database, no clock, no I/O. The same
+ * pool and the same rule always produce the same match, down to WHICH units
+ * were taken, because every ordering below has an explicit final tie-break.
+ *
+ * ## The matching rule, stated once
+ *
+ * One APPLICATION fills every slot. A slot is filled from the units its
+ * targets accept, MOST EXPENSIVE FIRST, and slots are filled MOST CONSTRAINED
+ * FIRST. The combo then applies again against whatever units are left, until a
+ * slot can no longer be filled or `maxComboApplications` is reached.
+ *
+ * Most-expensive-first is the buyer-favourable reading and it is the same
+ * instinct as R6's biggest-first ordering. On a `FREE_UNITS` combo it makes the
+ * free unit the dearest one the deal can reach; on a `BUNDLE_PRICE` combo the
+ * buyer pays the bundle price either way, so pulling the expensive units INTO
+ * the bundle leaves the cheap ones outside it at full price, which is again the
+ * cheaper cart.
+ *
+ * Most-constrained-first is a HEURISTIC, and the honest name for what it is: a
+ * greedy assignment, not a maximum bipartite matching. It is exact whenever the
+ * slots are disjoint — which every combo a merchant can describe in a sentence
+ * is — and it repairs the one overlap that occurs in practice, a specific item
+ * slot next to a broad category slot that also accepts it ("1 large popcorn + 2
+ * sodas", where the popcorn is itself filed under a targeted category). Filling
+ * the narrow slot first stops the broad one from eating its only candidate. A
+ * deliberately pathological spec — three slots overlapping three ways — can
+ * still leave an application unmatched that a full matching would have found.
+ *
+ * That residue is bounded and it is bounded in the safe direction: the cost is
+ * a combo firing fewer times than it could, never a wrong price, because
+ * whatever the assignment picks is a real set of units the buyer really has.
+ * The admin surface does NOT detect overlap — it caps the slot COUNT
+ * (`MAX_COMBO_SLOTS`), which is a limit on how pathological a spec can get and
+ * not a check that one is not. Trading an exact matching for that was
+ * deliberate: the exact algorithm is a maximum bipartite matching re-run per
+ * application, on a hot path a whole menu page walks, to buy correctness only
+ * on specs no merchant writes.
+ */
+
+/**
+ * The units a combo may still consume, plus the lines they belong to.
+ *
+ * It is a POOL rather than a plain line list because combos share it: two
+ * combos that both want the same burgers must not both be paid for them, so
+ * the combo pass builds one pool, and each match deducts what it took. See
+ * `runPass` in `./evaluate-passes.ts`.
+ */
+export interface ComboPool {
+  /** lineId -> units still available. */
+  readonly unitsByLine: ReadonlyMap<string, number>;
+  /** Every line of the cart by id — the matcher needs prices and targeting. */
+  readonly linesById: ReadonlyMap<string, DiscountCartLine>;
+}
+
+/** What one combo took from the cart, and what it is worth. */
+export interface ComboMatch {
+  /** How many times the slots were filled. Always >= 1 on a real match. */
+  applications: number;
+  /** lineId -> units consumed across every application. */
+  consumedUnitsByLine: ReadonlyMap<string, number>;
+  /** lineId -> GROSS cents of those units. This is the allocation base. */
+  consumedCentsByLine: ReadonlyMap<string, number>;
+  /** Gross value of the whole matched group: the sum of the map above. */
+  groupCents: number;
+  /**
+   * Cents this combo removes, summed over its applications and before the
+   * cart-level clamps (R4's remainders and R9's payable floor) are applied.
+   */
+  rewardCents: number;
+}
+
+/** lineId -> a count of units. */
+type UnitTally = Map<string, number>;
+
+/** One slot with its target lists turned into sets, prepared once per match. */
+interface PreparedSlot {
+  quantity: number;
+  menuItemIds: ReadonlySet<string>;
+  categoryIds: ReadonlySet<string>;
+}
+
+/** One candidate line for a slot, carried with the facts the sort needs. */
+interface SlotCandidate {
+  lineId: string;
+  units: number;
+  line: DiscountCartLine;
+}
+
+/** A pristine pool: every line's full quantity available. */
+export function freshComboPool(lines: readonly DiscountCartLine[]): ComboPool {
+  return {
+    unitsByLine: new Map(lines.map((line) => [line.lineId, Math.max(0, line.quantity)])),
+    linesById: new Map(lines.map((line) => [line.lineId, line])),
+  };
+}
+
+function prepareSlots(requirements: readonly ComboRequirement[]): PreparedSlot[] {
+  return requirements.map((requirement) => ({
+    quantity: Math.trunc(requirement.quantity),
+    menuItemIds: new Set(requirement.menuItemIds),
+    categoryIds: new Set(requirement.categoryIds),
+  }));
+}
+
+/**
+ * Whether one slot accepts one line: its BASE item, its chosen VARIATION, or
+ * any category on its path. Exactly the reach `coveredLineIds` gives an
+ * `ITEM`- or `CATEGORY`-scoped discount, so a merchant does not have to learn
+ * a second targeting model for combos.
+ */
+function slotAccepts(slot: PreparedSlot, line: DiscountCartLine): boolean {
+  if (slot.menuItemIds.has(line.menuItemId)) return true;
+  if (line.variationMenuItemId !== null && slot.menuItemIds.has(line.variationMenuItemId)) {
+    return true;
+  }
+  return line.categoryPath.some((categoryId) => slot.categoryIds.has(categoryId));
+}
+
+/** Every available unit a slot accepts, dearest first, then by line id. */
+function candidatesFor(
+  slot: PreparedSlot,
+  available: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+): SlotCandidate[] {
+  return [...available.entries()]
+    .map(([lineId, units]) => ({ lineId, units, line: linesById.get(lineId) }))
+    .filter(
+      (entry): entry is SlotCandidate =>
+        entry.units > 0 && entry.line !== undefined && slotAccepts(slot, entry.line),
+    )
+    .sort((a, b) => {
+      const byPrice = b.line.unitPriceCents - a.line.unitPriceCents;
+      if (byPrice !== 0) return byPrice;
+      return a.lineId < b.lineId ? -1 : 1;
+    });
+}
+
+/** Take one slot's units, dearest first. Null when the cart is short. */
+function takeSlot(
+  slot: PreparedSlot,
+  available: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+): UnitTally | null {
+  const taken: UnitTally = new Map();
+  let needed = slot.quantity;
+  for (const candidate of candidatesFor(slot, available, linesById)) {
+    if (needed <= 0) break;
+    const take = Math.min(needed, candidate.units);
+    taken.set(candidate.lineId, take);
+    needed -= take;
+  }
+  return needed > 0 ? null : taken;
+}
+
+/** How many units are available to a slot right now — the constraint metric. */
+function supplyFor(
+  slot: PreparedSlot,
+  available: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+): number {
+  return candidatesFor(slot, available, linesById).reduce(
+    (total, candidate) => total + candidate.units,
+    0,
+  );
+}
+
+/** Most constrained first, ties broken by the merchant's declaration order. */
+function orderSlots(
+  slots: readonly PreparedSlot[],
+  available: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+): PreparedSlot[] {
+  return slots
+    .map((slot, index) => ({ slot, index, supply: supplyFor(slot, available, linesById) }))
+    .sort((a, b) => a.supply - b.supply || a.index - b.index)
+    .map((entry) => entry.slot);
+}
+
+function addUnits(target: UnitTally, source: ReadonlyMap<string, number>): void {
+  for (const [lineId, units] of source) {
+    target.set(lineId, (target.get(lineId) ?? 0) + units);
+  }
+}
+
+function subtractUnits(target: UnitTally, source: ReadonlyMap<string, number>): void {
+  for (const [lineId, units] of source) {
+    target.set(lineId, Math.max(0, (target.get(lineId) ?? 0) - units));
+  }
+}
+
+/**
+ * Fill every slot once, against a private copy of what is available.
+ *
+ * The copy is what makes an application ALL-OR-NOTHING: a combo that fills two
+ * of its three slots and then runs short must consume nothing at all, or the
+ * buyer would be charged for a bundle they were never given.
+ */
+function fillOneApplication(
+  slots: readonly PreparedSlot[],
+  available: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+): UnitTally | null {
+  const left: UnitTally = new Map(available);
+  const taken: UnitTally = new Map();
+  for (const slot of orderSlots(slots, left, linesById)) {
+    const slotTake = takeSlot(slot, left, linesById);
+    if (slotTake === null) return null;
+    addUnits(taken, slotTake);
+    subtractUnits(left, slotTake);
+  }
+  return taken;
+}
+
+function tallyCents(
+  units: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+): Map<string, number> {
+  const cents = new Map<string, number>();
+  for (const [lineId, count] of units) {
+    const line = linesById.get(lineId);
+    if (line !== undefined) cents.set(lineId, count * Math.max(0, line.unitPriceCents));
+  }
+  return cents;
+}
+
+function sumValues(values: ReadonlyMap<string, number>): number {
+  let total = 0;
+  for (const cents of values.values()) total += cents;
+  return total;
+}
+
+/** The unit prices of one application, one entry per unit. */
+function unitPricesOf(
+  units: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+): number[] {
+  return [...units.entries()].flatMap(([lineId, count]) => {
+    const line = linesById.get(lineId);
+    if (line === undefined) return [];
+    return Array.from({ length: count }, () => Math.max(0, line.unitPriceCents));
+  });
+}
+
+/** The `FREE_UNITS` reward: the N CHEAPEST units of one application. */
+function cheapestUnitsCents(
+  units: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+  freeUnits: number,
+): number {
+  if (freeUnits <= 0) return 0;
+  return unitPricesOf(units, linesById)
+    .sort((a, b) => a - b)
+    .slice(0, freeUnits)
+    .reduce((total, cents) => total + cents, 0);
+}
+
+/**
+ * What ONE application removes.
+ *
+ * Per application rather than per match, because that is what each reward
+ * means: "R$ 5 off the combo" twice is R$ 10, and "one free" twice is two free
+ * units, one from each group. Only `PERCENTAGE` would read the same either
+ * way, and it goes through the same path so there is one rule to read.
+ */
+function applicationReward(
+  rule: DiscountRule,
+  units: ReadonlyMap<string, number>,
+  linesById: ReadonlyMap<string, DiscountCartLine>,
+): number {
+  const groupCents = sumValues(tallyCents(units, linesById));
+  if (groupCents <= 0) return 0;
+  if (rule.type === "BUNDLE_PRICE") {
+    return Math.max(0, groupCents - Math.max(0, rule.bundlePriceCents ?? 0));
+  }
+  if (rule.type === "FREE_UNITS") {
+    return cheapestUnitsCents(units, linesById, rule.freeUnits ?? 0);
+  }
+  return rawAmountCents(rule, groupCents);
+}
+
+/**
+ * The application ceiling.
+ *
+ * Bounded by the pool's own size whatever the rule says, which is what makes
+ * the loop below provably terminate: every application consumes at least one
+ * unit (a zero-quantity slot is refused before we get here), so there can never
+ * be more applications than there are units in the cart.
+ *
+ * Only null/undefined mean UNCAPPED. A stored zero means "at most zero times",
+ * so the combo simply does not fire — the admin surface refuses that value, and
+ * a row that carries one anyway should cost the merchant a promotion nobody
+ * sees rather than an uncapped giveaway nobody authorised.
+ */
+function applicationCap(rule: DiscountRule, pool: ComboPool): number {
+  const totalUnits = sumValues(pool.unitsByLine);
+  const declared = rule.maxComboApplications;
+  if (declared === null || declared === undefined) return totalUnits;
+  return Math.min(Math.trunc(declared), totalUnits);
+}
+
+/**
+ * Match one combo rule against a pool. Null when the cart cannot fill its
+ * slots even once — which the screen reports as `COMBO_NOT_MATCHED`.
+ */
+export function matchCombo(rule: DiscountRule, pool: ComboPool): ComboMatch | null {
+  const slots = prepareSlots(rule.comboRequirements ?? []);
+  if (slots.length === 0 || slots.some((slot) => slot.quantity <= 0)) return null;
+
+  const left: UnitTally = new Map(pool.unitsByLine);
+  const consumedUnits: UnitTally = new Map();
+  const cap = applicationCap(rule, pool);
+  let rewardCents = 0;
+  let applications = 0;
+  while (applications < cap) {
+    const taken = fillOneApplication(slots, left, pool.linesById);
+    if (taken === null) break;
+    rewardCents += applicationReward(rule, taken, pool.linesById);
+    addUnits(consumedUnits, taken);
+    subtractUnits(left, taken);
+    applications += 1;
+  }
+  if (applications === 0) return null;
+
+  const consumedCentsByLine = tallyCents(consumedUnits, pool.linesById);
+  return {
+    applications,
+    consumedUnitsByLine: consumedUnits,
+    consumedCentsByLine,
+    groupCents: sumValues(consumedCentsByLine),
+    rewardCents,
+  };
+}
+
+/**
+ * R3 for a `COMBO`-scoped rule: the lines a pristine cart would let it touch.
+ *
+ * Answered by MATCHING rather than by intersecting target lists, because a
+ * combo's coverage is not "every line it names" — a cart holding the popcorn
+ * and no soda names one of the slots and covers nothing, and reporting it as
+ * covered would let it through the screen only to remove zero.
+ */
+export function comboCoveredLineIds(
+  rule: DiscountRule,
+  lines: readonly DiscountCartLine[],
+): ReadonlySet<string> {
+  const match = matchCombo(rule, freshComboPool(lines));
+  return match === null ? new Set<string>() : new Set(match.consumedUnitsByLine.keys());
+}
+
+/**
+ * Whether any of a combo's slots would accept this line — the question a menu
+ * card asks ("is this item part of a combo?"), which is strictly weaker than
+ * whether the combo MATCHES. Used by `./combo-offer.ts`.
+ */
+export function comboRuleAcceptsLine(rule: DiscountRule, line: DiscountCartLine): boolean {
+  return prepareSlots(rule.comboRequirements ?? []).some((slot) => slotAccepts(slot, line));
+}