@12-apps/discounts 1.0.0

package/src/engine/preview.ts

@@ -0,0 +1,164 @@
+import { maxDiscountableCents, rawAmountCents } from "./allocate";
+import { buildLineIndex, coveredLineIds, screenRule } from "./eligibility";
+import { compareRuleOrder } from "./evaluate-passes";
+import type { DiscountCartLine, DiscountRule } from "./types";
+
+/**
+ * Menu-badge preview (FUT-246): what a single item's price looks like BEFORE
+ * there is a cart, so the storefront can strike the old price through on the
+ * catalog card. It reuses R2/R3/R5 from the evaluator rather than re-deriving
+ * them — one pricing rule, one implementation.
+ *
+ * A badge is a PROMISE, so this deliberately considers far less than a real
+ * evaluation does:
+ * - `AUTOMATIC` only — a coupon price the buyer has not typed yet is not this
+ *   item's price;
+ * - `ORDER` scope is excluded — an order-wide promo is not an item price and
+ *   would badge the whole menu;
+ * - 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
+ *   promotions end up combining is a cart-level question (R8) that cannot be
+ *   answered from a menu card.
+ *
+ * The R9 payable floor applies here too: the badged price is capped so it never
+ * drops below `MIN_PAYABLE_TOTAL_CENTS`, exactly as the evaluator caps a cart.
+ * A card advertising a zero price would be promising a free item the checkout
+ * is structurally unable to deliver — the provider rejects a zero charge — so a
+ * 100%-off item badges at one cent, and an item already priced at one cent
+ * badges nothing at all. Both surfaces read the floor from the same
+ * `maxDiscountableCents` in `./allocate.ts`, which is what keeps the card, the
+ * product sheet and the cart quoting the same number.
+ *
+ * `perBuyerLimit` is the ONE place that promise is knowingly weaker, and it is
+ * documented here rather than quietly inconsistent. The screen itself DOES
+ * honour the cap — `screenRule` rejects `BUYER_LIMIT_REACHED` — but only
+ * against the `buyerUsageCount` the caller resolved — and a catalog badge is
+ * typically an ANONYMOUS read, where a host has no buyer to count against and
+ * passes 0. A buyer who has already exhausted a once-per-buyer promotion
+ * therefore still sees its badge.
+ *
+ * Two alternatives were weighed and rejected:
+ *
+ * 1. drop every per-buyer-capped rule from the badge, the way
+ *    `minSubtotalCents` is dropped. That would hide a first-purchase promotion
+ *    from precisely the first-time buyers it exists for — wrong for the
+ *    overwhelming majority to protect a minority from a mild disappointment;
+ * 2. resolve the buyer on these reads. A product sheet often could, but a
+ *    catalog listing is deliberately unauthenticated — and a buyer-aware sheet
+ *    over an anonymous card reintroduces the card/sheet price disagreement
+ *    FUT-246 was filed about, one screen further in.
+ *
+ * So the badge stays optimistic and the CART tells the truth: the evaluator
+ * screens the same rule against a real `buyerUsageCount` and reports
+ * `BUYER_LIMIT_REACHED`, before a single cent is charged.
+ *
+ * Pure, like the rest of the engine: `now` is injected and the rules arrive
+ * pre-loaded once per catalog request, never per product.
+ */
+
+export interface ItemDiscountPreviewInput {
+  /** 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 price the card would otherwise show, in integer cents. */
+  priceCents: number;
+  /** 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;
+}
+
+/** What a host needs to render the badge: the struck price and its label. */
+export interface ItemDiscountPreview {
+  /**
+   * The price to show, in integer cents. Always strictly below `priceCents` and
+   * never below `MIN_PAYABLE_TOTAL_CENTS` — a card may not advertise zero.
+   */
+  discountedPriceCents: number;
+  /**
+   * What to name the promotion on the ribbon: the merchant's own discount name,
+   * which is already copy they wrote, in their own language. The `-NN%` badge is
+   * derived downstream from the two prices, so no money is formatted here.
+   */
+  promoLabel: string;
+}
+
+/** The synthetic one-line cart the preview screens against. */
+const PREVIEW_LINE_ID = "preview";
+
+function isBadgeable(rule: DiscountRule): boolean {
+  return (
+    rule.trigger === "AUTOMATIC" && rule.scope !== "ORDER" && rule.minSubtotalCents === null
+  );
+}
+
+function toPreviewLine(input: ItemDiscountPreviewInput): DiscountCartLine {
+  return {
+    lineId: PREVIEW_LINE_ID,
+    menuItemId: input.menuItemId,
+    variationMenuItemId: input.variationMenuItemId ?? null,
+    categoryPath: input.categoryPath,
+    quantity: 1,
+    unitPriceCents: input.priceCents,
+  };
+}
+
+/**
+ * The best badge for this item: the biggest saving, ties broken by the same
+ * canonical rule order the evaluator uses, so the card and the cart never
+ * disagree about which of two competing promotions is "the" one.
+ *
+ * Amounts are capped by R9 BEFORE they are ranked, so the winner is the one that
+ * really takes the most off the badged price — the same reason the evaluator's
+ * R8 compares post-clamp outcomes. A rule left with nothing to remove falls out
+ * on the `> 0` filter and is simply not badged.
+ */
+function bestBadgeRule(
+  input: ItemDiscountPreviewInput,
+  line: DiscountCartLine,
+): { rule: DiscountRule; amountCents: number } | null {
+  const index = buildLineIndex([line]);
+  const scored = input.rules
+    .filter(isBadgeable)
+    .filter(
+      (rule) =>
+        screenRule(rule, {
+          now: input.now,
+          subtotalCents: input.priceCents,
+          hasEligibleItems: coveredLineIds(rule, [line], index).has(PREVIEW_LINE_ID),
+        }) === null,
+    )
+    .map((rule) => ({
+      rule,
+      amountCents: Math.min(
+        rawAmountCents(rule, input.priceCents),
+        maxDiscountableCents(input.priceCents),
+      ),
+    }))
+    .filter((entry) => entry.amountCents > 0);
+  scored.sort((a, b) => {
+    const byAmount = b.amountCents - a.amountCents;
+    return byAmount !== 0 ? byAmount : compareRuleOrder(a.rule, b.rule);
+  });
+  return scored[0] ?? null;
+}
+
+/**
+ * The discounted price to badge this menu item with, or null when no automatic
+ * item-or-category promotion currently removes a whole cent from it — a
+ * "-0%" badge is worse than no badge at all.
+ */
+export function previewItemDiscount(
+  input: ItemDiscountPreviewInput,
+): ItemDiscountPreview | null {
+  const best = bestBadgeRule(input, toPreviewLine(input));
+  if (best === null) return null;
+  return {
+    discountedPriceCents: input.priceCents - best.amountCents,
+    promoLabel: best.rule.name,
+  };
+}

package/src/engine/pt-BR.ts

@@ -0,0 +1,26 @@
+import { MIN_SUBTOTAL_TOKEN, type DiscountRejectionCopy } from "./rejection-copy";
+
+/**
+ * The pt-BR pack — a NAMED export a host passes by hand
+ * (`rejectionCopy: PT_BR_DISCOUNT_REJECTION_COPY`), never a default. The
+ * filename is what exempts this file from the copy-portability gate:
+ * Portuguese may ship, it may not be silent.
+ *
+ * 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.
+ */
+export const PT_BR_DISCOUNT_REJECTION_COPY: DiscountRejectionCopy = {
+  UNKNOWN_CODE: "Cupom inválido ou expirado.",
+  INACTIVE: "Cupom inválido ou expirado.",
+  NOT_STARTED: "Cupom inválido ou expirado.",
+  EXPIRED: "Cupom inválido ou expirado.",
+  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.",
+  NO_ELIGIBLE_ITEMS: "Este cupom não vale para os itens do seu carrinho.",
+  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.",
+  minSubtotalUnknown: "Este cupom exige um valor mínimo de pedido.",
+};

package/src/engine/rejection-copy.ts

@@ -0,0 +1,69 @@
+import { DISCOUNT_REJECTION_REASONS, type DiscountRejectionReason } from "./kinds";
+import type { DiscountRejection } from "./types";
+
+/**
+ * The sentence a buyer is shown when a discount they asked for did not stick
+ * (FUT-235) — required HOST config, with NO defaults.
+ *
+ * The evaluator's reasons are machine-readable and stay the package's own; the
+ * SENTENCE is the host's, because it is the only part a user reads. A default
+ * in the origin host's language reads as finished to the next host right up
+ * until someone sees it, which is the rule the copy-portability gate enforces
+ * repo-wide. A pt-BR host imports {@link PT_BR_DISCOUNT_REJECTION_COPY} from
+ * `@12-apps/discounts/pt-BR` and passes it by hand — one reviewable line.
+ *
+ * Hosts are encouraged to make the copy COARSER than the reasons. A coupon
+ * that is switched off, has not started yet or is over can honestly read the
+ * same to the buyer: the distinction only leaks how the merchant schedules
+ * their promotions, and there is nothing the buyer could do differently.
+ */
+export type DiscountRejectionCopy = Readonly<
+  Record<DiscountRejectionReason, string>
+> & {
+  /**
+   * Said when `MIN_SUBTOTAL_NOT_MET` arrives WITHOUT its threshold — never
+   * show the raw token to a buyer.
+   */
+  readonly minSubtotalUnknown: string;
+};
+
+/**
+ * The placeholder {@link DiscountRejectionCopy.MIN_SUBTOTAL_NOT_MET} may carry,
+ * replaced with the formatted threshold. A sentence that omits it is left
+ * alone, so a host that would rather not quote the number simply does not
+ * write the token.
+ */
+export const MIN_SUBTOTAL_TOKEN = "{minimum}";
+
+const COPY_KEYS: readonly (keyof DiscountRejectionCopy)[] = [
+  ...DISCOUNT_REJECTION_REASONS,
+  "minSubtotalUnknown",
+];
+
+/**
+ * Every key present and non-blank — the assembly-time check, so a host that
+ * forgot a reason learns at wiring rather than from a buyer staring at
+ * `undefined`.
+ */
+export function missingRejectionCopy(copy: DiscountRejectionCopy | undefined): string[] {
+  if (copy === undefined) return [...COPY_KEYS];
+  return COPY_KEYS.filter((key) => typeof copy[key] !== "string" || copy[key].trim() === "");
+}
+
+/**
+ * The message for one rejection, with the minimum-subtotal threshold filled in
+ * when the reason carries one and the host's sentence asks for it.
+ *
+ * `formatCents` is INJECTED rather than imported: money formatting is a
+ * locale and currency decision, and this package has neither.
+ */
+export function discountRejectionMessage(
+  rejection: DiscountRejection,
+  copy: DiscountRejectionCopy,
+  formatCents: (cents: number) => string,
+): string {
+  const template = copy[rejection.reason];
+  if (!template.includes(MIN_SUBTOTAL_TOKEN)) return template;
+  if (rejection.minSubtotalCents === undefined) return copy.minSubtotalUnknown;
+  return template.replace(MIN_SUBTOTAL_TOKEN, formatCents(rejection.minSubtotalCents));
+}

package/src/engine/types.ts

@@ -0,0 +1,147 @@
+import type {
+  DiscountRejectionReason,
+  DiscountScope,
+  DiscountTrigger,
+  DiscountType,
+} from "./kinds";
+
+/**
+ * The evaluator's type contract (FUT-245). Types only, no logic — the shape
+ * `./evaluate.ts` and whatever loads a host's rows agree on.
+ */
+
+/**
+ * One discount as the evaluator sees it: a plain value object with every
+ * stored and every counted fact already resolved. The evaluator never touches
+ * a database and never reads the clock — the host's loader builds these from
+ * its own rows, and `now` is injected.
+ */
+export interface DiscountRule {
+  id: string;
+  name: string;
+  type: DiscountType;
+  /** 1..10000 basis points. Non-null iff `type === "PERCENTAGE"`. */
+  percentOffBp: number | null;
+  /** Cents off, > 0. Non-null iff `type === "FIXED_AMOUNT"`. */
+  amountOffCents: number | null;
+  scope: DiscountScope;
+  /** Target category ids. Non-empty iff `scope === "CATEGORY"`. */
+  targetCategoryIds: readonly string[];
+  /** Target menu-item ids. Non-empty iff `scope === "ITEM"`. */
+  targetMenuItemIds: readonly string[];
+  trigger: DiscountTrigger;
+  /** Normalized (trimmed, upper-cased) code. Non-null iff `trigger === "CODE"`. */
+  code: string | null;
+  active: boolean;
+  /** Inclusive lower bound of the active window; null = already open. */
+  startsAt: Date | null;
+  /** EXCLUSIVE upper bound of the active window; null = never closes. */
+  endsAt: Date | null;
+  /** Minimum PRE-discount subtotal in cents; null = no threshold. */
+  minSubtotalCents: number | null;
+  /** Global redemption cap; null = uncapped. */
+  usageLimit: number | null;
+  /** Redemptions already counted globally. */
+  usageCount: number;
+  /** Per-buyer redemption cap; null = uncapped. */
+  perBuyerLimit: number | null;
+  /** Redemptions this buyer has already PAID for. 0 for an anonymous cart. */
+  buyerUsageCount: number;
+  /** False ⇒ exclusive: if it wins, nothing else applies. */
+  stackable: boolean;
+  /** Deterministic tie-break key, ascending. */
+  createdAt: Date;
+}
+
+/**
+ * One cart line, priced exactly as the host prices it: `unitPriceCents`
+ * already includes the chosen variation and every paid extra, so the
+ * evaluator never re-derives money.
+ */
+export interface DiscountCartLine {
+  /** Cart-line id (or order-line index) — the allocation key. */
+  lineId: string;
+  /** The BASE (grouping) menu-item id — the card the admin picked as a target. */
+  menuItemId: string;
+  /** The chosen variation's menu-item id, when the line has one. */
+  variationMenuItemId: string | null;
+  /**
+   * The line's own category id followed by its ancestors, nearest first, so a
+   * discount on a top-level category also covers its subcategories' items.
+   * Empty for an uncategorized item.
+   */
+  categoryPath: readonly string[];
+  quantity: number;
+  /** Composed unit price in integer cents. */
+  unitPriceCents: number;
+}
+
+export interface DiscountEvaluationInput {
+  lines: readonly DiscountCartLine[];
+  /** Every non-archived discount of the tenant; the evaluator screens them. */
+  rules: readonly DiscountRule[];
+  /** Raw code as the buyer typed it, or null. Normalized internally. */
+  couponCode: string | null;
+  /** Evaluation instant. Injected — the evaluator never calls `new Date()`. */
+  now: Date;
+}
+
+/** Why a discount the buyer asked for was not applied. */
+export interface DiscountRejection {
+  /** Null only for `UNKNOWN_CODE`, where no rule matched. */
+  discountId: string | null;
+  /** The code involved, when the rejection concerns one. */
+  code: string | null;
+  reason: DiscountRejectionReason;
+  /** Present on `MIN_SUBTOTAL_NOT_MET`: the threshold, in cents. */
+  minSubtotalCents?: number;
+  /** Present on `NOT_STACKABLE`: the discount that displaced this one. */
+  supersededByDiscountId?: string;
+}
+
+/** A discount that actually removed money, frozen for the order snapshot. */
+export interface AppliedDiscount {
+  discountId: string;
+  name: string;
+  code: string | null;
+  type: DiscountType;
+  scope: DiscountScope;
+  percentOffBp: number | null;
+  amountOffCents: number | null;
+  /** Cents removed from the order by THIS discount. Always > 0. */
+  amountCents: number;
+}
+
+/** Per-line outcome. `Σ discountCents` equals the order's `discountTotalCents`. */
+export interface DiscountLineAdjustment {
+  lineId: string;
+  /** `unitPriceCents * quantity`, before any discount. */
+  lineGrossCents: number;
+  /** Cents removed from this line across every applied discount. */
+  discountCents: number;
+  /** `lineGrossCents - discountCents`. Never negative. */
+  lineNetCents: number;
+}
+
+export interface DiscountEvaluation {
+  /** Σ lineGrossCents. */
+  subtotalCents: number;
+  /**
+   * Σ applied[].amountCents, bounded by R9's payable floor:
+   * `0 <= discountTotalCents <= max(0, subtotalCents - MIN_PAYABLE_TOTAL_CENTS)`.
+   */
+  discountTotalCents: number;
+  /**
+   * `subtotalCents - discountTotalCents`. Never negative, never above
+   * `subtotalCents`, and — whenever anything was discounted at all — never below
+   * `MIN_PAYABLE_TOTAL_CENTS`, because the provider cannot be asked to raise a
+   * R$ 0,00 charge. See the R9 block in `./evaluate.ts`: this deliberately
+   * departs from the FUT-235 spec, which called for landing on exactly zero.
+   */
+  totalCents: number;
+  applied: readonly AppliedDiscount[];
+  /** One entry per input line, in input order. */
+  lines: readonly DiscountLineAdjustment[];
+  /** Only for discounts the buyer explicitly invoked or that lost a stack race. */
+  rejections: readonly DiscountRejection[];
+}

package/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * `@12-apps/discounts` — the discount/promotion domain, host-agnostic.
+ *
+ * The root entry is the ENGINE: given a priced cart, a tenant's rules and an
+ * instant, decide which promotions apply, how many cents each removes, and
+ * how those cents land on the individual lines. It reaches no database, no
+ * clock, no framework and no locale — `now` is injected, the rules arrive
+ * pre-loaded, and every user-facing sentence is host config
+ * (`./rejection-copy`, with a pt-BR pack at `@12-apps/discounts/pt-BR`).
+ *
+ * The admin CRUD surface lives behind `@12-apps/discounts/server`, so a
+ * browser bundle that only prices a cart never resolves it. The wiring
+ * manifests are at `@12-apps/discounts/manifest` and `./manifest/server`.
+ *
+ * The DATABASE is deliberately NOT here, and the manifest declares no `db`
+ * capability. A discount's rows relate to a host's own catalog and orders —
+ * targets point at categories and items, redemptions at orders and buyers —
+ * so a shipped Prisma partial would only compile inside a host that already
+ * has those tables under those names. What is portable is the RULE, not the
+ * storage: the host owns the schema and hands this package rows through the
+ * `DiscountStore` port and the `DiscountRule` value object.
+ */
+
+export {
+  DISCOUNT_REJECTION_REASONS,
+  DISCOUNT_SCOPES,
+  DISCOUNT_TRIGGERS,
+  DISCOUNT_TYPES,
+  MAX_PERCENT_OFF_BP,
+  MIN_PAYABLE_TOTAL_CENTS,
+  normalizeDiscountCode,
+  type DiscountRejectionReason,
+  type DiscountScope,
+  type DiscountTrigger,
+  type DiscountType,
+} from "./engine/kinds";
+
+export type {
+  AppliedDiscount,
+  DiscountCartLine,
+  DiscountEvaluation,
+  DiscountEvaluationInput,
+  DiscountLineAdjustment,
+  DiscountRejection,
+  DiscountRule,
+} from "./engine/types";
+
+export { evaluateDiscounts } from "./engine/evaluate";
+
+export {
+  previewItemDiscount,
+  type ItemDiscountPreview,
+  type ItemDiscountPreviewInput,
+} from "./engine/preview";
+
+export {
+  discountRejectionMessage,
+  missingRejectionCopy,
+  MIN_SUBTOTAL_TOKEN,
+  type DiscountRejectionCopy,
+} from "./engine/rejection-copy";
+
+/**
+ * The allocation primitives, exported because the badge preview and any host
+ * that quotes a discounted price outside a cart must read the payable floor
+ * from the SAME place the evaluator caps against — a second implementation is
+ * how a card and a cart start quoting different numbers.
+ */
+export { maxDiscountableCents, rawAmountCents } from "./engine/allocate";

package/src/manifest/index.ts

@@ -0,0 +1,52 @@
+/**
+ * `@12-apps/discounts/manifest` — the SHARED wiring manifest.
+ *
+ * Data every runtime can hold: identity, the permission contribution, the MCP
+ * tools, and the INVENTORY of the runtime manifest (`./manifest/server`). A
+ * host adopts this through `@12-apps/wiring/consumer`, and the inventory is
+ * what makes an unanswered capability a red `assemble()` instead of a silent
+ * gap.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency here, on purpose: the
+ * manifests are plain values `satisfies`-checked against the contract, and the
+ * producer factories' assertions run in this package's own test suite
+ * (`__tests__/manifest.test.ts`) — the same "fails in the package's own test
+ * run" guarantee with zero runtime dependencies added.
+ *
+ * ## Two capabilities this package deliberately does NOT declare
+ *
+ * **`db`.** A discount's rows relate to a host's own catalog and orders:
+ * targets point at its categories and items, redemptions at its orders and
+ * buyers. A `composed` partial may in principle relate to host models, but one
+ * shipped from here would only compile inside a host that already has those
+ * tables under those names — and `isolated` is ruled out by the same
+ * relations, which is exactly the qualification the wiring db contract states
+ * ("a package qualifies only when its models carry no relation into host
+ * tables"). What is portable is the RULE, not the storage: the host owns the
+ * schema and answers `DiscountStore`.
+ *
+ * **`web`.** The admin grid, the form and the target pickers stay host
+ * surfaces for now. They are three quarters product copy and host design
+ * system, and a surface declared before its copy is host config is the exact
+ * anti-pattern the copy-portability gate exists to refuse. The permission ids
+ * and the tool schemas are enough for a host to build them against.
+ */
+
+import type { PackageManifest } from "@12-apps/wiring";
+
+import { DISCOUNTS_PERMISSIONS } from "../server/contribution";
+import { DISCOUNTS_MCP_TOOLS } from "../server/mcp";
+
+export const discountsManifest = {
+  name: "@12-apps/discounts",
+  contract: 1,
+  permissions: DISCOUNTS_PERMISSIONS,
+  mcp: { endpoints: DISCOUNTS_MCP_TOOLS },
+  /**
+   * The server half logs through the binder's namespaced logger, so a
+   * discounts failure files under `discounts` rather than under the host app
+   * or nowhere.
+   */
+  observability: { namespace: "discounts" },
+  server: ["http"],
+} as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -0,0 +1,23 @@
+/**
+ * `@12-apps/discounts/manifest/server` — the server capabilities.
+ *
+ * One contribution: `http`, whose `create` IS {@link createApiDiscounts},
+ * unchanged. The descriptors it returns already satisfy the wiring contract's
+ * `WireRoute` — including the POLICY half, so a host's coverage gates can read
+ * each route's required permission off the assembled table instead of
+ * scanning route files for a guard literal.
+ *
+ * Behind its own subpath so a web bundle importing the shared manifest never
+ * resolves the server half. A plain `satisfies`-checked value — see `./index`
+ * for why the contract package stays a type-only devDependency; the inventory
+ * check against the shared manifest runs in the test suite.
+ */
+
+import type { AnyServerManifest } from "@12-apps/wiring";
+
+import { createApiDiscounts } from "../server/routes";
+
+export const discountsServerManifest = {
+  name: "@12-apps/discounts",
+  http: { create: createApiDiscounts },
+} as const satisfies AnyServerManifest;

package/src/server/contribution.ts

@@ -0,0 +1,42 @@
+import type { WirePermissionsContribution } from "@12-apps/wiring";
+
+/**
+ * THIS PACKAGE'S OWN PERMISSION CONTRIBUTION.
+ *
+ * The discounts surface decides two privileges, so it declares them rather
+ * than leaving each host to spell them: seeing which promotions are running,
+ * and changing what the store charges. They are SEPARATE on purpose (FUT-235)
+ * — "show me the promos" is a reasonable thing to grant a floor manager, and
+ * it is not the same act as repricing the menu — and neither is folded into a
+ * catalog permission, because a discount is not catalog content.
+ *
+ * There is deliberately no `discounts:approve`. A discount is a pricing rule
+ * carrying a LIVE redemption counter, not versioned content: restoring
+ * "version 3" of a coupon whose `usageCount` has since moved is meaningless,
+ * so there is no approval branch and therefore no author-cannot-approve pair
+ * to declare.
+ *
+ * The shape is `@12-apps/rbac`'s `PermissionContribution`, taken from the
+ * wiring contract's type-only twin rather than by depending on rbac: a host
+ * may run any RBAC, or none, and the contribution is plain data, so
+ * `composePermissions(DISCOUNTS_PERMISSIONS, …)` accepts it structurally.
+ *
+ * The LABELS are absent, and that is the same rule as the copy ports: a label
+ * is a word in a language, and the segment vocabularies a host composes are
+ * its own. A host that shows a permission picker supplies them there.
+ */
+export const DISCOUNTS_PERMISSIONS = {
+  source: "@12-apps/discounts",
+  ids: ["discounts:read", "discounts:write"],
+  permissions: {
+    /** See the promotions list and read one — RBAC alone decides. */
+    "discounts:read": { kind: "class" },
+    /** Create, re-state or end a promotion — the repricing privilege. */
+    "discounts:write": { kind: "class" },
+  },
+} as const satisfies WirePermissionsContribution;
+
+/** The read privilege's id, so a host maps a token rather than a string. */
+export const DISCOUNTS_READ = "discounts:read";
+/** The write privilege's id. */
+export const DISCOUNTS_WRITE = "discounts:write";

package/src/server/copy.ts

@@ -0,0 +1,64 @@
+/**
+ * Every string the discounts API surface answers a HUMAN with — required host
+ * config, with NO defaults, deliberately (the payments extraction's doctrine,
+ * enforced repo-wide by the copy-portability gate): a default in the origin
+ * host's language reads as finished to the next host right up until a user
+ * sees it. The machine-readable halves of a failure — the status, and the
+ * FIELD the operator must fix — stay the package's own; only the sentence is
+ * the host's.
+ *
+ * A pt-BR host imports {@link PT_BR_DISCOUNTS_SERVER_COPY} from
+ * `@12-apps/discounts/server/pt-BR` and passes it by hand — one reviewable
+ * line, never a silence.
+ *
+ * The keys are named after the RULE, not the field, because several rules
+ * report against the same form input (`targets` covers both scopes) and one
+ * rule reports against two (`invalidDate` is raised for either bound).
+ */
+export interface DiscountsServerCopy {
+  /** 400 — the list query did not parse (unknown sort field, bad page). */
+  readonly invalidQuery: string;
+  /** 404 — the id names no live discount of this tenant. */
+  readonly notFound: string;
+  /** 422 — a PERCENTAGE discount without a rate in `1..MAX_PERCENT_OFF_BP`. */
+  readonly invalidPercent: string;
+  /** 422 — a FIXED_AMOUNT discount without a positive amount in cents. */
+  readonly invalidAmount: string;
+  /** 422 — a CODE-triggered discount with no coupon code to type. */
+  readonly codeRequired: string;
+  /** 422 — a CATEGORY-scoped discount targeting no category. */
+  readonly categoryTargetRequired: string;
+  /** 422 — an ITEM-scoped discount targeting no item. */
+  readonly itemTargetRequired: string;
+  /** 422 — a window bound that is not a calendar date. */
+  readonly invalidDate: string;
+  /** 422 — the window closes at or before it opens, so it is never open. */
+  readonly endsBeforeStarts: string;
+  /** 422 — a minimum-basket threshold of zero or less. */
+  readonly invalidMinSubtotal: string;
+  /** 422 — a global redemption cap of zero or less. */
+  readonly invalidUsageLimit: string;
+  /** 422 — a per-buyer redemption cap of zero or less. */
+  readonly invalidPerBuyerLimit: string;
+}
+
+const COPY_KEYS: readonly (keyof DiscountsServerCopy)[] = [
+  "invalidQuery",
+  "notFound",
+  "invalidPercent",
+  "invalidAmount",
+  "codeRequired",
+  "categoryTargetRequired",
+  "itemTargetRequired",
+  "invalidDate",
+  "endsBeforeStarts",
+  "invalidMinSubtotal",
+  "invalidUsageLimit",
+  "invalidPerBuyerLimit",
+];
+
+/** Every key present and non-blank — checked at assembly, like the rest. */
+export function missingServerCopy(copy: DiscountsServerCopy | undefined): string[] {
+  if (copy === undefined) return [...COPY_KEYS];
+  return COPY_KEYS.filter((key) => typeof copy[key] !== "string" || copy[key].trim() === "");
+}