@12-apps/discounts 1.11.0 → 1.13.0

package/src/e2e/globs.ts

@@ -0,0 +1,70 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+/**
+ * Where this package's journeys and their steps live, ON DISK, in the consumer's
+ * `node_modules`.
+ *
+ * `defineBddConfig` takes filesystem globs, not module specifiers — it hands
+ * them to a glob matcher, so `'@12-apps/discounts/features/**'` matches
+ * nothing and, worse, matches nothing SILENTLY: bddgen compiles the features it
+ * found, finds none, and the run is green with zero journeys.
+ *
+ * So the paths are RESOLVED here instead of written down by every consumer. A
+ * host that hard-codes `node_modules/@12-apps/discounts/...` is broken by
+ * pnpm's nested store, by a workspace link, and by this package's own layout
+ * changing; resolving from the package's own entry point is correct under all
+ * three.
+ */
+const require_ = createRequire(import.meta.url);
+
+/**
+ * The package root, found from a file this package definitely exports.
+ * `./package.json` is exported precisely so this lookup needs no guess about
+ * directory depth.
+ */
+function packageRoot(): string {
+  return dirname(require_.resolve('@12-apps/discounts/package.json'));
+}
+
+/** Every packaged `.feature`, for `defineBddConfig({ features })`. */
+export const discountsFeatures: string = join(packageRoot(), 'features/**/*.feature');
+
+/**
+ * The base `defineBddConfig({ featuresRoot })` must be given, and it is NOT
+ * optional decoration.
+ *
+ * bddgen mirrors each feature's path RELATIVE TO `featuresRoot` under
+ * `outputDir`. Left unset it defaults to the config's own directory, so a
+ * feature living under `node_modules/...` compiles to a path Playwright then
+ * IGNORES, because its default `testIgnore` excludes `**\/node_modules/**`.
+ *
+ * The result is the worst kind of green: bddgen reports the features compiled,
+ * Playwright collects zero specs from them, and the run passes with the whole
+ * packaged suite silently absent.
+ *
+ * A host running SEVERAL packaged suites gives `featuresRoot` the directory they
+ * all sit under, since bddgen takes exactly one — and that is safe to do,
+ * because a feature outside it is a hard exit from bddgen, never a quiet
+ * omission.
+ */
+export const discountsFeaturesRoot: string = join(packageRoot(), 'features');
+
+/**
+ * Every packaged step definition, for `defineBddConfig({ steps })`.
+ *
+ * COMPILED JavaScript, and that is the reason this package has a build step at
+ * all while everything else it exports is raw `.ts` through the `exports` map.
+ * Those entries are consumed by an application's BUNDLER, which transpiles
+ * whatever it is pointed at. These are loaded by NODE — `playwright.config.ts`
+ * imports this module, and bddgen imports the step files — and Node refuses to
+ * strip types from anything under `node_modules`
+ * (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). Playwright's own TS transform
+ * does not rescue them either; it skips `node_modules` by design.
+ *
+ * The host's own steps glob must ALSO be listed — that is where its
+ * `defineDiscountsWorld` call lives, and playwright-bdd imports every step
+ * file before any scenario runs, which is what makes the registration land in
+ * time in every worker.
+ */
+export const discountsSteps: string = join(packageRoot(), 'dist/e2e/steps/**/*.js');

package/src/e2e/index.ts

@@ -0,0 +1,16 @@
+/**
+ * `@12-apps/discounts/e2e` — the packaged promotions journeys and the port a
+ * host implements to run them.
+ *
+ * The `e2e` capability the manifest declares. A host adds the three globs to
+ * its bdd config and calls `defineDiscountsWorld` from inside its own steps
+ * glob; every scenario this package ships then runs in that host, including the
+ * ones added after it integrated. Nothing is copied, so nothing can rot.
+ */
+export { discountsFeatures, discountsFeaturesRoot, discountsSteps } from './globs.js';
+export {
+  defineDiscountsWorld,
+  discountsWorld,
+  type DiscountsFixtures,
+  type DiscountsWorld,
+} from './world.js';

package/src/e2e/steps/journey.steps.ts

