@12-apps/discounts 1.12.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "type": "module",
   "sideEffects": [
     "**/e2e/**"
@@ -24,7 +24,8 @@
     "./e2e": {
       "types": "./dist/e2e/index.d.ts",
       "default": "./dist/e2e/index.js"
-    }
+    },
+    "./timezone": "./src/timezone.ts"
   },
   "scripts": {
     "build": "tsc -p tsconfig.e2e.json",
@@ -40,10 +41,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@12-apps/app-shell": "^5.5.0",
+    "@12-apps/app-shell": "^5.11.0",
     "@12-apps/forms-core": "^1.21.0",
     "@12-apps/shared-helpers": "^2.1.0",
-    "@12-apps/ui": "^6.10.0",
+    "@12-apps/ui": "^6.42.0",
     "@mui/icons-material": "^6.5.0",
     "zod": "^4.3.5"
   },
@@ -77,9 +78,9 @@
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.22.0",
-    "@12-apps/i18n": "^1.2.0",
+    "@12-apps/i18n": "^1.3.0",
     "@12-apps/typescript-config": "^1.21.0",
-    "@12-apps/wiring": "^1.14.0",
+    "@12-apps/wiring": "^1.16.0",
     "@electric-sql/pglite": "^0.2.17",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",

package/prisma/discounts.prisma

