@12-apps/discounts 1.0.0 → 1.1.0

package/src/engine/combo-offer.ts

@@ -0,0 +1,135 @@
+import { comboRuleAcceptsLine } from "./combo-match";
+import { compareRuleOrder } from "./evaluate-passes";
+import type { DiscountType } from "./kinds";
+import type { ComboRequirement, DiscountCartLine, DiscountRule } from "./types";
+
+/**
+ * "Which combos is this item part of?" — the menu-card question, answered from
+ * the same rules the cart is priced with.
+ *
+ * `previewItemDiscount` cannot answer it. A badge is a PRICE, and a combo has
+ * none until the other components are in the cart, so combos are excluded
+ * there. But a card that says nothing at all about a combo is how a merchant's
+ * best promotion goes unsold: the buyer has to already know the bundle exists
+ * to assemble it.
+ *
+ * So this returns a LABELLING fact, not a price: these are the live combos a
+ * slot of which this item can fill. A host renders "Leve 3, pague 2" or "Faz
+ * parte de um combo" from it, in its own words — the merchant's `name` is the
+ * only string here, and it is already their copy in their own language.
+ *
+ * Pure and copy-free, like the rest of the engine. Loaded once for a whole
+ * catalog request, never per product.
+ *
+ * ## What it deliberately does not do
+ *
+ * - **No cart.** It never says the combo would MATCH — that needs the other
+ *   components, and a card cannot see them. `comboRuleAcceptsLine` is the
+ *   weaker "a slot would accept this item", which is exactly what a card can
+ *   honestly claim.
+ * - **No coupon combos.** A `CODE`-triggered combo is not advertised, on the
+ *   same reasoning the badge uses: a price the buyer has not unlocked yet is
+ *   not this item's price, and a promotion nobody can reach from the card is
+ *   noise on it.
+ * - **No redemption caps.** `usageLimit` IS honoured (an exhausted combo is
+ *   over), but `perBuyerLimit` is not, for the reason `./preview.ts` sets out
+ *   at length: a catalog listing is anonymous, so the buyer's count is not
+ *   knowable here, and hiding a first-purchase promotion from first-time
+ *   buyers is the worse error.
+ */
+
+/**
+ * One combo an item takes part in, flattened to what a card needs.
+ *
+ * The reward is carried as the raw columns rather than as a rendered phrase
+ * because the phrase is a SENTENCE, and sentences are host config everywhere
+ * else in this package. A host reads `type` and the one column that goes with
+ * it, and writes its own line.
+ */
+export interface ComboOffer {
+  discountId: string;
+  /** The merchant's own name for the promotion — already their copy. */
+  name: string;
+  type: DiscountType;
+  /** Non-null iff `type === "BUNDLE_PRICE"`: what the group costs. */
+  bundlePriceCents: number | null;
+  /** Non-null iff `type === "FREE_UNITS"`: how many of the group are free. */
+  freeUnits: number | null;
+  /** Non-null iff `type === "PERCENTAGE"`: basis points off the group. */
+  percentOffBp: number | null;
+  /** Non-null iff `type === "FIXED_AMOUNT"`: cents off the group. */
+  amountOffCents: number | null;
+  /** The slots, so a card can say what else the buyer has to add. */
+  requirements: readonly ComboRequirement[];
+}
+
+export interface ComboOffersInput {
+  /** The BASE (grouping) menu-item id the card renders. */
+  menuItemId: string;
+  /** The variation whose price the card shows, when it shows one. */
+  variationMenuItemId?: string | null;
+  /** The item's own category id followed by its ancestors, nearest first. */
+  categoryPath: readonly string[];
+  /** The tenant's live discount rules, loaded once for the whole menu. */
+  rules: readonly DiscountRule[];
+  /** Evaluation instant. Injected — this module never calls `new Date()`. */
+  now: Date;
+}
+
+/** The synthetic one-unit line a slot is tested against. */
+const OFFER_LINE_ID = "offer";
+
+function toOfferLine(input: ComboOffersInput): DiscountCartLine {
+  return {
+    lineId: OFFER_LINE_ID,
+    menuItemId: input.menuItemId,
+    variationMenuItemId: input.variationMenuItemId ?? null,
+    categoryPath: input.categoryPath,
+    quantity: 1,
+    // A card asks whether a slot ACCEPTS this item, which no price enters into.
+    unitPriceCents: 0,
+  };
+}
+
+/**
+ * Live enough to advertise: switched on, inside its window, and not exhausted.
+ *
+ * Deliberately NOT `screenRule`: that function's remaining predicates are all
+ * cart facts (`minSubtotalCents` against a subtotal, `hasEligibleItems` against
+ * a covered set), and a card has no cart to answer them from. Feeding it
+ * zeroes would reject every combo carrying a minimum basket, which is precisely
+ * the sort a merchant advertises.
+ */
+function isAdvertisable(rule: DiscountRule, now: Date): boolean {
+  if (rule.scope !== "COMBO" || rule.trigger !== "AUTOMATIC" || !rule.active) return false;
+  if (rule.startsAt !== null && now.getTime() < rule.startsAt.getTime()) return false;
+  if (rule.endsAt !== null && now.getTime() >= rule.endsAt.getTime()) return false;
+  return rule.usageLimit === null || rule.usageCount < rule.usageLimit;
+}
+
+function toOffer(rule: DiscountRule): ComboOffer {
+  return {
+    discountId: rule.id,
+    name: rule.name,
+    type: rule.type,
+    bundlePriceCents: rule.bundlePriceCents ?? null,
+    freeUnits: rule.freeUnits ?? null,
+    percentOffBp: rule.percentOffBp,
+    amountOffCents: rule.amountOffCents,
+    requirements: rule.comboRequirements ?? [],
+  };
+}
+
+/**
+ * Every live combo one of whose slots this item can fill, in the evaluator's
+ * canonical rule order so a card and a cart never disagree about which combo
+ * comes first. Empty when the item is in none — the common case, and the one a
+ * caller should render as nothing at all.
+ */
+export function comboOffersForItem(input: ComboOffersInput): readonly ComboOffer[] {
+  const line = toOfferLine(input);
+  return input.rules
+    .filter((rule) => isAdvertisable(rule, input.now) && comboRuleAcceptsLine(rule, line))
+    .sort(compareRuleOrder)
+    .map(toOffer);
+}