@@ -0,0 +1,170 @@
+import { expect, type Locator, type Page } from '@playwright/test';
+import { createBdd } from 'playwright-bdd';
+
+import { discountsWorld } from '../world.js';
+
+/**
+ * The packaged journeys' step definitions.
+ *
+ * Every locator is a test id THIS package's own components render, which is
+ * what makes the scenarios portable: `discounts-grid`, `discount-dialog`,
+ * `discount-action-edit`, `combo-slots` and the `total-form-field-*` family
+ * mean the same thing in any app that mounts `createWebDiscounts`. Everything a
+ * host owns — sign-in, routing, how a percentage reads — arrives through the
+ * world port rather than being written down here.
+ *
+ * ## Why `package.json` declares this file under `sideEffects`
+ *
+ * Every Given/When/Then below runs at IMPORT time — registering a step is the
+ * whole point of the module, and it exports nothing anybody imports by name. To
+ * a bundler doing tree-shaking that reads as dead weight, and dropping it is
+ * licensed: the result is a suite where bddgen reports the features compiled
+ * and every scenario then fails on an undefined step.
+ *
+ * Not one step asserts a SENTENCE. The origin host's spec did — it clicked
+ * `menuitem { name: 'Editar' }` and a `Salvar alterações` button — which is why
+ * it could only ever have run in that host: copy is required config, so the next
+ * adopter's words are different by construction and the spec would fail for a
+ * reason unrelated to promotions working.
+ */
+const { Given, When, Then } = createBdd();
+
+const GRID = 'discounts-grid';
+const DIALOG = 'discount-dialog';
+
+/** The name the current scenario minted, so later steps can find its row. */
+let currentName = '';
+
+Given('I am signed in as somebody who may manage promotions', async ({ page }) => {
+  await discountsWorld().signInAsManager(page);
+});
+
+When('I open the promotions screen', async ({ page }) => {
+  await discountsWorld().openDiscountsScreen(page);
+  await expect(page.getByTestId(GRID)).toBeVisible();
+});
+
+Then('the promotions grid is visible', async ({ page }) => {
+  await expect(page.getByTestId(GRID)).toBeVisible();
+});
+
+/** The create dialog, open and ready to be filled. */
+async function openCreateDialog(page: Page): Promise<Locator> {
+  await page.getByTestId('new-discount-button').click();
+  const dialog = page.getByTestId(DIALOG);
+  await expect(dialog).toBeVisible();
+  return dialog;
+}
+
+When('I compose a percentage promotion', async ({ page }) => {
+  const { newName, percent } = discountsWorld().fixtures;
+  currentName = newName('Journey');
+  const dialog = await openCreateDialog(page);
+  await dialog.getByTestId('total-form-field-name').fill(currentName);
+  // Percentage is the default kind; clicking it anyway is the interaction that
+  // proves the toggle drives which value field is mounted.
+  await dialog.getByTestId('total-form-field-kind-item-PERCENTAGE').click();
+  await dialog.getByTestId('total-form-field-percentOff').fill(percent);
+  await dialog.getByTestId('discount-form-submit').click();
+  await expect(dialog).toBeHidden();
+});
+
+/**
+ * The row is found by NAME, and a name is the one user-visible string here that
+ * is not copy — the scenario chose it a moment ago, so naming it is naming a
+ * fixture rather than an adopter's wording.
+ */
+function rowFor(page: Page, name: string): Locator {
+  return page.getByTestId(GRID).getByRole('row', { name: new RegExp(name) });
+}
+
+Then('the promotion is listed with its rate', async ({ page }) => {
+  const row = rowFor(page, currentName);
+  await expect(row).toBeVisible();
+  // The round trip is the claim: a rate typed as a percentage comes back as one
+  // only if the conversion into basis points and back out BOTH ran. How it
+  // reads is the host's formatting, so the host states it.
+  await expect(row.getByText(discountsWorld().fixtures.percentInGrid)).toBeVisible();
+});
+
+When('I start composing a promotion', async ({ page }) => {
+  await openCreateDialog(page);
+});
+
+Then('the percentage field is the one on screen', async ({ page }) => {
+  await expect(page.getByTestId(DIALOG).getByTestId('total-form-field-percentOff')).toBeVisible();
+});
+
+When('I switch it to a fixed amount', async ({ page }) => {
+  await page.getByTestId(DIALOG).getByTestId('total-form-field-kind-item-FIXED_AMOUNT').click();
+});
+
+Then('the amount field REPLACES the percentage one', async ({ page }) => {
+  const dialog = page.getByTestId(DIALOG);
+  await expect(dialog.getByTestId('total-form-field-amountOff')).toBeVisible();
+  // Replaced, not hidden: a merely-hidden percentage input would still submit a
+  // stale rate alongside an amount the operator typed.
+  await expect(dialog.getByTestId('total-form-field-percentOff')).toHaveCount(0);
+});
+
+When('I switch it to a combo', async ({ page }) => {
+  await page.getByTestId(DIALOG).getByTestId('total-form-field-kind-item-COMBO').click();
+});
+
+Then('the scope question disappears and the group builder takes its place', async ({ page }) => {
+  const dialog = page.getByTestId(DIALOG);
+  // A combo COVERS the groups it is made of, so scope stops being a question at
+  // all — unmounted rather than disabled. That is what stops an operator
+  // building a combination the write path then refuses.
+  await expect(dialog.getByTestId('total-form-field-scope-item-ORDER')).toHaveCount(0);
+  await expect(dialog.getByTestId('combo-slots')).toBeVisible();
+});
+
+Then('the scope question comes back for a plain kind', async ({ page }) => {
+  const dialog = page.getByTestId(DIALOG);
+  await dialog.getByTestId('total-form-field-kind-item-FIXED_AMOUNT').click();
+  await expect(dialog.getByTestId('total-form-field-scope-item-ORDER')).toBeVisible();
+});
+
+When('I set the activation to a coupon code', async ({ page }) => {
+  await page.getByTestId(DIALOG).getByTestId('total-form-field-trigger-item-CODE').click();
+});
+
+Then('the coupon field is revealed', async ({ page }) => {
+  await expect(page.getByTestId(DIALOG).getByTestId('total-form-field-code')).toBeVisible();
+});
+
+/** Open the row's kebab and take one of its entries by its STABLE id. */
+async function chooseRowAction(page: Page, action: 'edit' | 'delete'): Promise<void> {
+  await rowFor(page, currentName).locator('[data-testid^="discount-actions-"]').click();
+  await page.getByTestId(`discount-action-${action}`).click();
+}
+
+When('I rename it from the row menu', async ({ page }) => {
+  await chooseRowAction(page, 'edit');
+  const dialog = page.getByTestId(DIALOG);
+  await expect(dialog).toBeVisible();
+  currentName = `${currentName} II`;
+  await dialog.getByTestId('total-form-field-name').fill(currentName);
+  await dialog.getByTestId('discount-form-submit').click();
+  await expect(dialog).toBeHidden();
+});
+
+Then('the grid shows the new name', async ({ page }) => {
+  // The grid re-read the server — proof the write landed, rather than proof the
+  // dialog closed.
+  await expect(rowFor(page, currentName)).toBeVisible();
+});
+
+When('I delete it from the row menu', async ({ page }) => {
+  await chooseRowAction(page, 'delete');
+  // The menu entry only OPENS the confirmation; the DELETE leaves when it is
+  // confirmed.
+  await page.getByTestId('discount-delete-confirm-confirm-button').click();
+});
+
+Then('the promotion is gone from the grid', async ({ page }) => {
+  // A soft delete: the row leaves the list even though the record survives for
+  // its redemption history.
+  await expect(rowFor(page, currentName)).toHaveCount(0);
+});

