@12-apps/discounts 1.0.0 → 1.2.0

package/src/engine/types.ts

@@ -10,6 +10,38 @@ import type {
  * `./evaluate.ts` and whatever loads a host's rows agree on.
  */
 
+/**
+ * One SLOT of a combo: what may fill it, and how many units it needs for ONE
+ * application of the combo.
+ *
+ * "1 large popcorn + 2 sodas" is two slots — `{ menuItemIds: ["popcorn-lg"],
+ * quantity: 1 }` and `{ categoryIds: ["sodas"], quantity: 2 }`. "3 burgers for
+ * the price of 2" is ONE slot of quantity 3, whose rule carries
+ * `type: "FREE_UNITS"`, `freeUnits: 1`.
+ *
+ * A slot is satisfied from either list — an item id OR a category — because a
+ * merchant thinks in both at once ("a soda" is a category, "the large popcorn"
+ * is an item). At least one of the two must be non-empty; a slot naming
+ * neither can never be filled, and `toDiscountScalars` refuses it rather than
+ * storing a combo that silently never fires.
+ */
+export interface ComboRequirement {
+  /**
+   * Menu-item ids that fill this slot, matched against a line's BASE item OR
+   * its chosen variation — the same reach an `ITEM`-scoped discount has, so
+   * "a Coke" still fills the slot when the buyer picked "Coke zero can".
+   */
+  menuItemIds: readonly string[];
+  /**
+   * Category ids that fill this slot, matched against a line's category PATH,
+   * so a slot naming a top-level category is filled by its subcategories' items
+   * — the same reach a `CATEGORY`-scoped discount has.
+   */
+  categoryIds: readonly string[];
+  /** Units this slot needs per application. An integer >= 1. */
+  quantity: number;
+}
+
 /**
  * One discount as the evaluator sees it: a plain value object with every
  * stored and every counted fact already resolved. The evaluator never touches
@@ -24,11 +56,42 @@ export interface DiscountRule {
   percentOffBp: number | null;
   /** Cents off, > 0. Non-null iff `type === "FIXED_AMOUNT"`. */
   amountOffCents: number | null;
+  /**
+   * What the matched combo group costs, in cents. Non-null iff
+   * `type === "BUNDLE_PRICE"`. The discount is the group's gross value minus
+   * this, per application.
+   */
+  bundlePriceCents?: number | null;
+  /**
+   * How many units of the matched group are free. Non-null iff
+   * `type === "FREE_UNITS"`. The CHEAPEST units of each application are the
+   * free ones, which is the buyer-favourable reading of "3 for the price of 2"
+   * and the one every merchant means by it.
+   */
+  freeUnits?: 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[];
+  /**
+   * The combo's slots, in the merchant's own declaration order. Non-empty iff
+   * `scope === "COMBO"`; ignored at every other scope.
+   *
+   * OPTIONAL, unlike the two target arrays above, and that asymmetry is the
+   * point: every discount has a scope and a type, so those fields are facts
+   * about all of them, while a combo is a CAPABILITY a host opts into. A host
+   * that does not sell combos never stores a `COMBO`-scoped rule, so it never
+   * has a value to put here, and requiring one would have made adding combos a
+   * breaking change for every adopter that does not want them.
+   */
+  comboRequirements?: readonly ComboRequirement[];
+  /**
+   * How many times this combo may apply to ONE cart; null or omitted means as
+   * often as the cart can fill its slots. A cart with six burgers takes "3 for
+   * the price of 2" twice unless this says otherwise.
+   */
+  maxComboApplications?: number | null;
   trigger: DiscountTrigger;
   /** Normalized (trimmed, upper-cased) code. Non-null iff `trigger === "CODE"`. */
   code: string | null;
@@ -110,6 +173,17 @@ export interface AppliedDiscount {
   amountOffCents: number | null;
   /** Cents removed from the order by THIS discount. Always > 0. */
   amountCents: number;
+  /**
+   * How many times a `COMBO`-scoped discount applied to this cart; absent for
+   * every other scope.
+   *
+   * It is on the SNAPSHOT rather than merely in the evaluation because it is
+   * the one combo fact an order cannot re-derive later: the rule's slots may
+   * have been re-stated, and the line quantities the combo consumed are not
+   * recoverable from the per-line cents alone. A receipt saying "Combo leve 3
+   * pague 2 (2x)" needs this number.
+   */
+  comboApplications?: number;
 }
 
 /** Per-line outcome. `Σ discountCents` equals the order's `discountTotalCents`. */

package/src/index.ts

@@ -12,6 +12,14 @@
  * browser bundle that only prices a cart never resolves it. The wiring
  * manifests are at `@12-apps/discounts/manifest` and `./manifest/server`.
  *
+ * COMBOS (FUT-268) live here too, as a SCOPE rather than as a catalog entity:
+ * a `COMBO`-scoped rule matches quantified slots against the cart's units and
+ * prices the group ("1 large popcorn + 2 sodas for R$ 25", "3 burgers for the
+ * price of 2"). What is NOT here — and cannot be, for the same reason the
+ * database is not — is a combo as a SELLABLE product: its own menu card, its
+ * own cart line, its own order snapshot. That is a host catalog entity with
+ * foreign keys into host tables. The pricing RULE travels; the product does not.
+ *
  * 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 —
@@ -22,10 +30,13 @@
  */
 
 export {
+  COMBO_ONLY_DISCOUNT_TYPES,
   DISCOUNT_REJECTION_REASONS,
   DISCOUNT_SCOPES,
   DISCOUNT_TRIGGERS,
   DISCOUNT_TYPES,
+  MAX_COMBO_SLOTS,
+  MAX_COMBO_SLOT_QUANTITY,
   MAX_PERCENT_OFF_BP,
   MIN_PAYABLE_TOTAL_CENTS,
   normalizeDiscountCode,
@@ -37,6 +48,7 @@ export {
 
 export type {
   AppliedDiscount,
+  ComboRequirement,
   DiscountCartLine,
   DiscountEvaluation,
   DiscountEvaluationInput,
@@ -53,6 +65,31 @@ export {
   type ItemDiscountPreviewInput,
 } from "./engine/preview";
 
+/**
+ * The COMBO half of the catalog surface (FUT-268). A combo has no single-item
+ * price to badge, so a card advertises PARTICIPATION instead — see
+ * `./engine/combo-offer.ts` for why that is the only honest thing a card can
+ * say about one.
+ */
+export {
+  comboOffersForItem,
+  type ComboOffer,
+  type ComboOffersInput,
+} from "./engine/combo-offer";
+
+/**
+ * The combo matcher, exported because a host that wants to EXPLAIN a combo —
+ * "aplicado 2x", "faltam 2 refrigerantes" — needs the same match the evaluator
+ * priced, and re-deriving it host-side is how a receipt and a cart start
+ * disagreeing about what was in the bundle.
+ */
+export {
+  freshComboPool,
+  matchCombo,
+  type ComboMatch,
+  type ComboPool,
+} from "./engine/combo-match";
+
 export {
   discountRejectionMessage,
   missingRejectionCopy,

package/src/manifest/index.ts

@@ -46,6 +46,13 @@ export const discountsManifest = {
    * 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.
+   *
+   * `createApiDiscounts` REFUSES to build without one, which is what makes
+   * that sentence a fact rather than an aspiration: for the whole of 1.0.x it
+   * was neither — the binder built the logger, hung it on
+   * `assembled.loggers["@12-apps/discounts"]`, and the package took nothing
+   * and logged nothing. A declared capability nobody consumes is worse than an
+   * undeclared one, because it reads as finished.
    */
   observability: { namespace: "discounts" },
   server: ["http"],

package/src/server/copy.ts

@@ -40,6 +40,22 @@ export interface DiscountsServerCopy {
   readonly invalidUsageLimit: string;
   /** 422 — a per-buyer redemption cap of zero or less. */
   readonly invalidPerBuyerLimit: string;
+  /** 422 — a BUNDLE_PRICE or FREE_UNITS reward on a discount that is not a combo. */
+  readonly comboScopeRequired: string;
+  /** 422 — a combo with no slots at all, or more than `MAX_COMBO_SLOTS`. */
+  readonly invalidComboSlots: string;
+  /** 422 — a combo slot naming neither a product nor a category. */
+  readonly comboTargetRequired: string;
+  /** 422 — a slot asking for zero units, or more than `MAX_COMBO_SLOT_QUANTITY`. */
+  readonly invalidComboQuantity: string;
+  /** 422 — a BUNDLE_PRICE combo without a positive price in cents. */
+  readonly invalidBundlePrice: string;
+  /** 422 — a FREE_UNITS combo without a positive count of free units. */
+  readonly invalidFreeUnits: string;
+  /** 422 — a combo giving away every unit it asks for, which sells nothing. */
+  readonly freeUnitsExceedCombo: string;
+  /** 422 — a per-cart combo cap of zero or less. */
+  readonly invalidMaxComboApplications: string;
 }
 
 const COPY_KEYS: readonly (keyof DiscountsServerCopy)[] = [
@@ -55,6 +71,14 @@ const COPY_KEYS: readonly (keyof DiscountsServerCopy)[] = [
   "invalidMinSubtotal",
   "invalidUsageLimit",
   "invalidPerBuyerLimit",
+  "comboScopeRequired",
+  "invalidComboSlots",
+  "comboTargetRequired",
+  "invalidComboQuantity",
+  "invalidBundlePrice",
+  "invalidFreeUnits",
+  "freeUnitsExceedCombo",
+  "invalidMaxComboApplications",
 ];
 
 /** Every key present and non-blank — checked at assembly, like the rest. */

package/src/server/index.ts

@@ -15,6 +15,8 @@ export {
 
 export { missingServerCopy, type DiscountsServerCopy } from "./copy";
 
+export { errorText, type DiscountsLogger } from "./logging";
+
 export {
   DISCOUNTS_PERMISSIONS,
   DISCOUNTS_READ,
@@ -40,9 +42,12 @@ export {
   type DiscountWriteInput,
 } from "./validate";
 
+export { comboRequirementsForScope, toComboColumns, type ComboColumns } from "./validate-combo";
+
 export { discountSearchConfig } from "./search";
 
 export {
+  comboRequirementSchema,
   createDiscountBody,
   createDiscountListQuery,
   discountCollectionParams,

package/src/server/logging.ts

@@ -0,0 +1,118 @@
+import type { WireRequest, WireResponse } from "@12-apps/wiring";
+
+import type { DiscountsActor } from "./routes";
+import { DiscountValidationError } from "./validate";
+
+/**
+ * What this surface says out loud, and to whom (FUT-244).
+ *
+ * The manifest declares `observability: { namespace: "discounts" }`, which is a
+ * PROMISE: a discounts failure files under `discounts` rather than under the
+ * host app or nowhere. Declaring it bought nothing on its own — the binder
+ * built the namespaced logger, hung it on `assembled.loggers`, and the package
+ * never took it, so for the whole of 1.0.x a refused write and a store that
+ * threw were equally silent. This module is the other half.
+ *
+ * ## Why every line is a STRING, and never an object
+ *
+ * A host's `LoggerPort` is a Winston child in practice, whose formatter runs
+ * `util.inspect(…, { depth: 5 })` over any extra argument. That is not a
+ * theoretical leak in this org: a provider error retains the provider's parsed
+ * response body, buyer name, e-mail and CPF included, so passing the cause as a
+ * second argument is precisely how a buyer's details reach a third party.
+ * {@link errorText} folds the cause into the sentence instead, which is the
+ * same call the origin host's own `errorText` makes and for the same reason.
+ *
+ * ## Why the sentences here are NOT copy config
+ *
+ * Everything below is written for a DEVELOPER reading a log, so it is English
+ * and it is the package's own — the copy-portability rule governs what a USER
+ * reads. Nothing logged here is shown to anyone; the operator's sentence comes
+ * from {@link DiscountsServerCopy} and travels in the response body.
+ */
+
+/**
+ * The three methods a host's logger must offer — the structural twin of
+ * `@12-apps/wiring`'s `LoggerPort` and of `createFeatureLogger`'s return.
+ *
+ * Declared here rather than imported so that the wiring contract stays a
+ * type-only devDependency: a host on no wiring at all still satisfies this by
+ * passing any Winston/pino child, and a host on wiring passes
+ * `assembled.loggers["@12-apps/discounts"]` unchanged.
+ */
+export interface DiscountsLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+
+/** The cause as a log line — never the object. See the module note. */
+export function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * What a line may name: the tenant, the route, the discount, the field, the
+ * status. Never a body, never a coupon code, never a name an operator typed —
+ * a log line is read by whoever can read the log, and none of those are needed
+ * to find the failure.
+ */
+function subject(route: string, request: WireRequest<DiscountsActor>): string {
+  const id = request.params.id;
+  return `${route}${id === undefined ? "" : ` [${id}]`} for tenant ${request.actor.clientId}`;
+}
+
+/**
+ * Wrap one descriptor's handler so that nothing it does is silent.
+ *
+ * Three outcomes, three levels, and the split is about who has to act:
+ *
+ *  - a REFUSAL the package itself decided (a 4xx it returned, or the 422 a
+ *    {@link DiscountValidationError} folds into) is `warn` — the operator
+ *    typed something the rules do not allow, which is worth seeing when a
+ *    store reports "it will not let me save" and worth nobody's pager;
+ *  - anything else THROWN is `error` and is re-thrown unchanged: the store's
+ *    own failures (a unique clash, a dead connection, a foreign target) belong
+ *    to the host's error mapping, and swallowing one here to make a tidy
+ *    response is how a broken database becomes a 404 nobody investigates;
+ *  - a write that SUCCEEDED is `info`, because a discount is a direct lever on
+ *    what a buyer is charged and "who repriced the menu at 03:12" is a
+ *    question that gets asked.
+ *
+ * The catch is what makes the promise total. Before this, only the two write
+ * routes had any catch at all ({@link DiscountValidationError} → 422) and the
+ * three read routes had none, so a store that threw inside `list` produced a
+ * stack in the host's catch-all with nothing naming discounts.
+ */
+export function observed(
+  logger: DiscountsLogger,
+  route: string,
+  handle: (request: WireRequest<DiscountsActor>) => Promise<WireResponse>,
+): (request: WireRequest<DiscountsActor>) => Promise<WireResponse> {
+  return async (request) => {
+    try {
+      const response = await handle(request);
+      if (response.status >= 400) {
+        logger.warn(`${subject(route, request)} refused with ${response.status}`);
+      }
+      return response;
+    } catch (error) {
+      if (error instanceof DiscountValidationError) {
+        logger.warn(`${subject(route, request)} refused with 422 on field "${error.field}"`);
+        throw error;
+      }
+      logger.error(`${subject(route, request)} failed: ${errorText(error)}`);
+      throw error;
+    }
+  };
+}
+
+/** The one line a successful write leaves — see {@link observed}'s third case. */
+export function logWrite(
+  logger: DiscountsLogger,
+  verb: string,
+  request: WireRequest<DiscountsActor>,
+  id: string,
+): void {
+  logger.info(`${verb} discount ${id} for tenant ${request.actor.clientId}`);
+}

package/src/server/mcp.ts

@@ -8,7 +8,14 @@ import {
 } from "@12-apps/shared-helpers/search";
 import type { WireMcpTool } from "@12-apps/wiring";
 
-import { DISCOUNT_SCOPES, DISCOUNT_TRIGGERS, DISCOUNT_TYPES, MAX_PERCENT_OFF_BP } from "../engine/kinds";
+import {
+  DISCOUNT_SCOPES,
+  DISCOUNT_TRIGGERS,
+  DISCOUNT_TYPES,
+  MAX_COMBO_SLOTS,
+  MAX_COMBO_SLOT_QUANTITY,
+  MAX_PERCENT_OFF_BP,
+} from "../engine/kinds";
 import { discountSearchConfig } from "./search";
 
 /**
@@ -46,6 +53,18 @@ export const discountItemParams = z.object({
  */
 const calendarDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
 
+/**
+ * One combo slot: what fills it, and how many units of it one application
+ * needs. Both target lists default to empty and at least one must be
+ * non-empty — a rule `./validate-combo.ts` enforces with the host's own
+ * sentence, because a Zod refinement here could only answer in a Zod path.
+ */
+export const comboRequirementSchema = z.object({
+  menuItemIds: z.array(z.string().min(1)).default([]),
+  categoryIds: z.array(z.string().min(1)).default([]),
+  quantity: z.number().int().min(1).max(MAX_COMBO_SLOT_QUANTITY),
+});
+
 /**
  * A discount as the API returns it (JSON-serialized: dates become ISO
  * strings). The two join tables are flattened into id arrays.
@@ -58,6 +77,16 @@ export const discountSchema = z.object({
   percentOffBp: z.number().int().nullable(),
   /** Cents off. Non-null iff `type = FIXED_AMOUNT`. */
   amountOffCents: z.number().int().nullable(),
+  /**
+   * The COMBO half. OPTIONAL in the RESPONSE, unlike in the body, because the
+   * record is assembled by a host's store: an adopter that has not added the
+   * columns still answers a valid discount, and one that has says so. See
+   * `DiscountRecord` in `./store`.
+   */
+  bundlePriceCents: z.number().int().nullable().optional(),
+  freeUnits: z.number().int().nullable().optional(),
+  maxComboApplications: z.number().int().nullable().optional(),
+  comboRequirements: z.array(comboRequirementSchema).optional(),
   scope: z.enum(DISCOUNT_SCOPES),
   trigger: z.enum(DISCOUNT_TRIGGERS),
   code: z.string().nullable(),
@@ -101,15 +130,20 @@ export const listDiscountsQuery = createDiscountListQuery(searchConfigSchema.par
  * The write body, shared by create and update: a discount is always saved
  * WHOLE (the form re-states every field), so there is no partial-patch shape
  * to diverge from. The cross-field rules — a rate iff PERCENTAGE, a code iff
- * CODE, a target iff CATEGORY/ITEM, `endsAt` strictly after `startsAt` — are
- * enforced in `./validate`, where they produce a sentence naming the field
- * instead of a Zod path.
+ * CODE, a target iff CATEGORY/ITEM, a slot list iff COMBO, a combo reward ONLY
+ * at COMBO scope, `endsAt` strictly after `startsAt` — are enforced in
+ * `./validate` and `./validate-combo`, where they produce a sentence naming the
+ * field instead of a Zod path.
  */
 const discountWriteShape = {
   name: z.string().min(2).max(120),
   type: z.enum(DISCOUNT_TYPES),
   percentOffBp: z.number().int().min(1).max(MAX_PERCENT_OFF_BP).nullable().optional(),
   amountOffCents: z.number().int().positive().nullable().optional(),
+  bundlePriceCents: z.number().int().positive().nullable().optional(),
+  freeUnits: z.number().int().positive().nullable().optional(),
+  comboRequirements: z.array(comboRequirementSchema).max(MAX_COMBO_SLOTS).optional(),
+  maxComboApplications: z.number().int().positive().nullable().optional(),
   scope: z.enum(DISCOUNT_SCOPES),
   trigger: z.enum(DISCOUNT_TRIGGERS),
   code: z.string().min(1).max(64).nullable().optional(),
@@ -145,7 +179,7 @@ export const DISCOUNTS_MCP_TOOLS: readonly WireMcpTool<z.ZodType>[] = [
     method: "GET",
     path: "/discounts",
     summary:
-      "List a store's discounts and promotions (admin). Backend filter (`q` over name and coupon code, `type_in` PERCENTAGE|FIXED_AMOUNT, `scope_in` ORDER|CATEGORY|ITEM, `trigger_in` AUTOMATIC|CODE, `active`), `sort` (field:asc|desc), and pagination (`page`/`pageSize`). Returns the page plus `pagination` (total, pageCount, hasNextPage).",
+      "List a store's discounts and promotions (admin). Backend filter (`q` over name and coupon code, `type_in` PERCENTAGE|FIXED_AMOUNT|BUNDLE_PRICE|FREE_UNITS, `scope_in` ORDER|CATEGORY|ITEM|COMBO, `trigger_in` AUTOMATIC|CODE, `active`), `sort` (field:asc|desc), and pagination (`page`/`pageSize`). Returns the page plus `pagination` (total, pageCount, hasNextPage).",
     tags: ["discounts"],
     params: discountCollectionParams,
     query: listDiscountsQuery,
@@ -167,7 +201,7 @@ export const DISCOUNTS_MCP_TOOLS: readonly WireMcpTool<z.ZodType>[] = [
     method: "POST",
     path: "/discounts",
     summary:
-      "Create a discount for a store (admin). A percentage is basis points (1..10000); a fixed amount is integer cents. A CODE-triggered discount needs a coupon code, unique within the store; a CATEGORY/ITEM-scoped one needs at least one target.",
+      "Create a discount for a store (admin). A percentage is basis points (1..10000); a fixed amount is integer cents. A CODE-triggered discount needs a coupon code, unique within the store; a CATEGORY/ITEM-scoped one needs at least one target. A COMBO-scoped one is a bundle: `comboRequirements` lists its slots (products and/or categories, with a per-slot `quantity`), and the reward is either `BUNDLE_PRICE` (what the whole matched group costs, in cents) or `FREE_UNITS` (how many of its cheapest units are free — \"3 for the price of 2\" is one slot of quantity 3 with `freeUnits` 1), or an ordinary percentage/fixed amount off the group.",
     tags: ["discounts"],
     params: discountCollectionParams,
     body: createDiscountBody,

package/src/server/pt-BR.ts

@@ -23,4 +23,13 @@ export const PT_BR_DISCOUNTS_SERVER_COPY: DiscountsServerCopy = {
   invalidMinSubtotal: "O pedido mínimo deve ser maior que zero (ou deixe em branco).",
   invalidUsageLimit: "O limite de usos deve ser maior que zero (ou deixe em branco).",
   invalidPerBuyerLimit: "O limite por cliente deve ser maior que zero (ou deixe em branco).",
+  comboScopeRequired: "Preço de combo e itens grátis só valem para descontos do tipo combo.",
+  invalidComboSlots: "Um combo precisa de pelo menos um grupo de itens.",
+  comboTargetRequired: "Selecione ao menos um produto ou categoria para cada grupo do combo.",
+  invalidComboQuantity: "Informe uma quantidade maior que zero para cada grupo do combo.",
+  invalidBundlePrice: "Informe o preço do combo, maior que zero.",
+  invalidFreeUnits: "Informe quantos itens saem de graça, maior que zero.",
+  freeUnitsExceedCombo: "O combo precisa cobrar por pelo menos um item.",
+  invalidMaxComboApplications:
+    "O limite de combos por carrinho deve ser maior que zero (ou deixe em branco).",
 };

package/src/server/routes.ts

@@ -3,6 +3,7 @@ import type { z } from "zod";
 import type { WireRequest, WireResponse, WireRoute } from "@12-apps/wiring";
 
 import { missingServerCopy, type DiscountsServerCopy } from "./copy";
+import { logWrite, observed, type DiscountsLogger } from "./logging";
 import { listDiscountsQuery } from "./mcp";
 import { DISCOUNTS_READ, DISCOUNTS_WRITE } from "./contribution";
 import type { DiscountListInput, DiscountRecord, DiscountStore } from "./store";
@@ -45,6 +46,16 @@ export interface DiscountsApiConfig {
   store: DiscountStore;
   /** Every sentence this surface answers a human with. Required, no defaults. */
   copy: DiscountsServerCopy;
+  /**
+   * Where this surface says what it did. Required, and for the same reason
+   * `copy` is: a default would be a no-op, and a no-op default is exactly the
+   * silence this config exists to end — the manifest declares an
+   * `observability` namespace, so a host adopting through
+   * `@12-apps/wiring/consumer` already HAS the logger and passes
+   * `assembled.loggers["@12-apps/discounts"]`; a host on no wiring passes any
+   * `createFeatureLogger`-shaped child. See `./logging`.
+   */
+  logger: DiscountsLogger;
   /**
    * The schema the list query is validated against. Optional ONLY because a
    * mechanical default is portable: the package's own, built from the search
@@ -85,18 +96,33 @@ function writeFrom(body: unknown, copy: DiscountsServerCopy) {
 }
 
 /**
- * Run a write, turning this package's own validation failure into the 422 the
+ * One descriptor's handler, observed and then folded.
+ *
+ * `observed` logs every outcome and changes none of them (see `./logging`);
+ * this fold turns THIS package's own validation failure into the 422 the
  * operator can act on. Everything else — a uniqueness clash, a foreign target,
  * a stale id — is the STORE's to raise, in the host's own error vocabulary,
  * and travels untouched to the host's error mapping.
+ *
+ * Every route goes through it, reads included. A read cannot raise a
+ * `DiscountValidationError`, but it can absolutely throw — and before this the
+ * three read routes had no catch at all, so a store that failed inside `list`
+ * reached the host's catch-all with nothing in the log naming discounts.
  */
-async function attempt(run: () => Promise<WireResponse>): Promise<WireResponse> {
-  try {
-    return await run();
-  } catch (error) {
-    if (error instanceof DiscountValidationError) return fieldError(error);
-    throw error;
-  }
+function endpoint(
+  config: DiscountsApiConfig,
+  route: string,
+  handle: (request: WireRequest<DiscountsActor>) => Promise<WireResponse>,
+): (request: WireRequest<DiscountsActor>) => Promise<WireResponse> {
+  const observedHandle = observed(config.logger, route, handle);
+  return async (request) => {
+    try {
+      return await observedHandle(request);
+    } catch (error) {
+      if (error instanceof DiscountValidationError) return fieldError(error);
+      throw error;
+    }
+  };
 }
 
 function listRoute(config: DiscountsApiConfig): DiscountRoute {
@@ -105,7 +131,7 @@ function listRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "GET",
     path: "/discounts",
     permission: DISCOUNTS_READ,
-    handle: async ({ actor, query }: WireRequest<DiscountsActor>) => {
+    handle: endpoint(config, "GET /discounts", async ({ actor, query }) => {
       const parsed = schema.safeParse(query);
       if (!parsed.success) {
         return { status: 400, body: { error: config.copy.invalidQuery } };
@@ -114,7 +140,7 @@ function listRoute(config: DiscountsApiConfig): DiscountRoute {
       // pagination }` envelope the advertised response describes, and wrapping
       // it again would nest it under a second `data`.
       return ok(await config.store.list(actor.clientId, parsed.data));
-    },
+    }),
   };
 }
 
@@ -123,11 +149,11 @@ function readRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "GET",
     path: "/discounts/:id",
     permission: DISCOUNTS_READ,
-    handle: async ({ actor, params }: WireRequest<DiscountsActor>) => {
+    handle: endpoint(config, "GET /discounts/:id", async ({ actor, params }) => {
       const record = await config.store.get(actor.clientId, String(params.id));
       if (record === null) return { status: 404, body: { error: config.copy.notFound } };
       return ok({ data: record as DiscountRecord });
-    },
+    }),
   };
 }
 
@@ -136,10 +162,12 @@ function createRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "POST",
     path: "/discounts",
     permission: DISCOUNTS_WRITE,
-    handle: ({ actor, body }: WireRequest<DiscountsActor>) =>
-      attempt(async () =>
-        ok({ data: await config.store.create(actor.clientId, writeFrom(body, config.copy)) }),
-      ),
+    handle: endpoint(config, "POST /discounts", async (request) => {
+      const { actor, body } = request;
+      const created = await config.store.create(actor.clientId, writeFrom(body, config.copy));
+      logWrite(config.logger, "created", request, created.id);
+      return ok({ data: created });
+    }),
   };
 }
 
@@ -148,12 +176,13 @@ function updateRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "PATCH",
     path: "/discounts/:id",
     permission: DISCOUNTS_WRITE,
-    handle: ({ actor, params, body }: WireRequest<DiscountsActor>) =>
-      attempt(async () => {
-        const id = String(params.id);
-        await config.store.update(actor.clientId, id, writeFrom(body, config.copy));
-        return acknowledged(id);
-      }),
+    handle: endpoint(config, "PATCH /discounts/:id", async (request) => {
+      const { actor, params, body } = request;
+      const id = String(params.id);
+      await config.store.update(actor.clientId, id, writeFrom(body, config.copy));
+      logWrite(config.logger, "re-stated", request, id);
+      return acknowledged(id);
+    }),
   };
 }
 
@@ -162,21 +191,39 @@ function archiveRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "DELETE",
     path: "/discounts/:id",
     permission: DISCOUNTS_WRITE,
-    handle: async ({ actor, params }: WireRequest<DiscountsActor>) => {
+    handle: endpoint(config, "DELETE /discounts/:id", async (request) => {
+      const { actor, params } = request;
       const id = String(params.id);
       await config.store.archive(actor.clientId, id);
+      logWrite(config.logger, "archived", request, id);
       return acknowledged(id);
-    },
+    }),
   };
 }
 
+/** The three methods `observed` calls — asserted before any request arrives. */
+function assertLogger(logger: DiscountsLogger | undefined): void {
+  const complete =
+    typeof logger?.info === "function" &&
+    typeof logger.warn === "function" &&
+    typeof logger.error === "function";
+  if (complete) return;
+  throw new Error(
+    "@12-apps/discounts: createApiDiscounts needs a logger with info/warn/error — " +
+      "the manifest declares an observability namespace, so a wiring host passes " +
+      'assembled.loggers["@12-apps/discounts"]; there is no silent default.',
+  );
+}
+
 /**
  * The five descriptors, config asserted at construction.
  *
- * Copy is checked HERE rather than at first request, because a missing
- * sentence is a wiring mistake and it should fail where the wiring is written
- * — the report-builder doctrine: required fields, no defaults, asserted at
- * assembly.
+ * Copy and the logger are checked HERE rather than at first request, because a
+ * missing sentence or a missing logger is a wiring mistake and it should fail
+ * where the wiring is written — the report-builder doctrine: required fields,
+ * no defaults, asserted at assembly. The logger earned that treatment the hard
+ * way: for the whole of 1.0.x the manifest promised these routes logged, the
+ * host built the namespaced logger, and nothing connected the two.
  */
 export function createApiDiscounts(config: DiscountsApiConfig): {
   routes: readonly DiscountRoute[];
@@ -188,6 +235,7 @@ export function createApiDiscounts(config: DiscountsApiConfig): {
         "every sentence this surface answers a human with is host config, with no defaults.",
     );
   }
+  assertLogger(config.logger);
   return {
     routes: [
       listRoute(config),