package/src/engine/eligibility.ts

@@ -1,3 +1,4 @@
+import { comboCoveredLineIds } from "./combo-match";
 import type { DiscountRejectionReason } from "./kinds";
 import type { DiscountCartLine, DiscountRule } from "./types";
 
@@ -90,6 +91,15 @@ function addAll(target: Set<string>, lineIds: readonly string[] | undefined): vo
  * discount on a top-level category automatically reaches items filed under its
  * subcategories; `ITEM` covers every line whose base or variation menu item is
  * targeted.
+ *
+ * `COMBO` is the one scope the reverse index cannot answer, because its
+ * coverage is not a set intersection but a MATCH: whether the cart holds enough
+ * units to fill every slot at once. It is delegated to `./combo-match.ts`, and
+ * the answer here is deliberately the PRISTINE one — what the whole cart could
+ * fill — because this is the screen, and the screen's job is to tell a combo
+ * that can never fire ("no soda in the cart") from one that merely lost its
+ * units to a combo that ran first. The second is not a screen failure; it is a
+ * combo that removed nothing, and `./evaluate.ts` reports it as `ZERO_VALUE`.
  */
 export function coveredLineIds(
   rule: DiscountRule,
@@ -97,6 +107,7 @@ export function coveredLineIds(
   index: LineIndex,
 ): ReadonlySet<string> {
   if (rule.scope === "ORDER") return new Set(lines.map((line) => line.lineId));
+  if (rule.scope === "COMBO") return comboCoveredLineIds(rule, lines);
   const byCategory = rule.scope === "CATEGORY";
   const targets = byCategory ? rule.targetCategoryIds : rule.targetMenuItemIds;
   const bucket = byCategory ? index.byCategory : index.byMenuItem;
@@ -147,6 +158,11 @@ function screenLimits(rule: DiscountRule, ctx: ScreenContext): DiscountRejection
  * The coupon-match predicate is NOT here: a CODE-triggered rule the buyer did
  * not type is not a rejection, it is simply not a candidate, and the caller
  * drops it silently.
+ *
+ * The last predicate splits by scope for one reason only: a combo that could
+ * not be assembled is the one failure in this set the buyer can DO something
+ * about, so it earns its own sentence rather than the shared "not for the items
+ * in your cart". See `DISCOUNT_REJECTION_REASONS` in `./kinds.ts`.
  */
 export function screenRule(
   rule: DiscountRule,
@@ -156,5 +172,6 @@ export function screenRule(
   if (scheduling !== null) return scheduling;
   const limits = screenLimits(rule, ctx);
   if (limits !== null) return limits;
-  return ctx.hasEligibleItems ? null : "NO_ELIGIBLE_ITEMS";
+  if (ctx.hasEligibleItems) return null;
+  return rule.scope === "COMBO" ? "COMBO_NOT_MATCHED" : "NO_ELIGIBLE_ITEMS";
 }

package/src/engine/evaluate-passes.ts

@@ -1,10 +1,12 @@
 import { allocateByLargestRemainder, maxDiscountableCents, rawAmountCents } from "./allocate";
+import { freshComboPool, matchCombo, type ComboMatch } from "./combo-match";
 import type { AppliedDiscount, DiscountCartLine, DiscountRule } from "./types";
 
 /**
  * APPLICATION core of the discount evaluator (FUT-245): rules R4 (a discount's
- * base is what is still discountable), R6 (the three narrowest-first passes),
- * R9 (the payable floor, imposed here rather than on the finished total) and the
+ * base is what is still discountable), R6 (the four narrowest-first passes),
+ * R9 (the payable floor, imposed here rather than on the finished total), R10
+ * (combos: the shared unit pool and the opacity of what they consumed) and the
  * plumbing that turns one set of candidates into one complete
  * "what if we applied exactly these" {@link Outcome}, which R8 in `./evaluate.ts`
  * then compares against the alternatives.
@@ -13,10 +15,44 @@ import type { AppliedDiscount, DiscountCartLine, DiscountRule } from "./types";
  * reason `order-confirm-payment.ts` sits beside `order-confirm.ts`. Read it as
  * the middle of that file, not as a separate concept. Pure: no database, no
  * clock, no I/O.
+ *
+ * ─── R10, THE COMBO RULES, IN FULL ───
+ *
+ * A combo is the only candidate whose base is not "the lines it covers". It
+ * consumes UNITS, and two consequences follow that the other three scopes never
+ * raise:
+ *
+ * 1. **One pool, shared by every combo.** Two combos that both want the same
+ *    three burgers must not both be paid for them. The state therefore carries
+ *    a unit pool that each match DEDUCTS from, so the second combo sees only
+ *    what the first left. Without it a cart of three burgers could satisfy
+ *    "3 for the price of 2" and "buy 3 get a free soda" on the same three
+ *    units, and the merchant would pay for both.
+ *
+ * 2. **What a combo consumed is OPAQUE to `ITEM` and `CATEGORY`.** A combo
+ *    price is a number the merchant set deliberately for a specific group; a
+ *    component-targeted promotion stacking on top of it is the double discount
+ *    the epic exists to refuse. So the units inside a combo are locked at their
+ *    post-combo value and the two middle passes see only the units OUTSIDE it —
+ *    a line of five burgers with three in a combo offers exactly two burgers at
+ *    full price to an item-level promotion.
+ *
+ *    `ORDER` is deliberately NOT blocked, and applies to the combo PRICE: an
+ *    order-wide "10% off everything" is a statement about the basket, not about
+ *    the components, and a buyer who was promised it on the whole cart would be
+ *    right to be surprised by a combo silently opting out of it.
+ *
+ * The two together are what make R4's promise still true at the UNIT level:
+ * money already given away on a unit cannot be given away again.
  */
 
-/** R6's three passes, narrowest scope first. */
-const SCOPE_PASSES = ["ITEM", "CATEGORY", "ORDER"] as const;
+/**
+ * R6's four passes, narrowest scope first. `COMBO` leads because it is the
+ * narrowest thing a merchant can price — a named group of units — and because
+ * the opacity in R10 only means anything if the combo has already claimed its
+ * units by the time the item pass runs.
+ */
+const SCOPE_PASSES = ["COMBO", "ITEM", "CATEGORY", "ORDER"] as const;
 
 /** A rule that survived R2, carried together with its R3 covered set. */
 export interface Candidate {
@@ -32,6 +68,12 @@ export interface EvaluationState {
   subtotalCents: number;
   /** `Σ applied[].amountCents` so far, kept beside it so R9's headroom is O(1). */
   appliedTotalCents: number;
+  /** R10 — units no combo has claimed yet. Depleted as combos match. */
+  comboPool: Map<string, number>;
+  /** R10 — per line, the NET value sitting inside a combo. Opaque to ITEM/CATEGORY. */
+  comboLockedCents: Map<string, number>;
+  /** The cart by line id: the combo matcher needs unit prices and targeting. */
+  linesById: ReadonlyMap<string, DiscountCartLine>;
 }
 
 /** One complete run over a candidate set, ready to be compared with another. */
@@ -41,17 +83,31 @@ export interface Outcome {
   totalCents: number;
 }
 
+/** What one candidate would take, and from where, measured against the state. */
+interface ApplicationPlan {
+  /** lineId -> the cents this candidate may take from that line. */
+  base: Map<string, number>;
+  /** R5's raw value against that base, before R9's floor. */
+  rawCents: number;
+  /** The combo match behind the plan, or null for the other three scopes. */
+  match: ComboMatch | null;
+}
+
 /** R1 — a line's gross value, floored at zero for defensive inputs. */
 export function lineGrossCents(line: DiscountCartLine): number {
   return Math.max(0, line.unitPriceCents * line.quantity);
 }
 
 function freshState(lines: readonly DiscountCartLine[]): EvaluationState {
+  const pool = freshComboPool(lines);
   return {
     remaining: new Map(lines.map((line) => [line.lineId, lineGrossCents(line)])),
     applied: [],
     subtotalCents: lines.reduce((sum, line) => sum + lineGrossCents(line), 0),
     appliedTotalCents: 0,
+    comboPool: new Map(pool.unitsByLine),
+    comboLockedCents: new Map(),
+    linesById: pool.linesById,
   };
 }
 
@@ -63,29 +119,98 @@ export function compareRuleOrder(a: DiscountRule, b: DiscountRule): number {
   return a.id < b.id ? -1 : 1;
 }
 
-/** R4 — what is still discountable on each of a candidate's covered lines. */
-function remainingFor(state: EvaluationState, covered: ReadonlySet<string>): Map<string, number> {
-  const remaining = new Map<string, number>();
-  for (const lineId of covered) {
-    remaining.set(lineId, Math.max(0, state.remaining.get(lineId) ?? 0));
-  }
-  return remaining;
-}
-
 function sumValues(values: ReadonlyMap<string, number>): number {
   let total = 0;
   for (const cents of values.values()) total += cents;
   return total;
 }
 
+/**
+ * R4 + R10 — what is still discountable on each of a candidate's covered lines.
+ *
+ * `ITEM` and `CATEGORY` are additionally denied whatever a combo has locked, so
+ * they reach only the units the combo did not take. `ORDER` reads the plain
+ * remainder, which is the combo's net price plus everything else.
+ */
+function discountableFor(state: EvaluationState, candidate: Candidate): Map<string, number> {
+  const respectsCombos = candidate.rule.scope !== "ORDER";
+  const base = new Map<string, number>();
+  for (const lineId of candidate.covered) {
+    const remaining = Math.max(0, state.remaining.get(lineId) ?? 0);
+    const locked = respectsCombos ? (state.comboLockedCents.get(lineId) ?? 0) : 0;
+    base.set(lineId, Math.max(0, remaining - locked));
+  }
+  return base;
+}
+
+/**
+ * R10 — a combo's plan: match against what the pool still holds, then take the
+ * consumed units' GROSS value as the allocation base.
+ *
+ * The base is the consumed value rather than the whole line, because a combo
+ * that took three of a line's five burgers must charge its discount to those
+ * three. Allocating over the whole line would spread the money across units the
+ * combo never claimed, and the locked-value arithmetic in `lockComboValue`
+ * would then hold back the wrong number.
+ */
+function comboPlan(state: EvaluationState, rule: DiscountRule): ApplicationPlan {
+  const match = matchCombo(rule, {
+    unitsByLine: state.comboPool,
+    linesById: state.linesById,
+  });
+  if (match === null) return { base: new Map(), rawCents: 0, match: null };
+  const base = new Map<string, number>();
+  for (const [lineId, grossCents] of match.consumedCentsByLine) {
+    base.set(lineId, Math.min(grossCents, Math.max(0, state.remaining.get(lineId) ?? 0)));
+  }
+  return { base, rawCents: Math.min(match.rewardCents, sumValues(base)), match };
+}
+
+function planFor(state: EvaluationState, candidate: Candidate): ApplicationPlan {
+  if (candidate.rule.scope === "COMBO") return comboPlan(state, candidate.rule);
+  const base = discountableFor(state, candidate);
+  return { base, rawCents: rawAmountCents(candidate.rule, sumValues(base)), match: null };
+}
+
 function chargeAllocation(state: EvaluationState, allocation: ReadonlyMap<string, number>): void {
   for (const [lineId, cents] of allocation) {
     state.remaining.set(lineId, (state.remaining.get(lineId) ?? 0) - cents);
   }
 }
 
-function toApplied(rule: DiscountRule, amountCents: number): AppliedDiscount {
-  return {
+/** R10 — the units are spent: no later combo may be paid for them again. */
+function depleteComboPool(state: EvaluationState, match: ComboMatch): void {
+  for (const [lineId, units] of match.consumedUnitsByLine) {
+    state.comboPool.set(lineId, Math.max(0, (state.comboPool.get(lineId) ?? 0) - units));
+  }
+}
+
+/**
+ * R10 — lock the consumed units at what the buyer will actually pay for them.
+ *
+ * `gross - allocated` is the combo's own net, so an item-level promotion is
+ * left with exactly `(quantity - consumed) x unitPrice` on that line: the
+ * units outside the combo, at full price. Locking the GROSS instead would hide
+ * the combo's discount from the order pass too, and locking nothing would let
+ * the item pass discount the bundle price a second time.
+ */
+function lockComboValue(
+  state: EvaluationState,
+  match: ComboMatch,
+  allocation: ReadonlyMap<string, number>,
+): void {
+  for (const [lineId, grossCents] of match.consumedCentsByLine) {
+    const netCents = Math.max(0, grossCents - (allocation.get(lineId) ?? 0));
+    state.comboLockedCents.set(lineId, (state.comboLockedCents.get(lineId) ?? 0) + netCents);
+  }
+}
+
+function toApplied(
+  rule: DiscountRule,
+  amountCents: number,
+  match: ComboMatch | null,
+): AppliedDiscount {
+  const applied: AppliedDiscount = {
     discountId: rule.id,
     name: rule.name,
     code: rule.code,
@@ -95,6 +220,8 @@ function toApplied(rule: DiscountRule, amountCents: number): AppliedDiscount {
     amountOffCents: rule.amountOffCents,
     amountCents,
   };
+  if (match === null) return applied;
+  return { ...applied, comboApplications: match.applications };
 }
 
 /**
@@ -111,9 +238,9 @@ function headroomCents(state: EvaluationState): number {
 }
 
 /**
- * Apply one candidate to the running state (R4 → R5 → R9 → R7) and return what
- * it removed. Zero removes nothing and records nothing — R5's `ZERO_VALUE` case,
- * because an `R$ 0,00` line is not a promotion.
+ * Apply one candidate to the running state (R4 → R5 → R9 → R7, plus R10 for a
+ * combo) and return what it removed. Zero removes nothing and records nothing —
+ * R5's `ZERO_VALUE` case, because an `R$ 0,00` line is not a promotion.
  *
  * The R9 cap sits BETWEEN the raw amount and the allocation on purpose: the
  * clamped amount is the one that gets split across the lines, so the per-line
@@ -122,14 +249,23 @@ function headroomCents(state: EvaluationState): number {
  * applied, and `./evaluate.ts` reports it as `ZERO_VALUE` — it removed nothing,
  * which is exactly what that reason means, and inventing a second "the cart is
  * already free" reason would say nothing more to a buyer.
+ *
+ * A combo that removes nothing consumes nothing either: the pool and the locks
+ * are only touched past the early return. That matters — a combo clamped to
+ * zero by the payable floor must not lock its units away from the item pass,
+ * having given the buyer nothing in exchange.
  */
 function applyOne(state: EvaluationState, candidate: Candidate): number {
-  const remaining = remainingFor(state, candidate.covered);
-  const rawCents = rawAmountCents(candidate.rule, sumValues(remaining));
-  const amountCents = Math.min(rawCents, headroomCents(state));
+  const plan = planFor(state, candidate);
+  const amountCents = Math.min(plan.rawCents, headroomCents(state));
   if (amountCents <= 0) return 0;
-  chargeAllocation(state, allocateByLargestRemainder(amountCents, remaining));
-  state.applied.push(toApplied(candidate.rule, amountCents));
+  const allocation = allocateByLargestRemainder(amountCents, plan.base);
+  chargeAllocation(state, allocation);
+  if (plan.match !== null) {
+    depleteComboPool(state, plan.match);
+    lockComboValue(state, plan.match, allocation);
+  }
+  state.applied.push(toApplied(candidate.rule, amountCents, plan.match));
   state.appliedTotalCents += amountCents;
   return amountCents;
 }
@@ -146,6 +282,10 @@ function applyOne(state: EvaluationState, candidate: Candidate): number {
  * into a tie and hand the choice of which one to NAME to the id tie-break. The
  * A-vs-B comparison in R8 is a different question and does compare capped
  * totals; see `runOutcome`.
+ *
+ * Combos are scored the same way and against the same pass-entry pool, so two
+ * combos competing for one set of units are ranked by what each is worth on the
+ * FULL cart, and the richer one claims its units first.
  */
 function orderPassCandidates(
   state: EvaluationState,
@@ -153,7 +293,7 @@ function orderPassCandidates(
 ): Candidate[] {
   const scored = candidates.map((candidate) => ({
     candidate,
-    amountCents: rawAmountCents(candidate.rule, sumValues(remainingFor(state, candidate.covered))),
+    amountCents: planFor(state, candidate).rawCents,
   }));
   scored.sort((a, b) => {
     const byAmount = b.amountCents - a.amountCents;
@@ -168,7 +308,7 @@ function runPass(state: EvaluationState, candidates: readonly Candidate[]): void
   }
 }
 
-/** R6 — the three fixed passes, narrowest scope first. */
+/** R6 — the four fixed passes, narrowest scope first. */
 function runPasses(state: EvaluationState, candidates: readonly Candidate[]): void {
   for (const scope of SCOPE_PASSES) {
     runPass(

package/src/engine/evaluate.ts

@@ -37,12 +37,16 @@ import type {
  *      `subtotalCents` is their sum. An empty cart short-circuits to a zero
  *      evaluation, with `EMPTY_CART` for any coupon the buyer supplied.
  * R2 — Eligibility screen (`./eligibility.ts`). A failing AUTOMATIC discount is
- *      dropped silently; a failing CODE discount the buyer typed is reported.
- * R3 — Covered set (`./eligibility.ts`).
+ *      dropped silently; a failing CODE discount the buyer typed is reported. A
+ *      combo the cart cannot assemble is reported as `COMBO_NOT_MATCHED` rather
+ *      than `NO_ELIGIBLE_ITEMS`, because it is the one failure here a buyer can
+ *      act on.
+ * R3 — Covered set (`./eligibility.ts`). For a combo this is a MATCH against the
+ *      pristine cart, not a target intersection.
  * R4 — A discount's base is what is STILL discountable on its covered lines, so
  *      a later discount never discounts money an earlier one already removed.
  * R5 — Raw amount (`./allocate.ts`).
- * R6 — Scope precedence `ITEM → CATEGORY → ORDER`, in three passes
+ * R6 — Scope precedence `COMBO → ITEM → CATEGORY → ORDER`, in four passes
  *      (`./evaluate-passes.ts`). Narrowest first, so an order-wide percentage is
  *      computed on the already item-discounted amount and an order-wide fixed
  *      amount is clamped to what is actually left.
@@ -55,6 +59,15 @@ import type {
  *      stackable ⇒ it forces A.
  * R9 — Payable floor: `totalCents = subtotalCents - discountTotalCents`, and a
  *      discounted order never lands below `MIN_PAYABLE_TOTAL_CENTS` (R$ 0,01).
+ * R10 — Combos (`./combo-match.ts`, `./evaluate-passes.ts`). A `COMBO`-scoped
+ *      rule matches UNITS against quantified slots, repeatedly, and prices each
+ *      application. Every combo draws from ONE shared unit pool, so two combos
+ *      can never both be paid for the same burger; and the units a combo
+ *      consumed are OPAQUE to the `ITEM` and `CATEGORY` passes, so a
+ *      component-targeted promotion cannot stack on top of a bundle price the
+ *      merchant set deliberately. `ORDER` is not blocked and applies to the
+ *      combo price, because an order-wide promotion is a statement about the
+ *      basket rather than about the components.
  *
  * ─── R9 CONTRADICTS THE FUT-235 SPEC ON PURPOSE. DO NOT "FIX" IT BACK. ───
  *

package/src/engine/kinds.ts

@@ -10,20 +10,54 @@
  */
 
 /**
- * How a discount computes its value. `PERCENTAGE` reads `percentOffBp`,
- * `FIXED_AMOUNT` reads `amountOffCents`; the DB CHECK enforces that exactly one
- * of the two columns is set.
+ * How a discount computes its value. Each type reads exactly ONE value column
+ * and the DB CHECK enforces that the other three are NULL:
+ *
+ * | type | column | means |
+ * |---|---|---|
+ * | `PERCENTAGE` | `percentOffBp` | basis points off its base |
+ * | `FIXED_AMOUNT` | `amountOffCents` | cents off its base |
+ * | `BUNDLE_PRICE` | `bundlePriceCents` | the matched group costs exactly this |
+ * | `FREE_UNITS` | `freeUnits` | the cheapest N units of the group are free |
+ *
+ * The last two are COMBO rewards and are only legal on a `COMBO`-scoped rule,
+ * because neither can be computed without a matched group to price: "the group
+ * costs R$ 25" and "one of them is free" are both statements ABOUT a group.
+ * `toDiscountScalars` refuses the combination, and a host's CHECK should too.
+ *
+ * The first two are legal at EVERY scope, `COMBO` included — "10% off when you
+ * buy the bundle" is a perfectly ordinary promotion, and it reads its base from
+ * the matched group like the other two.
  */
-export const DISCOUNT_TYPES = ["PERCENTAGE", "FIXED_AMOUNT"] as const;
+export const DISCOUNT_TYPES = [
+  "PERCENTAGE",
+  "FIXED_AMOUNT",
+  "BUNDLE_PRICE",
+  "FREE_UNITS",
+] as const;
 export type DiscountType = (typeof DISCOUNT_TYPES)[number];
 
+/** The two types that only mean something against a matched combo group. */
+export const COMBO_ONLY_DISCOUNT_TYPES = ["BUNDLE_PRICE", "FREE_UNITS"] as const;
+
 /**
  * What a discount is allowed to touch. `ORDER` carries no targets; `CATEGORY`
- * and `ITEM` are resolved through their join tables. The evaluator applies them
+ * and `ITEM` are resolved through their join tables; `COMBO` is resolved by
+ * MATCHING the cart against a list of quantified slots (see
+ * {@link ComboRequirement} in `./types`). The evaluator applies them
  * narrowest-first (R6) so an order-wide promo can never give away money an
  * item-level promo already removed.
+ *
+ * `COMBO` is the narrowest of the four and runs FIRST, because a combo price is
+ * a number the merchant set deliberately for a specific group of units, and
+ * everything else is an adjustment around it (R10).
+ *
+ * Appended rather than inserted: these values are stored as plain strings and
+ * typically pinned by a CHECK constraint, so the ARRAY's order is not a
+ * contract but its membership is. The pass order lives in
+ * `./evaluate-passes.ts`, which names the scopes explicitly.
  */
-export const DISCOUNT_SCOPES = ["ORDER", "CATEGORY", "ITEM"] as const;
+export const DISCOUNT_SCOPES = ["ORDER", "CATEGORY", "ITEM", "COMBO"] as const;
 export type DiscountScope = (typeof DISCOUNT_SCOPES)[number];
 
 /**
@@ -38,6 +72,15 @@ export type DiscountTrigger = (typeof DISCOUNT_TRIGGERS)[number];
  * surfaced for a coupon the buyer typed or for a promo displaced by an
  * exclusive one — a failing AUTOMATIC discount is silently skipped, because a
  * buyer must not be shown promotions they cannot have.
+ *
+ * `COMBO_NOT_MATCHED` is deliberately NOT folded into `NO_ELIGIBLE_ITEMS`,
+ * even though the two are the same predicate ("R3 covered nothing"), because
+ * the rest of this set is coarse for a reason that does not hold here: those
+ * reasons are merged when there is nothing the buyer could do differently. A
+ * buyer one soda short of a combo CAN act — adding it is the entire point of
+ * advertising the combo — so the sentence is worth its own key. See the pt-BR
+ * pack, where the scheduling reasons still collapse into one and this one
+ * does not.
  */
 export const DISCOUNT_REJECTION_REASONS = [
   "UNKNOWN_CODE",
@@ -48,6 +91,7 @@ export const DISCOUNT_REJECTION_REASONS = [
   "USAGE_LIMIT_REACHED",
   "BUYER_LIMIT_REACHED",
   "NO_ELIGIBLE_ITEMS",
+  "COMBO_NOT_MATCHED",
   "ZERO_VALUE",
   "NOT_STACKABLE",
   "EMPTY_CART",
@@ -81,6 +125,22 @@ export const MAX_PERCENT_OFF_BP = 10_000;
  */
 export const MIN_PAYABLE_TOTAL_CENTS = 1;
 
+/**
+ * The most slots one combo may declare, and the most units one slot may ask
+ * for. Both are FORM sanity rather than engine limits — the matcher is linear
+ * in slots x lines and would not care — and they exist for the two reasons the
+ * rest of this file's bounds do: an operator who typed 500 into a quantity
+ * field made a mistake worth a sentence, and a host that pins these as CHECK
+ * constraints needs a number to pin.
+ *
+ * Sized from what a combo IS rather than from what a database could hold: the
+ * spoken examples are two and three slots ("sandwich + soda", "popcorn + two
+ * sodas"), and a promotion nobody can describe in a sentence is not one a buyer
+ * will understand on a card.
+ */
+export const MAX_COMBO_SLOTS = 8;
+export const MAX_COMBO_SLOT_QUANTITY = 50;
+
 /** Codes are compared case- and whitespace-insensitively. */
 export function normalizeDiscountCode(raw: string): string {
   return raw.trim().toUpperCase();

package/src/engine/preview.ts

@@ -15,6 +15,12 @@ import type { DiscountCartLine, DiscountRule } from "./types";
  *   item's price;
  * - `ORDER` scope is excluded — an order-wide promo is not an item price and
  *   would badge the whole menu;
+ * - `COMBO` scope is excluded, for the same reason `minSubtotalCents` is: a
+ *   combo price only exists once the OTHER components are in the cart, so
+ *   striking a single item's price through with it would advertise a number
+ *   this item alone can never reach. What a card CAN honestly say about a combo
+ *   is that the item takes part in one, which is `comboOffersForItem` in
+ *   `./combo-offer.ts` — a label, not a price;
  * - a `minSubtotalCents` threshold is excluded — a card promising a price that
  *   only materializes above some basket total is a lie;
  * - `stackable` is ignored: this previews ONE item at ONE price, and which
@@ -92,7 +98,10 @@ const PREVIEW_LINE_ID = "preview";
 
 function isBadgeable(rule: DiscountRule): boolean {
   return (
-    rule.trigger === "AUTOMATIC" && rule.scope !== "ORDER" && rule.minSubtotalCents === null
+    rule.trigger === "AUTOMATIC" &&
+    rule.scope !== "ORDER" &&
+    rule.scope !== "COMBO" &&
+    rule.minSubtotalCents === null
   );
 }
 

package/src/engine/pt-BR.ts

@@ -9,6 +9,13 @@ import { MIN_SUBTOTAL_TOKEN, type DiscountRejectionCopy } from "./rejection-copy
  * Deliberately coarser than the reason set: switched off, not started yet and
  * expired all read the same, because the difference only leaks how the
  * merchant schedules promotions and the buyer could not act on it either way.
+ *
+ * `COMBO_NOT_MATCHED` is the one place that coarsening stops, and for the same
+ * test read the other way: a buyer one soda short of the combo can finish it,
+ * so telling them WHICH kind of failure this was is the difference between a
+ * dead end and a sale. It does not name the missing item — the evaluator does
+ * not report one, because "which item is missing" has no single answer when a
+ * slot accepts a whole category.
  */
 export const PT_BR_DISCOUNT_REJECTION_COPY: DiscountRejectionCopy = {
   UNKNOWN_CODE: "Cupom inválido ou expirado.",
@@ -19,6 +26,7 @@ export const PT_BR_DISCOUNT_REJECTION_COPY: DiscountRejectionCopy = {
   USAGE_LIMIT_REACHED: "Este cupom já atingiu o limite de uso.",
   BUYER_LIMIT_REACHED: "Você já usou este cupom.",
   NO_ELIGIBLE_ITEMS: "Este cupom não vale para os itens do seu carrinho.",
+  COMBO_NOT_MATCHED: "Seu carrinho ainda não tem todos os itens deste combo.",
   ZERO_VALUE: "Este cupom não vale para os itens do seu carrinho.",
   NOT_STACKABLE: "Outra promoção já aplicada é melhor que este cupom.",
   EMPTY_CART: "Seu carrinho está vazio.",