package/src/e2e/world.ts

@@ -0,0 +1,93 @@
+import type { Page } from '@playwright/test';
+
+/**
+ * The port a HOST implements to run the packaged promotions journeys.
+ *
+ * The journeys are portable because every assertion in them reads a test id
+ * this package's own components render — `discounts-grid`, `discount-dialog`,
+ * `discount-action-edit`, `total-form-field-*` mean the same thing in any app
+ * that mounts `createWebDiscounts`. What is NOT portable is everything around
+ * them: how an app signs somebody in, how it routes to the promotions screen,
+ * how it returns to a known state, and how it renders a percentage.
+ *
+ * It replaces a 167-line spec in the origin host (`discounts.e2e.ts`), which
+ * asserted this package's test ids from a repo it does not build — the
+ * arrangement whose failure mode is silent from here: rename an id inside the
+ * package and a spec it cannot see goes red somewhere it does not run.
+ */
+
+/**
+ * Facts about the host that the assertions have to name.
+ *
+ * A journey has to talk about SOMETHING: a permission to tick, a name to type,
+ * a rendered value to look for. None of that can live in a feature file without
+ * inventing one host's fixture as though it were everybody's.
+ */
+export interface DiscountsFixtures {
+  /**
+   * A name no seed uses, minted FRESH per call.
+   *
+   * A function rather than a string because these journeys WRITE: the
+   * promotions table carries a per-tenant unique index on the name, so a
+   * constant would collide with itself on the second scenario and on every
+   * re-run against the same database.
+   */
+  newName: (prefix: string) => string;
+  /** The percentage a create journey types, as the form takes it (e.g. `15`). */
+  percent: string;
+  /**
+   * How that percentage READS in the grid once saved (e.g. `15%`).
+   *
+   * Stated by the host because formatting is the host's: `createWebDiscounts`
+   * takes a locale and a currency, so the same 15 renders differently in two
+   * adopters. It is the round-trip that matters — a value typed as a percentage
+   * comes back as one only if the conversion into basis points and back out
+   * both ran — and this is the half a package cannot spell.
+   */
+  percentInGrid: string;
+}
+
+/** What a host must be able to do for these journeys to run in it. */
+export interface DiscountsWorld {
+  /**
+   * Put the browser in a known signed-in state as somebody who may manage
+   * promotions, and return the store to a known one.
+   *
+   * These journeys write, so the reset is load-bearing rather than hygiene: a
+   * scenario that renamed a promotion would otherwise hand the next one a
+   * catalog it did not expect.
+   */
+  signInAsManager(page: Page): Promise<void>;
+  /** Land on the promotions screen and wait until its grid has rendered. */
+  openDiscountsScreen(page: Page): Promise<void>;
+  fixtures: DiscountsFixtures;
+}
+
+let installed: DiscountsWorld | null = null;
+
+/**
+ * Install the host's implementation. Call this from a module inside the host's
+ * OWN steps glob — playwright-bdd imports every step file before any scenario
+ * runs, so a top-level call there is registered in time, in every worker.
+ */
+export function defineDiscountsWorld(world: DiscountsWorld): void {
+  installed = world;
+}
+
+/**
+ * The installed world, or a refusal naming the fix.
+ *
+ * Throws rather than returning null: a step that ran against an absent world
+ * would fail on whatever it touched next, somewhere unrelated to the actual
+ * mistake, which is a diagnosis nobody should have to make twice.
+ */
+export function discountsWorld(): DiscountsWorld {
+  if (!installed) {
+    throw new Error(
+      'No discounts e2e world is installed. Call defineDiscountsWorld({ … }) from a module ' +
+        "inside your own `steps` glob — playwright-bdd imports those before any " +
+        'scenario runs, which is what makes the registration land in every worker.',
+    );
+  }
+  return installed;
+}