@@ -79,6 +79,29 @@ model Discount {
   // either side = open-ended.
   startsAt             DateTime? @map("starts_at")
   endsAt               DateTime? @map("ends_at")
+  // The WEEKLY schedule INSIDE that window (FUT-996) — "toda sexta, das 16:00
+  // às 20:00", "segunda e terça à tarde". NULL = always, within
+  // [starts_at, ends_at), which is what every row predating the feature means.
+  //
+  //   {"windows":[{"days":[4],"from":"16:00","to":"20:00"}]}
+  //
+  // `days` is Monday-first 0..6 — the axis every hours surface uses, and NOT
+  // `Date#getDay()`'s Sunday-first one. `from`/`to` are "HH:MM" in the STORE's
+  // timezone, half-open [from, to) exactly as the campaign window is, and a
+  // `to` earlier than `from` runs past midnight rather than being invalid.
+  //
+  // JSON rather than a fourth table because the recurrence is not usefully
+  // SQL-queryable (the grid's vigência filter already cannot express the
+  // campaign window either), and a fourth table would put a third `include` on
+  // the storefront's hottest read. The cost is that the DATABASE cannot check
+  // this shape: `assertSchedule` is the only gate, and the evaluator treats a
+  // malformed window as covering NOTHING, so a bad blob is a promotion that
+  // does not fire rather than a cart priced wrong.
+  //
+  // A recurring window is a WALL-CLOCK fact, so it is only meaningful against
+  // the store's own timezone. The engine never reads one: a host resolves the
+  // instant into a weekday and a minute-of-day and passes those in.
+  schedule             Json?     @map("schedule")
   // 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.

package/prisma/migrations/20260830120000_discount_weekly_schedule/migration.sql

@@ -0,0 +1,40 @@
+-- @12-apps/discounts: the WEEKLY schedule (FUT-996).
+--
+-- "Toda sexta, das 16:00 às 20:00" — a recurring window INSIDE the campaign
+-- `[starts_at, ends_at)`, which until now was the only scheduling a rule had.
+--
+-- ── PURELY ADDITIVE, AND THAT IS THE POINT ────────────────────────────────
+-- One nullable column, no backfill, no CHECK to widen, nothing dropped. NULL
+-- means "always, within the campaign window", which is exactly what every
+-- existing row already means — so this migration cannot change the price of
+-- anything, and the release carrying it needs none of the expand/contract
+-- ceremony a destructive DDL would (see the host's CLAUDE.md on why a
+-- `DROP COLUMN` takes production down for the length of a healthcheck).
+--
+-- Replay-safe like its predecessor: `IF NOT EXISTS` throughout.
+--
+-- ── WHY JSON RATHER THAN A FOURTH TABLE ───────────────────────────────────
+-- The recurrence is not SQL-queryable in any useful way. The admin grid's
+-- vigência filter already punts on comparing two nullable timestamps against
+-- `now()` and rides as a separate parameter the store resolves, so a schedule
+-- table would buy queryability that nothing asks for — while adding a third
+-- `include` to `loadDiscountRules`, which is on the storefront's hottest read
+-- (a whole menu page's badge preview walks it once per request).
+--
+-- The trade is stated plainly: the database cannot check this column's SHAPE.
+-- `assertSchedule` in `src/server/validate.ts` is the only gate in front of it,
+-- and the evaluator is deliberately tolerant of a row that got past it — a
+-- malformed window covers NOTHING rather than everything, so the failure mode
+-- of a bad blob is a promotion that does not fire, never a cart priced at zero.
+--
+-- Shape, for a reader with only the database in front of them:
+--
+--   {"windows":[{"days":[4],"from":"16:00","to":"20:00"}]}
+--
+--   * `days`  — Monday-first, 0..6. NOT `Date#getDay()`'s Sunday-first axis.
+--   * `from`/`to` — "HH:MM", 24-hour, in the STORE's timezone, half-open
+--     [from, to) exactly as [starts_at, ends_at) is.
+--   * `to` < `from` means the window runs past midnight (a bar shutting at
+--     02:00), which is the most common happy hour there is.
+
+ALTER TABLE "discounts" ADD COLUMN IF NOT EXISTS "schedule" JSONB;

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.",

package/src/engine/schedule.ts

@@ -0,0 +1,191 @@
+/**
+ * The WEEKLY schedule inside a discount's campaign window (FUT-996).
+ *
+ * `startsAt`/`endsAt` answer "for how long is this campaign on?". This answers
+ * the second question a merchant actually asks — "and within that, on which
+ * days and at what hours?" — so that "toda sexta, das 16:00 às 20:00" and
+ * "segunda e terça à tarde" are expressible at all.
+ *
+ * Pure and clock-free, like the rest of the engine: it never calls `new Date()`
+ * and never touches `Intl`. A recurring window is a WALL-CLOCK fact and is
+ * therefore only meaningful in the store's own timezone — but resolving an
+ * IANA zone is the HOST's job, because this module runs in an offline tool
+ * generator, a browser bundle and a worker, and none of them may depend on a
+ * timezone database. The host resolves an instant into a {@link LocalClock} and
+ * passes it in; everything here is integer arithmetic over that.
+ *
+ * A rule with no schedule is every rule that exists today, and answers `true`
+ * unconditionally — which is what makes this a strictly additive change.
+ */
+
+/** Monday-first, matching the seven-entry week every hours surface uses. */
+export const MAX_SCHEDULE_WINDOWS = 7;
+
+/**
+ * One "these days, these hours" row of a schedule.
+ *
+ * A LIST of these rather than one shared time range, because "sexta 16–20 e
+ * sábado 12–16" is one promotion to the merchant selling it and two rows here.
+ * Deliberately NOT a per-weekday hours table (the shape `openingHours` uses):
+ * that editor asks seven questions to answer one, and a promotion is a
+ * sentence, not a business week.
+ */
+export interface DiscountScheduleWindow {
+  /**
+   * Weekdays this window runs on, **Monday-first, 0..6**.
+   *
+   * Monday-first because that is what `WeekHours` and every hours screen in a
+   * host already uses; `Date#getDay()` is Sunday-first and the conversion is
+   * `(getDay() + 6) % 7`. Stated here because a schedule that is off by one day
+   * is a promotion that runs on the wrong day and looks like a pricing bug.
+   */
+  days: readonly number[];
+  /** `HH:MM`, 24-hour, in the STORE's timezone. Inclusive. */
+  from: string;
+  /** `HH:MM`, 24-hour, in the STORE's timezone. EXCLUSIVE. */
+  to: string;
+}
+
+/** A rule's weekly schedule. Null/absent = always, within the campaign window. */
+export interface DiscountSchedule {
+  windows: readonly DiscountScheduleWindow[];
+}
+
+/**
+ * An instant already resolved into the store's own wall clock.
+ *
+ * Two integers rather than a `Date`, so this module cannot be tempted to read a
+ * timezone: by the time a value reaches here the only question left is
+ * arithmetic. The host builds it once per line and once per evaluation.
+ */
+export interface LocalClock {
+  /** Monday-first, 0..6 — the same axis as {@link DiscountScheduleWindow.days}. */
+  weekday: number;
+  /** Minutes since local midnight, 0..1439. */
+  minutes: number;
+}
+
+/** `HH:MM` → minutes since midnight, or null when it is not a time at all. */
+export function toMinutes(value: string): number | null {
+  const match = /^(\d{2}):(\d{2})$/.exec(value);
+  if (match === null) return null;
+  const hours = Number(match[1]);
+  const minutes = Number(match[2]);
+  if (hours > 23 || minutes > 59) return null;
+  return hours * 60 + minutes;
+}
+
+/** The weekday before this one, on the Monday-first axis. */
+function previousWeekday(weekday: number): number {
+  return (weekday + 6) % 7;
+}
+
+/**
+ * Whether one window is running at `clock`.
+ *
+ * A `to` EARLIER than `from` is a bar that shuts at 02:00, not a typo — the
+ * window runs past midnight into the next day, exactly as `minutesOpen` reads a
+ * store's opening hours. Treating it as invalid would refuse the single most
+ * common shape of a happy hour.
+ *
+ * So an overnight window is two intervals: `[from, 24:00)` on each of its own
+ * days, and `[00:00, to)` on the day AFTER each of them — which is why the
+ * second test asks about `previousWeekday`. A Saturday 00:30 instant is inside
+ * a Friday 22:00–02:00 window, and no amount of testing Saturday against
+ * `days` would ever discover that.
+ *
+ * Half-open `[from, to)`, matching `[startsAt, endsAt)`: a window ending at
+ * 20:00 is over the instant 20:00 begins.
+ */
+function windowCovers(window: DiscountScheduleWindow, clock: LocalClock): boolean {
+  const from = toMinutes(window.from);
+  const to = toMinutes(window.to);
+  // A malformed or empty window covers NOTHING rather than everything: it can
+  // only arrive by bypassing the validator, and the safe reading of "I cannot
+  // tell what this means" is not "charge the discount".
+  if (from === null || to === null || from === to) return false;
+  const days = new Set(window.days);
+  if (to > from) {
+    return days.has(clock.weekday) && clock.minutes >= from && clock.minutes < to;
+  }
+  if (days.has(clock.weekday) && clock.minutes >= from) return true;
+  return days.has(previousWeekday(clock.weekday)) && clock.minutes < to;
+}
+
+/**
+ * Whether the schedule is running at `clock` — true if ANY window is.
+ *
+ * `null` schedule → always true, which is every rule that predates this
+ * feature. A schedule with no windows is a rule an operator half-built; it
+ * covers nothing, and the validator refuses to save one.
+ *
+ * `clock` of `null` → **true**, and this is the load-bearing failure
+ * direction. It means the host could not resolve a timezone, and the same
+ * unknown makes `inStoreZone` fall back to the caller's clock rather than throw
+ * ("an unknown zone must not take the storefront down — nor refuse a payment")
+ * and `readStoreHours` keep a store selling. Failing the other way would
+ * silently switch off every scheduled promotion in a store on one bad timezone
+ * string — with nothing red anywhere, because a promotion that does not fire
+ * looks exactly like a promotion nobody qualified for.
+ */
+export function scheduleCovers(
+  schedule: DiscountSchedule | null | undefined,
+  clock: LocalClock | null | undefined,
+): boolean {
+  if (schedule === null || schedule === undefined) return true;
+  if (clock === null || clock === undefined) return true;
+  return schedule.windows.some((window) => windowCovers(window, clock));
+}
+
+/**
+ * Whether a schedule is one this engine can act on at all.
+ *
+ * Used by the validator and by hosts reading a stored blob back; the evaluator
+ * itself is deliberately tolerant (see `windowCovers`) because refusing to
+ * price a cart is never the right answer to a bad row.
+ */
+export function isUsableSchedule(schedule: DiscountSchedule): boolean {
+  if (schedule.windows.length === 0) return false;
+  if (schedule.windows.length > MAX_SCHEDULE_WINDOWS) return false;
+  return schedule.windows.every(
+    (window) =>
+      window.days.length > 0 &&
+      window.days.every((day) => Number.isInteger(day) && day >= 0 && day <= 6) &&
+      toMinutes(window.from) !== null &&
+      toMinutes(window.to) !== null &&
+      window.from !== window.to,
+  );
+}
+
+/**
+ * The next window that OPENS later today, or null — the teaser's whole input
+ * (FUT-996).
+ *
+ * "Later today" and not "next Friday": a card promising an offer six days out
+ * is noise on a screen the shopper is reading now, and it advertises a price
+ * they cannot have for almost a week. Scoped to the current weekday, the label
+ * is a reason to wait rather than a reason to leave.
+ *
+ * A window already running returns nothing from here — that is the BADGE's job,
+ * and a card must never carry both. The two are mutually exclusive by
+ * construction because this only looks at windows whose `from` is still ahead
+ * on the clock.
+ *
+ * Ties break on the earliest opening, so a card teases the offer that arrives
+ * soonest rather than whichever row the operator happened to add first.
+ */
+export function nextWindowToday(
+  schedule: DiscountSchedule | null | undefined,
+  clock: LocalClock | null | undefined,
+): DiscountScheduleWindow | null {
+  if (schedule === null || schedule === undefined) return null;
+  if (clock === null || clock === undefined) return null;
+  const upcoming = schedule.windows
+    .filter((window) => {
+      const from = toMinutes(window.from);
+      if (from === null || from <= clock.minutes) return false;
+      return window.days.includes(clock.weekday);
+    })
+    .sort((a, b) => (toMinutes(a.from) ?? 0) - (toMinutes(b.from) ?? 0));
+  return upcoming[0] ?? null;
+}