@12-apps/discounts 1.2.0 → 1.3.0

package/prisma/migrations/20260821140000_discounts_package_owned/migration.sql

@@ -0,0 +1,286 @@
+-- @12-apps/discounts: the promotions tables, owned by the package and copied
+-- into a host's migrations folder by its plugin-migration sync. Runs
+-- identically on PostgreSQL and PGlite.
+--
+-- ── REPLAY-SAFE ON PURPOSE ────────────────────────────────────────────────
+-- Every statement here is idempotent, because the first host to adopt this
+-- package already HAS a `discounts` table created by its own, earlier
+-- migration. A package migration is applied by name order, so this one sorts
+-- AFTER the host's — and a bare `CREATE TABLE` would then fail
+-- `prisma migrate deploy` on an existing database AND on a fresh one built from
+-- the full folder. `prisma migrate resolve --applied` can only paper over the
+-- first case, by hand, once per database. So this migration ADOPTS an existing
+-- table instead of demanding a baseline:
+--
+--   * a fresh host gets the three tables, every index and every CHECK;
+--   * a host that already has `discounts` gets only what it is missing — the
+--     three combo columns, the two new tables, and the widened CHECKs;
+--   * replaying the whole folder is a no-op.
+--
+-- What it deliberately does NOT do is MOVE a host's existing target rows. A
+-- host adopting this package has `discount_categories` / `discount_items` rows
+-- that belong in `discount_targets`, and only that host knows whether its
+-- catalog tables are named what this package would have to guess. Backfilling
+-- and dropping the old tables is one migration in the host, written once, and
+-- it sorts after this one.
+--
+-- ── NO FOREIGN KEYS INTO HOST TABLES ──────────────────────────────────────
+-- `client_id` and `target_id` are by-value scalars (the payments-backend
+-- doctrine). The relations INTERNAL to these three tables ARE constrained, with
+-- cascades, so a deleted rule can never leave orphan targets or orphan slots.
+-- A host that wants referential integrity against its own catalog adds those
+-- constraints in its own migration — and should first read the partial's note
+-- on what the absence actually costs.
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- discounts — the rule itself.
+-- ─────────────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS "discounts" (
+    "id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "percent_off_bp" INTEGER,
+    "amount_off_cents" INTEGER,
+    "bundle_price_cents" INTEGER,
+    "free_units" INTEGER,
+    "max_combo_applications" INTEGER,
+    "scope" TEXT NOT NULL,
+    "trigger" TEXT NOT NULL,
+    "code" TEXT,
+    "starts_at" TIMESTAMP(3),
+    "ends_at" TIMESTAMP(3),
+    "min_subtotal_cents" INTEGER,
+    "usage_limit" INTEGER,
+    "per_buyer_limit" INTEGER,
+    "usage_count" INTEGER NOT NULL DEFAULT 0,
+    "stackable" BOOLEAN NOT NULL DEFAULT true,
+    "active" BOOLEAN NOT NULL DEFAULT true,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+    "created_by" TEXT,
+    "updated_by" TEXT,
+    "search_name" TEXT,
+    "archived_at" TIMESTAMP(3),
+
+    CONSTRAINT "discounts_pkey" PRIMARY KEY ("id")
+);
+
+-- The three combo columns, for a host whose `discounts` predates them.
+ALTER TABLE "discounts" ADD COLUMN IF NOT EXISTS "bundle_price_cents" INTEGER;
+ALTER TABLE "discounts" ADD COLUMN IF NOT EXISTS "free_units" INTEGER;
+ALTER TABLE "discounts" ADD COLUMN IF NOT EXISTS "max_combo_applications" INTEGER;
+
+-- One live name and one live coupon per tenant. PARTIAL on purpose: deleting is
+-- a soft archive, and an unconditional unique lets a deleted coupon squat its
+-- code forever, so the operator can never recreate a code they removed. NULLs
+-- stay distinct, so the many automatic rules (all `code` NULL) never collide.
+CREATE UNIQUE INDEX IF NOT EXISTS "discounts_client_id_name_key"
+    ON "discounts"("client_id", "name") WHERE "archived_at" IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS "discounts_client_id_code_key"
+    ON "discounts"("client_id", "code") WHERE "archived_at" IS NULL;
+
+-- The storefront's "which rules could fire right now", and the admin list's
+-- default active-first ordering.
+CREATE INDEX IF NOT EXISTS "discounts_client_id_active_archived_at_idx"
+    ON "discounts"("client_id", "active", "archived_at");
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- discount_combo_slots — the quantified groups a COMBO matches.
+-- ─────────────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS "discount_combo_slots" (
+    "id" TEXT NOT NULL,
+    "discount_id" TEXT NOT NULL,
+    -- The operator's order, which is also the order a card describes the combo
+    -- in. Stable because two slots of the same size are otherwise
+    -- indistinguishable in a list.
+    "position" INTEGER NOT NULL,
+    "quantity" INTEGER NOT NULL,
+
+    CONSTRAINT "discount_combo_slots_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "discount_combo_slots_discount_id_position_key"
+    ON "discount_combo_slots"("discount_id", "position");
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- discount_targets — what a rule points at, BY VALUE.
+--
+-- One table for both jobs, told apart by `slot_id`: NULL is a SCOPE target,
+-- non-null is one combo slot's. They are the same fact — "this rule cares about
+-- this row of this collection" — and two tables would need every reverse read,
+-- every ownership check and every cascade written twice.
+-- ─────────────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS "discount_targets" (
+    "id" TEXT NOT NULL,
+    "discount_id" TEXT NOT NULL,
+    "slot_id" TEXT,
+    "target_type" TEXT NOT NULL,
+    "target_id" TEXT NOT NULL,
+
+    CONSTRAINT "discount_targets_pkey" PRIMARY KEY ("id")
+);
+
+-- PARTIAL uniques, and they have to be: NULLs are distinct in Postgres, so one
+-- unconditional unique over `slot_id` would not constrain the scope rows at all
+-- — a rule could name the same category twice and cover it twice.
+CREATE UNIQUE INDEX IF NOT EXISTS "discount_targets_scope_key"
+    ON "discount_targets"("discount_id", "target_type", "target_id")
+    WHERE "slot_id" IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS "discount_targets_slot_key"
+    ON "discount_targets"("slot_id", "target_type", "target_id")
+    WHERE "slot_id" IS NOT NULL;
+
+-- The reverse read a menu badge does: "which rules touch this row".
+CREATE INDEX IF NOT EXISTS "discount_targets_target_type_target_id_idx"
+    ON "discount_targets"("target_type", "target_id");
+CREATE INDEX IF NOT EXISTS "discount_targets_discount_id_idx"
+    ON "discount_targets"("discount_id");
+CREATE INDEX IF NOT EXISTS "discount_targets_slot_id_idx"
+    ON "discount_targets"("slot_id");
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Foreign keys — INTERNAL only.
+-- ─────────────────────────────────────────────────────────────────────────────
+DO $$ BEGIN
+    ALTER TABLE "discount_combo_slots" ADD CONSTRAINT "discount_combo_slots_discount_id_fkey"
+        FOREIGN KEY ("discount_id") REFERENCES "discounts"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discount_targets" ADD CONSTRAINT "discount_targets_discount_id_fkey"
+        FOREIGN KEY ("discount_id") REFERENCES "discounts"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- Cascading from the SLOT as well as from the discount: removing one slot of a
+-- combo must take its targets, or the next write would merge them into the slot
+-- that replaced it.
+DO $$ BEGIN
+    ALTER TABLE "discount_targets" ADD CONSTRAINT "discount_targets_slot_id_fkey"
+        FOREIGN KEY ("slot_id") REFERENCES "discount_combo_slots"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- CHECK constraints — the String+CHECK house style. The closed sets here and
+-- the arrays in `src/engine/kinds.ts` are two halves of ONE set: widening one
+-- without the other is how a write starts failing at the database rather than
+-- at the validator.
+--
+-- The three that a host may already have in a NARROWER form are dropped and
+-- re-added rather than guarded, because the whole point is to widen them.
+-- ─────────────────────────────────────────────────────────────────────────────
+ALTER TABLE "discounts" DROP CONSTRAINT IF EXISTS "discounts_type_check";
+ALTER TABLE "discounts" ADD CONSTRAINT "discounts_type_check"
+    CHECK ("type" IN ('PERCENTAGE', 'FIXED_AMOUNT', 'BUNDLE_PRICE', 'FREE_UNITS'));
+
+ALTER TABLE "discounts" DROP CONSTRAINT IF EXISTS "discounts_scope_check";
+ALTER TABLE "discounts" ADD CONSTRAINT "discounts_scope_check"
+    CHECK ("scope" IN ('ORDER', 'CATEGORY', 'ITEM', 'COMBO'));
+
+-- Exactly one value column, chosen by the type. A percentage with no rate, or a
+-- bundle with no price, would silently discount nothing.
+ALTER TABLE "discounts" DROP CONSTRAINT IF EXISTS "discounts_value_check";
+ALTER TABLE "discounts" ADD CONSTRAINT "discounts_value_check"
+    CHECK (("type" = 'PERCENTAGE')   = ("percent_off_bp" IS NOT NULL)
+       AND ("type" = 'FIXED_AMOUNT') = ("amount_off_cents" IS NOT NULL)
+       AND ("type" = 'BUNDLE_PRICE') = ("bundle_price_cents" IS NOT NULL)
+       AND ("type" = 'FREE_UNITS')   = ("free_units" IS NOT NULL));
+
+-- A combo REWARD only means something against a matched group: "the group costs
+-- R$ 25" and "one of them is free" are both statements ABOUT a group.
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_combo_reward_scope_check"
+        CHECK ("type" NOT IN ('BUNDLE_PRICE', 'FREE_UNITS') OR "scope" = 'COMBO');
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_bundle_price_check"
+        CHECK ("bundle_price_cents" IS NULL OR "bundle_price_cents" > 0);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_free_units_check"
+        CHECK ("free_units" IS NULL OR "free_units" > 0);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- A per-cart cap on a rule that is not a combo would be a number nothing reads.
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_max_combo_applications_check"
+        CHECK ("max_combo_applications" IS NULL
+            OR ("max_combo_applications" > 0 AND "scope" = 'COMBO'));
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_trigger_check"
+        CHECK ("trigger" IN ('AUTOMATIC', 'CODE'));
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- 0 bp is not a promotion; over 100% would credit the buyer.
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_percent_off_bp_check"
+        CHECK ("percent_off_bp" IS NULL
+            OR ("percent_off_bp" > 0 AND "percent_off_bp" <= 10000));
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_amount_off_cents_check"
+        CHECK ("amount_off_cents" IS NULL OR "amount_off_cents" > 0);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- A CODE rule with no code can never be redeemed; an AUTOMATIC one with a code
+-- would be redeemable two different ways.
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_code_check"
+        CHECK (("trigger" = 'CODE') = ("code" IS NOT NULL));
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- An inverted window is always empty; whoever typed it meant something else.
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_window_check"
+        CHECK ("ends_at" IS NULL OR "starts_at" IS NULL OR "ends_at" > "starts_at");
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_min_subtotal_check"
+        CHECK ("min_subtotal_cents" IS NULL OR "min_subtotal_cents" > 0);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_usage_limit_check"
+        CHECK ("usage_limit" IS NULL OR "usage_limit" > 0);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_per_buyer_limit_check"
+        CHECK ("per_buyer_limit" IS NULL OR "per_buyer_limit" > 0);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_usage_count_check"
+        CHECK ("usage_count" >= 0);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- The invariant the predicated PAID-time UPDATE exists to keep true.
+DO $$ BEGIN
+    ALTER TABLE "discounts" ADD CONSTRAINT "discounts_usage_within_limit_check"
+        CHECK ("usage_limit" IS NULL OR "usage_count" <= "usage_limit");
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- A slot asking for zero units can never be filled; the upper bound is
+-- MAX_COMBO_SLOT_QUANTITY, and a combo nobody can carry is not an offer.
+DO $$ BEGIN
+    ALTER TABLE "discount_combo_slots" ADD CONSTRAINT "discount_combo_slots_quantity_check"
+        CHECK ("quantity" > 0 AND "quantity" <= 50);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+DO $$ BEGIN
+    ALTER TABLE "discount_combo_slots" ADD CONSTRAINT "discount_combo_slots_position_check"
+        CHECK ("position" >= 0);
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- The closed set of discountable dimensions. Widening it is a host registering
+-- one more DiscountableCollection, plus this line.
+DO $$ BEGIN
+    ALTER TABLE "discount_targets" ADD CONSTRAINT "discount_targets_target_type_check"
+        CHECK ("target_type" IN ('CATEGORY', 'ITEM'));
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;

package/scripts/sync-discounts-schema.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/* global console, process */
+/**
+ * Copy this package's Prisma model PARTIAL into the host's schema folder.
+ *
+ *   node scripts/sync-discounts-schema.mjs [--check] [<host-schema-dir>]
+ *
+ * The partial is COPIED, never symlinked (the
+ * prisma-partials-are-copied-never-symlinked doctrine): `turbo prune` copies
+ * only what the dependency graph reaches, so a committed symlink dangles the
+ * moment the owning package is not a declared workspace dependency — and a
+ * SYMLINKED MIGRATION is silently skipped by Prisma (`readdir` +
+ * `isDirectory()` is false for a link), so a green deploy applies no schema.
+ *
+ * Only the schema partial. MIGRATIONS ARE NOT HANDLED HERE — a host discovers
+ * and copies them structurally, by looking for a `prisma/migrations` directory
+ * inside every installed `@12-apps/*` package.
+ *
+ * The host package that owns the schema folder MUST also declare this package
+ * as a dependency, so the source of the copy is present in every build context.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LABEL = '[discounts-schema]';
+const RESYNC = 'pnpm --filter @12-apps/discounts prisma:sync';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SOURCE = join(HERE, '../prisma/discounts.prisma');
+
+const args = process.argv.slice(2).filter((arg) => arg !== '--check');
+const check = process.argv.includes('--check');
+const hostSchemaDir =
+  args[0] ?? process.env.DISCOUNTS_HOST_SCHEMA_DIR ?? join(HERE, '../../prisma/prisma/schema');
+const TARGET = join(hostSchemaDir, 'discounts.prisma');
+
+const source = readFileSync(SOURCE, 'utf8');
+const target = existsSync(TARGET) ? readFileSync(TARGET, 'utf8') : null;
+
+if (source === target) {
+  console.log(`${LABEL} in sync.`);
+} else if (check) {
+  console.error(
+    `${LABEL} DRIFT: ${TARGET} does not match the @12-apps/discounts partial. ` +
+      `Run "${RESYNC}" and commit the result.`,
+  );
+  process.exit(1);
+} else {
+  mkdirSync(hostSchemaDir, { recursive: true });
+  copyFileSync(SOURCE, TARGET);
+  console.log(`${LABEL} copied ${SOURCE} -> ${TARGET}.`);
+}

package/src/engine/kinds.ts

@@ -60,6 +60,26 @@ export const COMBO_ONLY_DISCOUNT_TYPES = ["BUNDLE_PRICE", "FREE_UNITS"] as const
 export const DISCOUNT_SCOPES = ["ORDER", "CATEGORY", "ITEM", "COMBO"] as const;
 export type DiscountScope = (typeof DISCOUNT_SCOPES)[number];
 
+/**
+ * The DIMENSIONS a discount can be pointed at — the two scopes above that name
+ * rows in a host's catalog, as opposed to `ORDER` (which names nothing) and
+ * `COMBO` (which names its own slots).
+ *
+ * Split out from the scopes because they are the key of a different thing: a
+ * `DiscountableCollection` is a host's answer for ONE of these
+ * (`./server/collections`), and a combo slot names both of them at once, so
+ * neither list is a subset of the other in use even though it is here.
+ *
+ * This set is closed today and that is a boundary rather than a principle. A
+ * third dimension — "every item from this supplier", "every item on this
+ * shelf" — is expressible the moment targets are stored BY VALUE
+ * (`(target_type, target_id)`) rather than as a join table per member, and the
+ * registration seam is deliberately shaped so that widening this array plus
+ * registering one more collection is the whole change.
+ */
+export const DISCOUNT_TARGET_TYPES = ["CATEGORY", "ITEM"] as const;
+export type DiscountTargetType = (typeof DISCOUNT_TARGET_TYPES)[number];
+
 /**
  * What makes a discount fire: the engine picks `AUTOMATIC` ones up on its own,
  * while a `CODE` one only becomes a candidate when the buyer types its coupon.
@@ -67,6 +87,48 @@ export type DiscountScope = (typeof DISCOUNT_SCOPES)[number];
 export const DISCOUNT_TRIGGERS = ["AUTOMATIC", "CODE"] as const;
 export type DiscountTrigger = (typeof DISCOUNT_TRIGGERS)[number];
 
+/**
+ * Where a rule sits relative to its window RIGHT NOW.
+ *
+ * A derived fact rather than a stored one — it is `startsAt`/`endsAt` compared
+ * against an instant, so storing it would mean a column that is wrong between
+ * the moment a promotion starts and the next time something wrote to it.
+ *
+ * The values are English wire tokens on purpose. They are read in three places
+ * that must agree — an admin grid's filter pill, the query the backend
+ * receives, and the badge on a row — and the moment one of those three is a
+ * word in a language, the set stops being a set: the origin host filtered on
+ * `Vigente`, so its pill values WERE its pt-BR labels, and a second host in
+ * another language could not use its own words without changing the wire.
+ * Labels come from the web copy pack; these do not.
+ */
+export const DISCOUNT_WINDOW_STATES = ["RUNNING", "SCHEDULED", "ENDED"] as const;
+export type DiscountWindowState = (typeof DISCOUNT_WINDOW_STATES)[number];
+
+/**
+ * Which of the three a rule is in, at `now`.
+ *
+ * Domain logic rather than presentation, which is why it lives beside the
+ * vocabulary and not in the web surface: the badge on a row and the filter the
+ * backend applies must answer this the same way, and two implementations of
+ * "has it ended" is how a grid shows a rule as running on a row the filter
+ * excludes.
+ *
+ * The window is half-open `[startsAt, endsAt)` — `endsAt` is EXCLUSIVE, so a
+ * promotion ends the instant its end date begins.
+ */
+export function discountWindowState(
+  rule: { startsAt: Date | string | null; endsAt: Date | string | null },
+  now: Date,
+): DiscountWindowState {
+  const instant = now.getTime();
+  const starts = rule.startsAt === null ? null : new Date(rule.startsAt).getTime();
+  const ends = rule.endsAt === null ? null : new Date(rule.endsAt).getTime();
+  if (starts !== null && starts > instant) return "SCHEDULED";
+  if (ends !== null && ends <= instant) return "ENDED";
+  return "RUNNING";
+}
+
 /**
  * Why a discount the buyer explicitly asked for was not applied. Only ever
  * surfaced for a coupon the buyer typed or for a promo displaced by an

package/src/index.ts

@@ -33,8 +33,11 @@ export {
   COMBO_ONLY_DISCOUNT_TYPES,
   DISCOUNT_REJECTION_REASONS,
   DISCOUNT_SCOPES,
+  DISCOUNT_TARGET_TYPES,
   DISCOUNT_TRIGGERS,
   DISCOUNT_TYPES,
+  DISCOUNT_WINDOW_STATES,
+  discountWindowState,
   MAX_COMBO_SLOTS,
   MAX_COMBO_SLOT_QUANTITY,
   MAX_PERCENT_OFF_BP,
@@ -42,8 +45,10 @@ export {
   normalizeDiscountCode,
   type DiscountRejectionReason,
   type DiscountScope,
+  type DiscountTargetType,
   type DiscountTrigger,
   type DiscountType,
+  type DiscountWindowState,
 } from "./engine/kinds";
 
 export type {

package/src/manifest/index.ts

@@ -13,23 +13,41 @@
  * (`__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.
+ * ## The `db` capability, and what had to change to earn it
+ *
+ * This manifest used to declare none, on the reasoning that a discount's rows
+ * relate to a host's own catalog: a partial literally naming `product_categories`
+ * and `menu_items` only compiles inside a host that has tables under those
+ * names. That half was right. The half that was not is the conclusion — the
+ * shape was not a given.
+ *
+ * `@12-apps/entity-lifecycle` had already solved it in this repo and written
+ * the answer at the top of its own partial: name the record BY VALUE. Applied
+ * here, the two target join tables collapse into one `discount_targets` keyed
+ * `(target_type, target_id)`, the tenant becomes a scalar `client_id`, and
+ * WHICH collections are discountable becomes a runtime `DiscountableCollection`
+ * registration rather than a schema fact. Nothing in the partial names a host
+ * table, so `composed` qualifies on the contract's own terms.
+ *
+ * What stays behind is the REDEMPTION snapshot (`order_discounts`): a child of
+ * the host's order, with a cascade, whose whole purpose is to freeze what a
+ * buyer received on an order the host owns. Shipping the rule and leaving the
+ * receipt is the clean cut.
+ *
+ * ## The `web` capability, and what had to move first
+ *
+ * This manifest also used to refuse `web`, and the refusal was right at the
+ * time: the screens were 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.
+ *
+ * Neither half holds now. The copy IS host config — `DiscountsWebCopy`,
+ * required and defaultless, the third such port here. And what was genuinely
+ * host-grown underneath the screens — the kebab, the card context, the two
+ * confirm hooks, the server-grid hook, the row export — moved into
+ * `@12-apps/ui` and `@12-apps/app-shell` first, which is the only reason this
+ * could follow rather than dragging a private copy of an admin framework along
+ * with it.
  */
 
 import type { PackageManifest } from "@12-apps/wiring";
@@ -55,5 +73,15 @@ export const discountsManifest = {
    * undeclared one, because it reads as finished.
    */
   observability: { namespace: "discounts" },
+  /**
+   * `composed`, not `isolated`. The models carry no relation into host tables,
+   * which is the qualification isolation asks for — but isolation costs the
+   * seam, and this is the one package where that cost is unpayable: the
+   * redemption counter is incremented INSIDE the host's PAID confirmation
+   * transaction, and a rule whose counter cannot move in the same transaction
+   * as the order that redeemed it is a rule that can be redeemed twice.
+   */
+  db: { partial: "prisma/discounts.prisma", migrations: "prisma/migrations" },
   server: ["http"],
+  web: ["surface", "areas"],
 } as const satisfies PackageManifest;

package/src/manifest/web.ts

@@ -0,0 +1,55 @@
+/**
+ * `@12-apps/discounts/manifest/web` — the browser capabilities.
+ *
+ * Two contributions. `surface` is the `createWeb*` convention the contract
+ * names: one config object in, an object of component types out, memoised by
+ * the host because the members are TYPES. `areas` is the declaration half — a
+ * route and a nav row this package SUGGESTS for a host's admin area, which the
+ * host is free to relabel, reorder or veto at its single call site.
+ *
+ * ## Why this capability exists now, and did not before
+ *
+ * The manifest used to refuse it, and said why:
+ *
+ * > 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.
+ *
+ * Both halves were true when written and neither is now. The copy IS host
+ * config — `DiscountsWebCopy`, required, no defaults, the third such port in
+ * this package. And the "host design system" is `@12-apps/ui`, a shared
+ * package these screens already read eighteen symbols from; what genuinely was
+ * host-grown underneath them — the kebab, the card context, the confirm hooks,
+ * the server-grid hook, the export — moved into `@12-apps/ui` and
+ * `@12-apps/app-shell` first, which is why this could follow.
+ *
+ * Behind its own subpath so a server bundle importing the shared manifest never
+ * resolves React.
+ */
+
+import type { AnyWebManifest } from "@12-apps/wiring";
+
+import { createWebDiscounts } from "../react/create-web-discounts";
+
+export const discountsWebManifest = {
+  name: "@12-apps/discounts",
+  surface: { create: createWebDiscounts },
+  areas: [
+    {
+      area: "admin",
+      routes: [
+        {
+          path: "discounts",
+          screen: "Screen",
+          // The write privilege gates the ROUTE, not just the create button:
+          // the grid is an operator's view of what the store charges, and a
+          // read-only visitor has `discounts:read` for the storefront's sake
+          // rather than for this page's.
+          permission: "discounts:read",
+        },
+      ],
+      nav: [{ testId: "nav-discounts", path: "discounts", permission: "discounts:read" }],
+    },
+  ],
+} as const satisfies AnyWebManifest;