package/src/engine/combo-offer.ts

@@ -1,5 +1,6 @@
 import { comboRuleAcceptsLine } from "./combo-match";
 import { compareRuleOrder } from "./evaluate-passes";
+import { scheduleCovers, type LocalClock } from "./schedule";
 import type { DiscountType } from "./kinds";
 import type { ComboRequirement, DiscountCartLine, DiscountRule } from "./types";
 
@@ -74,6 +75,8 @@ export interface ComboOffersInput {
   rules: readonly DiscountRule[];
   /** Evaluation instant. Injected — this module never calls `new Date()`. */
   now: Date;
+  /** `now` as the store's wall clock, for a combo that only runs some hours. */
+  localNow?: LocalClock | null;
 }
 
 /** The synthetic one-unit line a slot is tested against. */
@@ -99,11 +102,22 @@ function toOfferLine(input: ComboOffersInput): DiscountCartLine {
  * 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.
+ *
+ * It DOES honour the weekly schedule (FUT-996), and that is not optional: this
+ * predicate is a SECOND implementation of "inside its window", so a schedule
+ * taught only to `screenRule` would leave a Tuesday-afternoon combo advertising
+ * itself around the clock while the cart refused to price it. The duplication
+ * above is deliberate; a duplication that disagrees is not.
  */
-function isAdvertisable(rule: DiscountRule, now: Date): boolean {
+function isAdvertisable(
+  rule: DiscountRule,
+  now: Date,
+  localNow: LocalClock | null | undefined,
+): 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;
+  if (!scheduleCovers(rule.schedule, localNow)) return false;
   return rule.usageLimit === null || rule.usageCount < rule.usageLimit;
 }
 
@@ -139,9 +153,10 @@ function toOffer(rule: DiscountRule): ComboOffer {
 export function advertisableCombos(
   rules: readonly DiscountRule[],
   now: Date,
+  localNow?: LocalClock | null,
 ): readonly ComboOffer[] {
   return rules
-    .filter((rule) => isAdvertisable(rule, now))
+    .filter((rule) => isAdvertisable(rule, now, localNow))
     .sort(compareRuleOrder)
     .map(toOffer);
 }
@@ -155,7 +170,10 @@ export function advertisableCombos(
 export function comboOffersForItem(input: ComboOffersInput): readonly ComboOffer[] {
   const line = toOfferLine(input);
   return input.rules
-    .filter((rule) => isAdvertisable(rule, input.now) && comboRuleAcceptsLine(rule, line))
+    .filter(
+      (rule) =>
+        isAdvertisable(rule, input.now, input.localNow) && comboRuleAcceptsLine(rule, line),
+    )
     .sort(compareRuleOrder)
     .map(toOffer);
 }

package/src/engine/eligibility.ts

@@ -1,5 +1,6 @@
 import { comboCoveredLineIds } from "./combo-match";
 import type { DiscountRejectionReason } from "./kinds";
+import { scheduleCovers, type LocalClock } from "./schedule";
 import type { DiscountCartLine, DiscountRule } from "./types";
 
 /**
@@ -32,6 +33,15 @@ interface ScreenContext {
   subtotalCents: number;
   /** Whether R3's covered set came back non-empty for this rule. */
   hasEligibleItems: boolean;
+  /**
+   * True when R3 covered lines the SCHEDULE then took away (FUT-996) — i.e.
+   * the rule would have applied but not at this hour.
+   *
+   * Kept separate from `hasEligibleItems` because the two are different
+   * sentences to a buyer: "não vale para os itens do seu carrinho" is a dead
+   * end, and "o happy hour começa às 16:00" is an invitation.
+   */
+  blockedBySchedule: boolean;
 }
 
 /**
@@ -148,6 +158,69 @@ function screenLimits(rule: DiscountRule, ctx: ScreenContext): DiscountRejection
   return null;
 }
 
+/**
+ * Which lines a SCHEDULED rule may touch, and whether the schedule is what
+ * emptied the set (FUT-996).
+ *
+ * Screening is PER LINE, against each line's own `committedLocal`, because a
+ * cart is not committed all at once: a beer added at 19:55 and one added at
+ * 20:05 are two different facts, and pricing them alike would mean either
+ * charging for a promotion the shopper earned or honouring one they did not.
+ *
+ * The three scopes answer it differently, and each difference is forced:
+ *
+ * - **`ORDER`** names no line at all, so there is nothing to anchor to and it
+ *   screens against `localNow` — the checkout instant. An order-wide discount
+ *   is a fact about the order, and the order comes into existence at checkout.
+ * - **`COMBO`** is RE-MATCHED over the qualifying lines rather than
+ *   intersected, because a combo's coverage is not a set intersection but a
+ *   match: "leve 3, pague 2 na terça à tarde" must not assemble itself from two
+ *   units bought in the afternoon and one bought at night. Intersecting after
+ *   the fact would have kept the units and lost the requirement.
+ * - **`ITEM` / `CATEGORY`** intersect, which is exactly what they mean.
+ */
+function scheduledCoverage(
+  rule: DiscountRule,
+  lines: readonly DiscountCartLine[],
+  pristine: ReadonlySet<string>,
+  localNow: LocalClock | null | undefined,
+): { covered: ReadonlySet<string>; blockedBySchedule: boolean } {
+  if (rule.schedule === null || rule.schedule === undefined) {
+    return { covered: pristine, blockedBySchedule: false };
+  }
+  if (rule.scope === "ORDER") {
+    const running = scheduleCovers(rule.schedule, localNow);
+    return {
+      covered: running ? pristine : new Set<string>(),
+      blockedBySchedule: !running && pristine.size > 0,
+    };
+  }
+  const qualifying = lines.filter((line) =>
+    scheduleCovers(rule.schedule, line.committedLocal),
+  );
+  const covered =
+    rule.scope === "COMBO"
+      ? comboCoveredLineIds(rule, qualifying)
+      : new Set([...pristine].filter((lineId) => qualifying.some((l) => l.lineId === lineId)));
+  return { covered, blockedBySchedule: covered.size === 0 && pristine.size > 0 };
+}
+
+/**
+ * R3 + the schedule, in one call: what this rule may touch right now, and
+ * whether the schedule is the reason it may touch nothing.
+ *
+ * The two are returned together because a caller needs both to say the right
+ * thing, and computing them apart would mean matching a combo twice.
+ */
+export function coveredLineIdsNow(
+  rule: DiscountRule,
+  lines: readonly DiscountCartLine[],
+  index: LineIndex,
+  localNow: LocalClock | null | undefined,
+): { covered: ReadonlySet<string>; blockedBySchedule: boolean } {
+  return scheduledCoverage(rule, lines, coveredLineIds(rule, lines, index), localNow);
+}
+
 /**
  * R2 — the eligibility screen. Returns the FIRST failing predicate's reason, or
  * null when the rule is a live candidate. The order is not arbitrary: it runs
@@ -173,5 +246,8 @@ export function screenRule(
   const limits = screenLimits(rule, ctx);
   if (limits !== null) return limits;
   if (ctx.hasEligibleItems) return null;
+  // Before the two coarse reasons, because it is the one the buyer can act on:
+  // this rule DOES cover their cart, just not at this hour.
+  if (ctx.blockedBySchedule) return "OUT_OF_SCHEDULE";
   return rule.scope === "COMBO" ? "COMBO_NOT_MATCHED" : "NO_ELIGIBLE_ITEMS";
 }

package/src/engine/en-US.ts

@@ -25,6 +25,7 @@ export const EN_US_DISCOUNT_REJECTION_COPY: DiscountRejectionCopy = {
   INACTIVE: "That coupon is invalid or expired.",
   NOT_STARTED: "That coupon is invalid or expired.",
   EXPIRED: "That coupon is invalid or expired.",
+  OUT_OF_SCHEDULE: "This promotion is not running right now.",
   MIN_SUBTOTAL_NOT_MET: `This coupon needs a minimum order of ${MIN_SUBTOTAL_TOKEN}.`,
   USAGE_LIMIT_REACHED: "This coupon has reached its usage limit.",
   BUYER_LIMIT_REACHED: "You have already used this coupon.",

package/src/engine/evaluate.ts

@@ -1,6 +1,6 @@
 import { maxDiscountableCents } from "./allocate";
 import { normalizeDiscountCode } from "./kinds";
-import { buildLineIndex, coveredLineIds, screenRule } from "./eligibility";
+import { buildLineIndex, coveredLineIdsNow, screenRule } from "./eligibility";
 import {
   compareRuleOrder,
   lineGrossCents,
@@ -187,11 +187,17 @@ function screenOneRule(
   context: { subtotalCents: number; couponCode: string | null; index: LineIndex },
 ): Screened {
   if (rule.trigger === "CODE" && rule.code !== context.couponCode) return { kind: "skipped" };
-  const covered = coveredLineIds(rule, input.lines, context.index);
+  const { covered, blockedBySchedule } = coveredLineIdsNow(
+    rule,
+    input.lines,
+    context.index,
+    input.localNow,
+  );
   const reason = screenRule(rule, {
     now: input.now,
     subtotalCents: context.subtotalCents,
     hasEligibleItems: covered.size > 0,
+    blockedBySchedule,
   });
   if (reason === null) return { kind: "candidate", candidate: { rule, covered } };
   if (rule.trigger !== "CODE") return { kind: "skipped" };

package/src/engine/kinds.ts

@@ -135,6 +135,12 @@ export function discountWindowState(
  * exclusive one — a failing AUTOMATIC discount is silently skipped, because a
  * buyer must not be shown promotions they cannot have.
  *
+ * `OUT_OF_SCHEDULE` earns its own key for the same reason `COMBO_NOT_MATCHED`
+ * does, and NOT the one `NOT_STARTED`/`EXPIRED` share. A campaign that has
+ * ended is over; there is nothing the buyer can do. A promotion that runs on
+ * Fridays from 16:00 is one they can simply come back for, and "expirado" would
+ * send them away from a shop that will sell it to them in an hour.
+ *
  * `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
@@ -149,6 +155,7 @@ export const DISCOUNT_REJECTION_REASONS = [
   "INACTIVE",
   "NOT_STARTED",
   "EXPIRED",
+  "OUT_OF_SCHEDULE",
   "MIN_SUBTOTAL_NOT_MET",
   "USAGE_LIMIT_REACHED",
   "BUYER_LIMIT_REACHED",

package/src/engine/preview.ts

@@ -1,6 +1,7 @@
 import { maxDiscountableCents, rawAmountCents } from "./allocate";
-import { buildLineIndex, coveredLineIds, screenRule } from "./eligibility";
+import { buildLineIndex, coveredLineIdsNow, screenRule } from "./eligibility";
 import { compareRuleOrder } from "./evaluate-passes";
+import type { LocalClock } from "./schedule";
 import type { DiscountCartLine, DiscountRule } from "./types";
 
 /**
@@ -76,6 +77,19 @@ export interface ItemDiscountPreviewInput {
   rules: readonly DiscountRule[];
   /** Evaluation instant. Injected — this module never calls `new Date()`. */
   now: Date;
+  /**
+   * `now` as the STORE's wall clock (FUT-996), for a rule that only runs on
+   * certain days and hours.
+   *
+   * A badge is a PRICE, and the price a card may promise is the one a shopper
+   * adding this item RIGHT NOW would get — so the preview screens the schedule
+   * against `now` for both halves: it is the evaluation instant and, for
+   * anything added off the back of this card, the commit instant too.
+   *
+   * Omitted or null → scheduled rules badge as if always running, the same
+   * fail-open direction the rest of the schedule takes.
+   */
+  localNow?: LocalClock | null;
 }
 
 /** What a host needs to render the badge: the struck price and its label. */
@@ -113,6 +127,10 @@ function toPreviewLine(input: ItemDiscountPreviewInput): DiscountCartLine {
     categoryPath: input.categoryPath,
     quantity: 1,
     unitPriceCents: input.priceCents,
+    // The shopper is looking at this card NOW, so the instant it would be
+    // committed at is `now` — which is what lets one predicate answer both the
+    // badge and the cart without the card promising an hour it cannot deliver.
+    committedLocal: input.localNow ?? null,
   };
 }
 
@@ -133,14 +151,22 @@ function bestBadgeRule(
   const index = buildLineIndex([line]);
   const scored = input.rules
     .filter(isBadgeable)
-    .filter(
-      (rule) =>
+    .filter((rule) => {
+      const { covered, blockedBySchedule } = coveredLineIdsNow(
+        rule,
+        [line],
+        index,
+        input.localNow,
+      );
+      return (
         screenRule(rule, {
           now: input.now,
           subtotalCents: input.priceCents,
-          hasEligibleItems: coveredLineIds(rule, [line], index).has(PREVIEW_LINE_ID),
-        }) === null,
-    )
+          hasEligibleItems: covered.has(PREVIEW_LINE_ID),
+          blockedBySchedule,
+        }) === null
+      );
+    })
     .map((rule) => ({
       rule,
       amountCents: Math.min(

package/src/engine/pt-BR.ts

@@ -10,6 +10,13 @@ import { MIN_SUBTOTAL_TOKEN, type DiscountRejectionCopy } from "./rejection-copy
  * 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.
  *
+ * `OUT_OF_SCHEDULE` is the SECOND place it stops, and by the same test.
+ * "Inválido ou expirado" sends a buyer away from a shop that will sell them
+ * this in an hour; a promotion that runs on Friday afternoons is one they can
+ * simply come back for. It stays vague about WHEN on purpose — the hours are on
+ * the card, and a rejection message that recited a merchant's whole schedule
+ * would be both long and a leak.
+ *
  * `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
@@ -22,6 +29,7 @@ export const PT_BR_DISCOUNT_REJECTION_COPY: DiscountRejectionCopy = {
   INACTIVE: "Cupom inválido ou expirado.",
   NOT_STARTED: "Cupom inválido ou expirado.",
   EXPIRED: "Cupom inválido ou expirado.",
+  OUT_OF_SCHEDULE: "Esta promoção não está valendo agora.",
   MIN_SUBTOTAL_NOT_MET: `Este cupom exige um pedido mínimo de ${MIN_SUBTOTAL_TOKEN}.`,
   USAGE_LIMIT_REACHED: "Este cupom já atingiu o limite de uso.",
   BUYER_LIMIT_REACHED: "Você já usou este cupom.",