@zolve/offers 0.3.0 → 0.3.2

package/README.md

@@ -16,9 +16,12 @@ const decision = decide(doc, { placement: 'cart', cart, visitorId, at: new Date(
 
 // Cobrança: o preço de cada linha aceita (com offerId), conferindo as condições de novo com o carrinho real.
 const priced = price(doc, { cart, visitorId, at });
-// priced.lines[i]: { status: 'ok', unitPrice } | { status: 'ineligible', reason }
+// priced.lines[i]: { status: 'ok', unitPrice, compareAtPrice, discountedQuantity } | { status: 'ineligible', reason }
 ```
 
+`unitPrice` é por unidade e vale para `discountedQuantity` unidades da linha (0.3.2); o resto da linha vai a preço
+cheio. `compareAtPrice` é o preço da loja no documento, quando maior que o da oferta (o mesmo do `decide`).
+
 `offerKind(doc, offer)` (0.2.0) dá o tipo e a direção de uma oferta cadastrada sem carrinho, com os gatilhos de
 `cart_has_any` no papel do carrinho escolhido: é o que o editor do Commerce OS mostra.
 
@@ -49,6 +52,83 @@ price(doc, { cart, visitorId, assignments, at });
 por posição (sorteio do PostHog, em duas etapas) e o grupo de fora geral. `price` devolve a mesma variante de teste que
 o `decide` deu ao visitante.
 
+## Regras de cobrança (0.3.1)
+
+- **Grupo de fora geral** (ADR-0047): ligado, quem cai nele não vê oferta. O `decide` devolve `offers: []` e
+  `holdout: true` (a ponte manda o `exposed` do controle geral); o `price` recusa as linhas dele com `holdout`. Sem
+  `visitorId`, `holdout` é sempre `false`.
+- **Só o que a cliente escolheu** é gatilho, subtotal, vaga extra e combo, no `decide` e na reconferência do `price`:
+  linha de oferta aceita não sustenta outra. A exceção é a **linha de troca** (`offerId` + `replacedItem` de uma oferta
+  `replace` do documento, item trocado do mesmo produto), que desde a 0.3.2 conta como o **item trocado** para todas as
+  ofertas (ver abaixo). O `replacedItem` fora de `doc.items` é reconhecido pelo `storeProductId` da linha (a troca é no
+  mesmo produto da loja). Só conta como escolhida a troca cuja oferta `replace` está ligada (com a variante do
+  teste do visitante), dentro da validade no `at` e de tipo que o pacote conhece; senão é linha de oferta comum e não
+  sustenta outra oferta.
+- **Vagas na cobrança**: o `price` não cobra mais ofertas por posição do que as vagas (com a extra), na ordem de
+  prioridade; o excesso, e a mesma oferta ou o mesmo item numa segunda linha, volta `no_slot`.
+- **Linha de oferta é toda linha com `offerId`, brinde (`gift: true`) ou não**: ocupa a vaga da posição dela no
+  `decide` e disputa a vaga no `price`. O `gift` só a tira do gatilho e do subtotal.
+- **Posição de cada linha de oferta**, uma regra só para o `decide` (vagas já tomadas) e o `price` (cobrança): vale o
+  `placement` da linha quando a oferta tem aquele id naquela posição; sem ele (ou com outro), a primeira posição, na
+  ordem do documento, em que a oferta é elegível; nenhuma elegível, a primeira. Linha recusada ainda ocupa a vaga no
+  `decide` (a ponte pode cobrá-la cheia); id que o documento não tem não ocupa vaga.
+- **Vitrine e cobrança concordam**: para o mesmo documento e carrinho, toda oferta que o `decide` mostra e a cliente
+  aceita (e, desde a 0.3.2, toda combinação delas, com troca, vaga extra e combo) sai `ok` no `price`, ao preço
+  mostrado (é um teste de propriedade do pacote). Para isso a linha acrescentada leva o
+  `placement` da `DecidedOffer`: com o id em duas posições e sem ele, a regra acima pode atribuir a linha à outra
+  posição.
+- **`visitorId` no `price`**: a ponte manda sempre o mesmo `visitorId` (e as mesmas `assignments`) do `decide`. Sem
+  ele o `price` não sorteia teste nem confere o grupo de fora geral: cobra o documento sem variante, e quem estava no
+  grupo de fora leva a oferta.
+
+## Um carrinho só e quantidade com teto (0.3.2)
+
+- **O carrinho de antes da troca**, no `decide` e no `price`: a linha de troca válida volta a ser o item trocado
+  (`replacedItem`), com a quantidade da linha, como linha escolhida, para **tudo**: gatilho, `cart_has_none`, subtotal,
+  vaga extra, combo e contagem de vagas, da própria troca e das outras ofertas. A linha de troca em si ocupa a vaga da
+  posição dela. Assim o `price` vê exatamente o carrinho que o `decide` viu: a troca LP → 90 não fecha a vaga extra
+  presa à LP, o cross-sell com gatilho na Intense 30 segue valendo depois da troca 30 → 90, e a troca de R$ 199 não
+  destrava o brinde de R$ 250 (no subtotal entra o item trocado, não o novo). Substitui a regra da 0.3.1 ("a linha de
+  troca conta como o produto que a cliente leva").
+- **Subtotal pelo preço do documento**: toda linha escolhida de item listado em `doc.items` entra no subtotal pelo
+  preço do documento; o `unitPrice` da linha só vale para item fora dele (0 sem nenhum dos dois). O item trocado já
+  saiu do carrinho e o pacote não sabe o preço da linha que sumiu: com o preço do documento, as duas chamadas somam
+  igual. Item trocado **fora** do documento conta 0 no subtotal depois da troca (a compilação deve listar os itens que
+  uma troca pode tirar). O `unitPrice` segue sendo teto do preço da linha de oferta.
+- **Troca só na posição dela**: a linha é troca quando a oferta `replace` com aquele `offerId` é a da posição da linha
+  (o `placement` dela, ou a atribuída pela regra de posição abaixo), ligada, na validade, de tipo conhecido, do mesmo
+  item, e o `replacedItem` é do mesmo produto. O mesmo id como `add` em `cart` e `replace` em `product_page`: a linha
+  de `cart` com `replacedItem` forjado é `add` e não sustenta outra oferta.
+- **Alvo da troca sem depender da ordem**: com mais de uma linha escolhida do mesmo produto, o `replaces` é a de menor
+  duração no catálogo e, no empate (ou sem duração), a de menor chave de item (`source:variantId`). Linha que já é
+  troca não é alvo de outra troca.
+- **`maxQuantity`** (campo opcional da oferta, inteiro ≥ 1): quantas unidades da linha levam o preço da oferta.
+  Ausente: **1** quando o preço da oferta dá 0 (brinde), a linha toda nos outros casos. O `price` devolve
+  `discountedQuantity` por linha `ok`; a ponte aplica o desconto só nessas unidades (na Shopify, o desconto de linha
+  com quantidade limitada) e o resto vai a preço cheio. `maxQuantity` que não é inteiro ≥ 1 torna a oferta
+  `unsupported_offer`. Como a 0.3.2 cobra diferente da 0.3.1 com o mesmo documento (o brinde passa a valer uma
+  unidade mesmo sem o campo), o formato subiu para **`schemaVersion` 2**: uma ponte ainda na 0.3.1 recebe
+  `unsupported_schema` e não cobra, em vez de dar o desconto na linha toda.
+- **Linha validada**: `quantity` inteiro ≥ 1 e `unitPrice` (se vier) centavos inteiros ≥ 0. Linha fora disso não é
+  gatilho nem entra no subtotal; a linha de oferta volta `invalid_line`. O pacote nunca devolve `NaN`, negativo ou
+  fração; preço de oferta com valor que não é inteiro também é `unsupported_offer`.
+- **`decisionId`** = sha1 da versão, posição, visitante, carrinho (cada linha com item, quantidade, `unitPrice`,
+  `offerId`, `placement`, `replacedItem`, `storeProductId`, `gift`, sem a ordem) e da **resposta inteira** (cada oferta
+  com preço, alvo da troca, conteúdo e vaga; apresentação, combo, teste, `holdout`). Mesma pergunta e mesma resposta =
+  mesmo id; resposta diferente, outro id. Os ids mudam em relação à 0.3.1.
+
+Motivos de `ineligible`: `unknown_offer`, `inactive`, `item_mismatch`, `not_started`, `expired`, `trigger_missing`,
+`subtotal_out_of_range`, `unsupported_schema` e, desde a 0.3.1:
+
+| Motivo | Quando |
+|---|---|
+| `unavailable` | Item oferecido indisponível ou com preço da loja 0 no documento (nunca sai de graça por falta de preço; brinde a R$ 0 é `fixed` 0 com preço da loja) |
+| `holdout` | Visitante no grupo de fora geral |
+| `no_slot` | A posição já tem as vagas tomadas por ofertas de prioridade maior, ou a oferta/item já vale em outra linha |
+| `unsupported_offer` | Condição, preço ou ação de tipo que o pacote não conhece (o `decide` também não mostra) |
+| `invalid_instant` | Oferta com validade e `at` (ou a validade) ilegível |
+| `invalid_line` (0.3.2) | Linha com `quantity` que não é inteiro ≥ 1 ou `unitPrice` que não é centavo inteiro ≥ 0 |
+
 Documento com `schemaVersion` maior que `SUPPORTED_SCHEMA_VERSION` não é decidido nem precificado: a resposta vem com
 `status: 'unsupported_schema'` (e toda linha do `price` inelegível com esse motivo). Atualize o pacote.
 

package/dist/assess.d.ts

@@ -0,0 +1,33 @@
+import { type ItemIndex, type SwapCheck } from './cart.js';
+import type { IneligibleReason, PricedLine, PriceInput } from './io.js';
+import type { SlotClaim } from './slots.js';
+import type { Offer, OfferDocument } from './types.js';
+/**
+ * A avaliação das linhas de oferta do carrinho, a mesma no `decide` (as vagas já tomadas) e no `price` (a cobrança).
+ * O `input` é só o que as duas chamadas têm em comum: carrinho, instante, visitante e atribuições. `placed` é a oferta
+ * do documento a que cada linha de oferta foi atribuída (a regra de posição), e `isSwap` sai dela.
+ */
+export interface Assessor {
+    doc: OfferDocument;
+    items: ItemIndex;
+    input: PriceInput;
+    isSwap: SwapCheck;
+    placed: Map<number, Offer>;
+}
+/** Uma linha de oferta avaliada: a posição a que ela foi atribuída e, se passou, a oferta que disputa a vaga. */
+export interface Assessed {
+    priced: PricedLine;
+    claim: SlotClaim | null;
+    /** Nula só para o id que o documento não tem. */
+    placement: string | null;
+}
+export declare const refused: (index: number, offerId: string, reason: IneligibleReason) => PricedLine;
+/** O portão da oferta em si, sem carrinho: tipo que o pacote conhece, ligada e dentro da validade. */
+export declare function offerGate(offer: Offer, at: string): IneligibleReason | null;
+/**
+ * Duas passadas: primeiro as trocas que a própria linha define (o id numa posição só, ou a posição da linha); com elas,
+ * a posição de cada linha de oferta; daí as trocas de fato (`replace` na posição atribuída), que valem para tudo.
+ */
+export declare function assessor(doc: OfferDocument, items: ItemIndex, input: PriceInput): Assessor;
+/** Toda linha com `offerId`, brinde ou não, na ordem do carrinho: é linha de oferta, e disputa a vaga da posição dela. */
+export declare function assessOfferLines(ctx: Assessor): Assessed[];

package/dist/assess.js

@@ -0,0 +1,141 @@
+import { isSameProductSwap, isValidLine, itemKey, viewCart } from './cart.js';
+import { conditionsFailure, isSellable, isSupportedOffer, validityFailure } from './conditions.js';
+import { applyVariant } from './effective.js';
+import { assignExperiment } from './experiments.js';
+import { compareAtPrice, discountedQuantity, offerUnitPrice } from './money.js';
+export const refused = (index, offerId, reason) => ({ index, offerId, status: 'ineligible', reason });
+/** A oferta do documento como o visitante a vê: com a variante do teste da posição dela. */
+function liveOffer(doc, found, input) {
+    return applyVariant(found, assignExperiment(doc, found.placement, input)?.variant ?? null);
+}
+/** O portão da oferta em si, sem carrinho: tipo que o pacote conhece, ligada e dentro da validade. */
+export function offerGate(offer, at) {
+    if (!isSupportedOffer(offer))
+        return 'unsupported_offer';
+    if (!offer.active)
+        return 'inactive';
+    return validityFailure(offer, at);
+}
+/**
+ * Troca viva: a oferta (a da posição da linha) é `replace` daquele item, passa no portão com a variante do visitante e
+ * o `at`, e a linha é válida e diz que trocou um item do mesmo produto. Forjar os campos só rende o que o caminho
+ * legítimo daria; a troca desligada, vencida, de tipo desconhecido ou de outra posição é linha de oferta comum.
+ */
+function isLiveSwap(ctx, offer, line) {
+    if (offer.action !== 'replace' || itemKey(offer.item) !== itemKey(line.item))
+        return false;
+    if (!isValidLine(line) || !isSameProductSwap(ctx.items, line))
+        return false;
+    return offerGate(liveOffer(ctx.doc, offer, ctx.input), ctx.input.at) === null;
+}
+/** As ofertas que podem valer para a linha: a da posição dela, quando o id está lá; senão todas com o id. */
+function lineOptions(doc, line) {
+    const same = doc.offers.filter((offer) => offer.id === line.offerId);
+    const declared = same.filter((offer) => offer.placement === line.placement);
+    return declared.length > 0 ? declared : same;
+}
+/** As posições do carrinho que são troca, calculadas uma vez (o sorteio do teste não roda a cada linha). */
+function swapSet(cart, offerOf, isSwap) {
+    const swaps = new Set(cart.flatMap((line, index) => {
+        const offer = line.offerId ? offerOf(line, index) : undefined;
+        return offer && isSwap(offer, line) ? [index] : [];
+    }));
+    return (index) => swaps.has(index);
+}
+/**
+ * O carrinho como no instante em que a oferta apareceu, o de antes da troca: só o que a cliente escolheu (as trocas
+ * de volta ao item trocado), sem a própria linha no `add` e, no `replace`, com ela de volta ao item trocado. Nulo
+ * quando o `replace` não diz o que trocou, ou diz um item que não é o mesmo produto.
+ */
+function recheckView(ctx, offer, index) {
+    const line = ctx.input.cart[index];
+    if (offer.action === 'add')
+        return viewCart(ctx.items, ctx.input.cart, ctx.isSwap, index);
+    if (!isSameProductSwap(ctx.items, line))
+        return null;
+    return viewCart(ctx.items, ctx.input.cart, (position) => position === index || ctx.isSwap(position));
+}
+function lineFailure(ctx, offer, index) {
+    const line = ctx.input.cart[index];
+    if (!isValidLine(line))
+        return 'invalid_line';
+    const gate = offerGate(offer, ctx.input.at);
+    if (gate === 'unsupported_offer' || gate === 'inactive')
+        return gate;
+    const item = ctx.items.get(itemKey(offer.item));
+    if (!item)
+        return 'unknown_offer';
+    if (itemKey(line.item) !== itemKey(offer.item))
+        return 'item_mismatch';
+    if (!isSellable(item))
+        return 'unavailable';
+    if (gate)
+        return gate;
+    const view = recheckView(ctx, offer, index);
+    if (!view)
+        return 'trigger_missing';
+    const failure = conditionsFailure(offer.conditions, view, 'price');
+    return failure === 'excluded' ? null : failure;
+}
+/** A oferta do documento nesta posição, com a variante do teste do visitante, contra esta linha. */
+function assessOffer(ctx, found, index) {
+    const line = ctx.input.cart[index];
+    const offerId = found.id;
+    const offer = liveOffer(ctx.doc, found, ctx.input);
+    const reason = lineFailure(ctx, offer, index);
+    if (reason)
+        return { priced: refused(index, offerId, reason), claim: null, placement: found.placement };
+    const storePrice = ctx.items.get(itemKey(offer.item)).price;
+    const offerPrice = offerUnitPrice(offer.price, storePrice);
+    const unitPrice = Math.min(offerPrice, line.unitPrice ?? storePrice);
+    const priced = {
+        index,
+        offerId,
+        status: 'ok',
+        unitPrice,
+        compareAtPrice: compareAtPrice(storePrice, unitPrice),
+        discountedQuantity: discountedQuantity(line.quantity, offer.maxQuantity, offerPrice),
+    };
+    return { priced, claim: { index, offer, order: ctx.doc.offers.indexOf(found) }, placement: found.placement };
+}
+/**
+ * A atribuição de posição de uma linha de oferta, a única do pacote. O id repetido em duas posições (oferta migrada do
+ * app) desempata pela posição da linha. Sem ela (ou com uma que não tem o id), vale a primeira posição, na ordem do
+ * documento, em que a oferta é elegível; nenhuma elegível, a primeira. Id que o documento não tem não fica em posição.
+ * A elegibilidade desse desempate é medida com as trocas cuja posição a linha já define (`declared`).
+ */
+function placeLines(declared) {
+    const placed = new Map();
+    declared.input.cart.forEach((line, index) => {
+        const options = line.offerId ? lineOptions(declared.doc, line) : [];
+        const pick = options.length > 1 ? options.find((offer) => assessOffer(declared, offer, index).claim !== null) : undefined;
+        const offer = pick ?? options[0];
+        if (offer)
+            placed.set(index, offer);
+    });
+    return placed;
+}
+/**
+ * Duas passadas: primeiro as trocas que a própria linha define (o id numa posição só, ou a posição da linha); com elas,
+ * a posição de cada linha de oferta; daí as trocas de fato (`replace` na posição atribuída), que valem para tudo.
+ */
+export function assessor(doc, items, input) {
+    const base = { doc, items, input };
+    const declaredOffer = (line) => {
+        const options = lineOptions(doc, line);
+        return options.length === 1 ? options[0] : undefined;
+    };
+    const declaredSwap = swapSet(input.cart, declaredOffer, (offer, line) => isLiveSwap(base, offer, line));
+    const placed = placeLines({ ...base, isSwap: declaredSwap, placed: new Map() });
+    const isSwap = swapSet(input.cart, (_, index) => placed.get(index), (offer, line) => isLiveSwap(base, offer, line));
+    return { ...base, isSwap, placed };
+}
+/** Toda linha com `offerId`, brinde ou não, na ordem do carrinho: é linha de oferta, e disputa a vaga da posição dela. */
+export function assessOfferLines(ctx) {
+    return ctx.input.cart.flatMap((line, index) => {
+        if (!line.offerId)
+            return [];
+        const offer = ctx.placed.get(index);
+        return [offer ? assessOffer(ctx, offer, index) : { priced: refused(index, line.offerId, 'unknown_offer'), claim: null, placement: null }];
+    });
+}

package/dist/cart.d.ts

@@ -8,23 +8,36 @@ export interface ResolvedLine {
     storeProductId: string | null;
     catalogProductIds: string[];
     durationDays: number | null;
+    /** Linha de troca vista como o item que ela trocou (o carrinho de antes da troca): não é alvo de outra troca. */
+    swapped: boolean;
 }
 /**
- * O carrinho do ponto de vista do motor. O gatilho é só o que a cliente escolheu: brinde e linha de oferta aceita ficam
- * fora, senão a oferta aceita vira gatilho da próxima ("a fila que não acaba", app ADR 0006). `keys` é o carrinho
- * inteiro: não se oferece o que ela já tem, venha de onde vier.
+ * O carrinho do ponto de vista do motor, **o de antes da troca**, o mesmo no `decide` e no `price` (pacote 0.3.2).
+ * O gatilho, o subtotal, a vaga extra e o combo são só o que a cliente escolheu: brinde e linha de oferta aceita ficam
+ * fora, senão a oferta aceita vira gatilho da próxima ("a fila que não acaba", app ADR 0006) ou sustenta o subtotal da
+ * outra. A **linha de troca** (`replace`) volta a ser o item trocado, com a quantidade dela: a vitrine decidiu com ele
+ * no carrinho, e a cobrança confere o mesmo carrinho. Linha com quantidade ou preço inválido não conta. `keys` é o
+ * carrinho inteiro, com o item trocado: não se oferece o que ela tem (ou acabou de trocar), venha de onde vier.
  */
 export interface CartView {
     chosen: ResolvedLine[];
-    accepted: ResolvedLine[];
     keys: Set<string>;
-    /** Mercadoria sem brinde, linhas de oferta inclusive. */
+    /** Mercadoria escolhida (as linhas de `chosen`), sem brinde nem linha de oferta. */
     subtotal: Cents;
 }
 export type ItemIndex = Map<string, OfferItem>;
 export declare function indexItems(doc: OfferDocument): ItemIndex;
-export declare function resolveLine(items: ItemIndex, line: CartLine): ResolvedLine;
-export declare function viewCart(items: ItemIndex, lines: CartLine[]): CartView;
+export declare function resolveLine(items: ItemIndex, line: CartLine, swapped?: boolean): ResolvedLine;
+/** Quantidade inteira ≥ 1 e, se vier, preço em centavos inteiros ≥ 0. A linha fora disso não é gatilho nem é cobrada. */
+export declare function isValidLine(line: CartLine): boolean;
+/** O item que a troca tirou, como linha; fora do documento, ele é do produto da loja da linha (a troca é no mesmo produto). */
+export declare function replacedLine(line: CartLine): CartLine | null;
+/** A linha diz que trocou um item do mesmo produto pelo ofertado. Só a forma: se a troca ainda vale é o `price` que diz. */
+export declare function isSameProductSwap(items: ItemIndex, line: CartLine): boolean;
+/** A linha nesta posição do carrinho é uma troca válida (`assess.ts`): no carrinho de antes, ela é o item trocado. */
+export type SwapCheck = (index: number) => boolean;
+/** `omit`: a posição da linha que fica de fora (a própria linha de oferta, na reconferência dela). */
+export declare function viewCart(items: ItemIndex, cart: CartLine[], isSwap: SwapCheck, omit?: number): CartView;
 export declare function lineMatches(match: ProductMatch, line: ResolvedLine): boolean;
 export declare function anyLineMatches(match: ProductMatch, lines: ResolvedLine[]): boolean;
 /**

package/dist/cart.js

@@ -2,7 +2,7 @@ export const itemKey = (ref) => `${ref.source}:${ref.variantId}`;
 export function indexItems(doc) {
     return new Map(doc.items.map((item) => [itemKey(item), item]));
 }
-export function resolveLine(items, line) {
+export function resolveLine(items, line, swapped = false) {
     const key = itemKey(line.item);
     const item = items.get(key);
     return {
@@ -11,20 +11,57 @@ export function resolveLine(items, line) {
         storeProductId: item?.storeProductId ?? line.storeProductId ?? null,
         catalogProductIds: item?.catalogProductIds ?? [],
         durationDays: item?.durationDays ?? null,
+        swapped,
     };
 }
+const isCents = (value) => Number.isSafeInteger(value) && value >= 0;
+/** Quantidade inteira ≥ 1 e, se vier, preço em centavos inteiros ≥ 0. A linha fora disso não é gatilho nem é cobrada. */
+export function isValidLine(line) {
+    return Number.isSafeInteger(line.quantity) && line.quantity >= 1 && (line.unitPrice === undefined || isCents(line.unitPrice));
+}
+/**
+ * Valor da linha no subtotal: o preço do **documento** quando o item está nele, o `unitPrice` da linha só quando não
+ * está (0 sem nenhum dos dois). O item trocado não tem linha no carrinho de depois; com o preço do documento para todo
+ * item listado, o `decide` (antes) e o `price` (depois) somam o mesmo.
+ */
 function lineTotal(items, line) {
-    const unit = line.unitPrice ?? items.get(itemKey(line.item))?.price ?? 0;
+    const unit = items.get(itemKey(line.item))?.price ?? line.unitPrice ?? 0;
     return unit * line.quantity;
 }
-export function viewCart(items, lines) {
-    const resolved = lines.map((line) => resolveLine(items, line));
-    return {
-        chosen: resolved.filter(({ line }) => !line.gift && !line.offerId),
-        accepted: resolved.filter(({ line }) => !line.gift && line.offerId),
-        keys: new Set(resolved.map(({ key }) => key)),
-        subtotal: lines.filter((line) => !line.gift).reduce((sum, line) => sum + lineTotal(items, line), 0),
-    };
+/** O item que a troca tirou, como linha; fora do documento, ele é do produto da loja da linha (a troca é no mesmo produto). */
+export function replacedLine(line) {
+    if (!line.replacedItem)
+        return null;
+    const product = line.storeProductId === undefined ? {} : { storeProductId: line.storeProductId };
+    return { item: line.replacedItem, quantity: line.quantity, ...product };
+}
+/** A linha diz que trocou um item do mesmo produto pelo ofertado. Só a forma: se a troca ainda vale é o `price` que diz. */
+export function isSameProductSwap(items, line) {
+    const replaced = replacedLine(line);
+    return replaced !== null && sameProduct(resolveLine(items, replaced), resolveLine(items, line));
+}
+/** A linha como o carrinho de antes da troca a vê: escolhida, trocada (o item que saiu) ou fora (oferta, brinde, inválida). */
+function chosenAs(items, line, swap) {
+    if (line.gift || !isValidLine(line))
+        return null;
+    const replaced = swap ? replacedLine(line) : null;
+    if (replaced)
+        return resolveLine(items, replaced, true);
+    return line.offerId ? null : resolveLine(items, line);
+}
+/** `omit`: a posição da linha que fica de fora (a própria linha de oferta, na reconferência dela). */
+export function viewCart(items, cart, isSwap, omit = -1) {
+    const chosen = [];
+    const keys = new Set();
+    cart.forEach((line, index) => {
+        keys.add(itemKey(line.item));
+        const seen = index === omit ? null : chosenAs(items, line, isSwap(index));
+        if (seen)
+            chosen.push(seen);
+        if (seen?.swapped)
+            keys.add(seen.key);
+    });
+    return { chosen, keys, subtotal: chosen.reduce((sum, { line }) => sum + lineTotal(items, line), 0) };
 }
 export function lineMatches(match, line) {
     if (match.items?.some((ref) => itemKey(ref) === line.key))

package/dist/conditions.d.ts

@@ -1,9 +1,17 @@
 import { type CartView } from './cart.js';
 import type { IneligibleReason } from './io.js';
-import type { Offer, OfferCondition } from './types.js';
+import type { Offer, OfferCondition, OfferItem } from './types.js';
 /** `excluded` só existe no `decide`: o "produto que esconde" esconde a oferta, mas não desfaz a já aceita (app ADR 0025). */
 export type GateFailure = IneligibleReason | 'excluded';
-export declare function validityFailure(offer: Offer, at: string): 'not_started' | 'expired' | null;
+/**
+ * O pacote conhece todos os tipos da oferta (condições, preço, ação). Documento publicado para um pacote mais novo
+ * pode trazer um tipo que este não sabe avaliar: a oferta não vale, em vez de passar ou cobrar `NaN`.
+ */
+export declare function isSupportedOffer(offer: Offer): boolean;
+/** Item vendável pela oferta: disponível e com preço da loja em centavos > 0 (sem ele a compilação grava 0, e a oferta sairia de graça). */
+export declare const isSellable: (item: OfferItem | undefined) => item is OfferItem;
+/** Validade: início inclusivo, fim exclusivo. Com validade, um instante ilegível (o `at` ou a própria validade) não vale. */
+export declare function validityFailure(offer: Offer, at: string): 'not_started' | 'expired' | 'invalid_instant' | null;
 /**
  * Toda oferta tem uma condição implícita: a cliente escolheu alguma coisa. A oferta "sempre" só aparece porque há
  * carrinho; sozinha (ou só com brinde) ela é o promocional se sustentando em nada (app, `cart-bump-orphan.test.js`).

package/dist/conditions.js

@@ -1,11 +1,29 @@
 import { anyLineMatches } from './cart.js';
+import { isKnownPrice } from './money.js';
+const CONDITION_TYPES = new Set(['cart_has_any', 'cart_has_none', 'subtotal_between']);
+const ACTIONS = new Set(['add', 'replace']);
+/**
+ * O pacote conhece todos os tipos da oferta (condições, preço, ação). Documento publicado para um pacote mais novo
+ * pode trazer um tipo que este não sabe avaliar: a oferta não vale, em vez de passar ou cobrar `NaN`.
+ */
+export function isSupportedOffer(offer) {
+    const quantity = offer.maxQuantity === undefined || (Number.isSafeInteger(offer.maxQuantity) && offer.maxQuantity >= 1);
+    return quantity && isKnownPrice(offer.price) && ACTIONS.has(offer.action) && offer.conditions.every((condition) => CONDITION_TYPES.has(condition.type));
+}
+/** Item vendável pela oferta: disponível e com preço da loja em centavos > 0 (sem ele a compilação grava 0, e a oferta sairia de graça). */
+export const isSellable = (item) => item !== undefined && item.available && Number.isSafeInteger(item.price) && item.price > 0;
+/** Validade: início inclusivo, fim exclusivo. Com validade, um instante ilegível (o `at` ou a própria validade) não vale. */
 export function validityFailure(offer, at) {
+    if (offer.validFrom === undefined && offer.validUntil === undefined)
+        return null;
     const now = Date.parse(at);
-    if (offer.validFrom !== undefined && now < Date.parse(offer.validFrom))
+    const from = offer.validFrom === undefined ? -Infinity : Date.parse(offer.validFrom);
+    const until = offer.validUntil === undefined ? Infinity : Date.parse(offer.validUntil);
+    if ([now, from, until].some(Number.isNaN))
+        return 'invalid_instant';
+    if (now < from)
         return 'not_started';
-    if (offer.validUntil !== undefined && now >= Date.parse(offer.validUntil))
-        return 'expired';
-    return null;
+    return now >= until ? 'expired' : null;
 }
 function conditionFailure(condition, view, mode) {
     if (condition.type === 'cart_has_any')
@@ -13,6 +31,8 @@ function conditionFailure(condition, view, mode) {
     if (condition.type === 'cart_has_none') {
         return mode === 'price' || !anyLineMatches(condition.match, view.chosen) ? null : 'excluded';
     }
+    if (condition.type !== 'subtotal_between')
+        return 'unsupported_offer';
     const { min, max } = condition;
     const inRange = (min === undefined || view.subtotal >= min) && (max === undefined || view.subtotal <= max);
     return inRange ? null : 'subtotal_out_of_range';

package/dist/decide.d.ts

@@ -2,7 +2,7 @@ import type { Decision, DecideInput } from './io.js';
 import type { OfferDocument } from './types.js';
 /**
  * As ofertas que valem para esta posição e este carrinho, com preço, tipo calculado e o teste sorteado. Respeita
- * condições, item disponível e fora do carrinho, vagas (e a vaga condicional), prioridade, um teste por posição e o
- * grupo de fora geral. Determinística: não lê relógio nem sorteia ao acaso.
+ * condições, item disponível e fora do carrinho, vagas (e a vaga condicional), prioridade e um teste por posição.
+ * Quem cai no grupo de fora geral (ADR-0047) não vê oferta nenhuma. Determinística: não lê relógio nem sorteia ao acaso.
  */
 export declare function decide(doc: OfferDocument, input: DecideInput): Decision;

package/dist/decide.js

@@ -1,37 +1,39 @@
+import { assessOfferLines, assessor, offerGate } from './assess.js';
 import { anyLineMatches, indexItems, itemKey, resolveLine, viewCart } from './cart.js';
-import { conditionsFailure, validityFailure } from './conditions.js';
+import { conditionsFailure, isSellable } from './conditions.js';
 import { placementOffers } from './effective.js';
-import { assignExperiment } from './experiments.js';
+import { assignExperiment, inHoldout } from './experiments.js';
 import { classify } from './kind.js';
 import { compareAtPrice, offerUnitPrice, pricePerDay } from './money.js';
 import { isSupportedSchema } from './schema-version.js';
 import { sha1Hex } from './sha1.js';
-/** Vagas deste carrinho: as da posição, mais a extra quando o carrinho escolhido casa (a 2ª vaga presa a produtos). */
-function slotsFor(placement, view) {
-    const extra = placement.extraSlot && anyLineMatches(placement.extraSlot.when, view.chosen) ? 1 : 0;
-    return placement.slots + extra;
-}
-/** A posição de onde veio uma linha aceita: a que ela declara, ou a da oferta com aquele id. */
-function acceptedPlacement(doc, line) {
-    return line.placement ?? doc.offers.find((offer) => offer.id === line.offerId)?.placement;
-}
+import { slotsFor } from './slots.js';
 /**
- * Vagas abertas: as do carrinho menos as ofertas já aceitas nesta posição (app ADR 0017). Aceitar uma e ver outra
- * nascer no lugar é a fila que não acaba; com duas vagas e uma aceita, fica a que já estava ao lado.
+ * Vagas abertas: as do carrinho menos as linhas de oferta atribuídas a esta posição (app ADR 0017), pela mesma regra
+ * do `price` (`assess.ts`). Aceitar uma e ver outra nascer no lugar é a fila que não acaba; com duas vagas e uma aceita,
+ * fica a que já estava ao lado. A linha que o `price` recusa ainda ocupa a vaga: a ponte pode cobrá-la cheia.
  */
 function openSlots(ctx) {
-    const accepted = ctx.view.accepted.filter(({ line }) => acceptedPlacement(ctx.doc, line) === ctx.placement.key).length;
-    return Math.max(0, slotsFor(ctx.placement, ctx.view) - accepted);
+    const taken = ctx.accepted.filter((assessed) => assessed.placement === ctx.placement.key).length;
+    return Math.max(0, slotsFor(ctx.placement, ctx.view) - taken);
+}
+/**
+ * O tipo pela linha escolhida do mesmo produto. A troca só mira linha escolhida de fato: a que já é troca (vista como o
+ * item que saiu) não tem linha no carrinho para a ponte trocar de novo.
+ */
+function classifyOffer(ctx, offer) {
+    const pool = offer.action === 'replace' ? ctx.view.chosen.filter((line) => !line.swapped) : ctx.view.chosen;
+    return classify(resolveLine(ctx.items, { item: offer.item, quantity: 1 }), pool);
 }
 function candidate(ctx, offer) {
-    if (!offer.active || validityFailure(offer, ctx.at))
+    if (offerGate(offer, ctx.at))
         return null;
     const item = ctx.items.get(itemKey(offer.item));
-    if (!item?.available || ctx.view.keys.has(itemKey(offer.item)))
+    if (!isSellable(item) || ctx.view.keys.has(itemKey(offer.item)))
         return null;
     if (conditionsFailure(offer.conditions, ctx.view, 'decide'))
         return null;
-    const classification = classify(resolveLine(ctx.items, { item: offer.item, quantity: 1 }), ctx.view.chosen);
+    const classification = classifyOffer(ctx, offer);
     if (offer.action === 'replace' && !classification.target)
         return null;
     return { offer, item, classification };
@@ -58,23 +60,26 @@ function groupingFor(ctx) {
     const groupings = ctx.variant?.groupings ?? ctx.placement.groupings ?? [];
     return groupings.find((grouping) => anyLineMatches(grouping.when, ctx.view.chosen))?.presentation ?? null;
 }
+/** A linha com tudo o que muda a decisão (troca, posição, produto, preço), sem depender da ordem do carrinho. */
+function lineKey(line) {
+    const replaced = line.replacedItem ? itemKey(line.replacedItem) : '';
+    return JSON.stringify([itemKey(line.item), line.quantity, line.unitPrice ?? null, line.offerId ?? '', line.placement ?? '', replaced, line.storeProductId ?? '', line.gift ? 1 : 0]);
+}
 /**
- * Mesmo documento, carrinho, visitante e resposta = mesmo id (ADR-0083 §1, princípio 3). O instante não entra: duas
+ * Mesma pergunta e mesma resposta = mesmo id (ADR-0083 §1, princípio 3); resposta diferente, outro (pacote 0.3.2: o
+ * hash leva a resposta inteira, com preço, alvo da troca e conteúdo de cada oferta). O instante não entra: duas
  * perguntas iguais seguidas são a mesma decisão. A ordem das linhas também não.
  */
-function decisionIdOf(input, version, offerIds, experiments) {
-    const cart = input.cart
-        .map((line) => [itemKey(line.item), line.quantity, line.offerId ?? '', line.gift ? 1 : 0].join('*'))
-        .sort();
-    const canonical = JSON.stringify([version, input.placement, input.visitorId ?? '', cart, offerIds, experiments]);
-    return `dec_${sha1Hex(canonical).slice(0, 24)}`;
+function withDecisionId(input, version, answer) {
+    const cart = input.cart.map(lineKey).sort();
+    const decisionId = `dec_${sha1Hex(JSON.stringify([version, input.placement, input.visitorId ?? '', cart, answer])).slice(0, 24)}`;
+    return { ...answer, decisionId, offers: answer.offers.map((offer) => ({ ...offer, decisionId })) };
 }
-function toDecided(ctx, pick, slot, decisionId) {
+function toDecided(ctx, pick, slot) {
     const { offer, item, classification } = pick;
     const price = offerUnitPrice(offer.price, item.price);
     return {
         offerId: offer.id,
-        decisionId,
         placement: ctx.placement.key,
         slot,
         kind: classification.kind,
@@ -95,37 +100,40 @@ function placementPresentation(ctx) {
 }
 /**
  * Posição desconhecida responde vazio (a ponte ainda manda o `exposed`), nunca erro. Documento de formato mais novo
- * também responde vazio, com `status: 'unsupported_schema'`, para a ponte saber que precisa atualizar o pacote.
+ * também responde vazio, com `status: 'unsupported_schema'`, para a ponte saber que precisa atualizar o pacote. O
+ * grupo de fora geral responde vazio com `holdout: true`.
  */
-function emptyDecision(doc, input, status) {
-    const decisionId = decisionIdOf(input, doc.version, [], []);
-    return { status, version: doc.version, placement: input.placement, decisionId, offers: [], presentation: null, grouping: null, experiments: [] };
+function emptyDecision(doc, input, status, holdout = false) {
+    return withDecisionId(input, doc.version, { status, version: doc.version, placement: input.placement, offers: [], presentation: null, grouping: null, experiments: [], holdout });
 }
 /**
  * As ofertas que valem para esta posição e este carrinho, com preço, tipo calculado e o teste sorteado. Respeita
- * condições, item disponível e fora do carrinho, vagas (e a vaga condicional), prioridade, um teste por posição e o
- * grupo de fora geral. Determinística: não lê relógio nem sorteia ao acaso.
+ * condições, item disponível e fora do carrinho, vagas (e a vaga condicional), prioridade e um teste por posição.
+ * Quem cai no grupo de fora geral (ADR-0047) não vê oferta nenhuma. Determinística: não lê relógio nem sorteia ao acaso.
  */
 export function decide(doc, input) {
     if (!isSupportedSchema(doc.schemaVersion))
         return emptyDecision(doc, input, 'unsupported_schema');
+    if (input.visitorId && inHoldout(doc.holdout, input.visitorId))
+        return emptyDecision(doc, input, 'ok', true);
     const placement = doc.placements.find((candidatePlacement) => candidatePlacement.key === input.placement);
     if (!placement)
         return emptyDecision(doc, input, 'ok');
     const assignment = assignExperiment(doc, placement.key, input);
     const items = indexItems(doc);
-    const ctx = { doc, items, view: viewCart(items, input.cart), placement, variant: assignment?.variant ?? null, at: input.at };
+    const assess = assessor(doc, items, input);
+    const view = viewCart(items, input.cart, assess.isSwap);
+    const ctx = { doc, items, view, accepted: assessOfferLines(assess), placement, variant: assignment?.variant ?? null, at: input.at };
     const picks = pickOffers(ctx);
     const experiments = assignment ? [{ key: assignment.experiment.key, variant: assignment.variant.key }] : [];
-    const decisionId = decisionIdOf(input, doc.version, picks.map((pick) => pick.offer.id), experiments);
-    return {
+    return withDecisionId(input, doc.version, {
         status: 'ok',
         version: doc.version,
         placement: placement.key,
-        decisionId,
-        offers: picks.map((pick, index) => toDecided(ctx, pick, index + 1, decisionId)),
+        offers: picks.map((pick, index) => toDecided(ctx, pick, index + 1)),
         presentation: placementPresentation(ctx),
         grouping: groupingFor(ctx),
         experiments,
-    };
+        holdout: false,
+    });
 }

package/dist/io.d.ts

@@ -2,18 +2,31 @@ import type { Cents, ItemRef, OfferAction, OfferContent } from './types.js';
 /** Uma linha do carrinho como a ponte a vê. */
 export interface CartLine {
     item: ItemRef;
+    /** Inteiro ≥ 1; fora disso a linha não é gatilho nem entra no subtotal, e a linha de oferta volta `invalid_line`. */
     quantity: number;
-    /** O que a loja cobra por unidade agora; sem ele vale o preço do item no documento (0 se ele não estiver lá). */
+    /**
+     * O que a loja cobra por unidade agora (centavos inteiros ≥ 0; fora disso, como `quantity`). Teto do preço da linha
+     * de oferta. No subtotal só vale para item **fora** do documento: o item listado conta pelo preço do documento, o
+     * mesmo que o item trocado (que já saiu do carrinho) tem, para o `decide` e o `price` somarem igual.
+     */
     unitPrice?: Cents;
-    /** Produto da loja da linha, para o item que o documento não lista (o produto que a cliente escolheu). */
+    /**
+     * Produto da loja da linha, para o item que o documento não lista (o produto que a cliente escolheu). Na linha de
+     * troca, vale também para o `replacedItem` fora do documento: a troca é dentro do mesmo produto.
+     */
     storeProductId?: string;
     /** Linha de oferta aceita: leva o `offerId` até o pedido (ADR-0083 §1, princípio 4). Não é gatilho de outra oferta. */
     offerId?: string;
-    /** A posição de onde a oferta aceita veio; desempata o id repetido em duas posições. */
+    /** A posição de onde a oferta aceita veio (o `placement` da `DecidedOffer`); desempata o id repetido em duas posições. */
     placement?: string;
-    /** Na ação `replace`: o item que a oferta trocou. `price()` confere a condição como se ele ainda estivesse lá. */
+    /**
+     * Na ação `replace`: o item que a oferta trocou. O motor avalia o **carrinho de antes da troca** (pacote 0.3.2): para
+     * todas as ofertas, a própria e as outras, a linha de troca volta a ser este item, com a quantidade dela (gatilho,
+     * `cart_has_none`, subtotal pelo preço do documento, vaga extra, combo). A linha em si ocupa a vaga da posição dela.
+     * Só é troca quando a oferta `replace` com o `offerId` está na posição da linha (a dela, ou a da regra de posição).
+     */
     replacedItem?: ItemRef;
-    /** Brinde: não é escolha da cliente nem entra no subtotal. */
+    /** Brinde: não é escolha da cliente nem entra no subtotal. Com `offerId`, segue linha de oferta e ocupa a vaga. */
     gift?: boolean;
 }
 export interface DecideInput {
@@ -50,7 +63,10 @@ export interface DecidedOffer {
     pricePerDay: Cents | null;
     currency: string;
     action: OfferAction;
-    /** O item que a cliente leva e a oferta troca, na ação `replace`. */
+    /**
+     * O item que a cliente leva e a oferta troca, na ação `replace`: a linha escolhida do mesmo produto (nunca uma que já
+     * é troca) de menor duração, e no empate a de menor chave de item, sem depender da ordem das linhas.
+     */
     replaces: ItemRef | null;
     content: OfferContent;
     presentation: string | null;
@@ -61,7 +77,11 @@ export interface Decision {
     status: ResultStatus;
     version: number;
     placement: string;
-    /** Mesmo documento, carrinho, visitante e resposta = mesmo id. Sai também sem oferta (para o `exposed`). */
+    /**
+     * sha1 da versão, posição, visitante, carrinho (sem ordem) e da **resposta inteira** (ofertas com preço, alvo da
+     * troca, conteúdo; apresentação, combo, teste): mesma pergunta e mesma resposta = mesmo id; resposta diferente, outro.
+     * Sai também sem oferta (para o `exposed`).
+     */
     decisionId: string;
     offers: DecidedOffer[];
     /** Apresentação padrão da posição (já com a variante do teste). */
@@ -69,24 +89,46 @@ export interface Decision {
     /** Apresentação de grupo (combo) quando vale para este carrinho. */
     grouping: string | null;
     experiments: ExperimentAssignment[];
+    /**
+     * O visitante caiu no grupo de fora geral (ADR-0047): nenhuma oferta, e a ponte manda o `exposed` do controle geral.
+     * Sem `visitorId` é sempre `false`.
+     */
+    holdout: boolean;
 }
 export interface PriceInput {
     cart: CartLine[];
-    /** O mesmo do `decide`: a variante do teste é sorteada de novo por ele. */
+    /**
+     * Sempre o mesmo do `decide`: a variante do teste é sorteada de novo por ele, e o grupo de fora geral conferido. Sem
+     * ele, nem teste nem grupo de fora valem (cobra o documento sem variante).
+     */
     visitorId?: string;
     /** As mesmas do `decide`: sem elas, o teste congelado cobra o documento sem mudança. */
     assignments?: ExperimentAssignment[];
     at: string;
 }
 export type IneligibleReason = 'unknown_offer' | 'inactive' | 'item_mismatch' | 'not_started' | 'expired' | 'trigger_missing' | 'subtotal_out_of_range'
+/** O item oferecido está indisponível ou sem preço da loja (0) no documento: nunca sai de graça por falta de preço. */
+ | 'unavailable'
+/** O visitante está no grupo de fora geral: não leva oferta nenhuma. */
+ | 'holdout'
+/** A posição já tem as vagas tomadas por ofertas de prioridade maior, ou a mesma oferta (ou item) em outra linha. */
+ | 'no_slot'
+/** Condição, preço ou ação de um tipo que este pacote não conhece: atualize o pacote. */
+ | 'unsupported_offer'
+/** O `at` (ou a validade da oferta) não é um instante legível, e a oferta tem validade. */
+ | 'invalid_instant'
 /** O documento é de um formato mais novo que o pacote: toda linha volta com este motivo. */
- | 'unsupported_schema';
+ | 'unsupported_schema'
+/** A linha tem `quantity` que não é inteiro ≥ 1, ou `unitPrice` que não é centavo inteiro ≥ 0 (pacote 0.3.2). */
+ | 'invalid_line';
 export type PricedLine = {
     index: number;
     offerId: string;
     status: 'ok';
     unitPrice: Cents;
     compareAtPrice: Cents | null;
+    /** Quantas unidades da linha levam o `unitPrice` (o `maxQuantity` da oferta); o resto vai a preço cheio. */
+    discountedQuantity: number;
 } | {
     index: number;
     offerId: string;

package/dist/kind.d.ts

@@ -9,7 +9,8 @@ export interface Classification {
 }
 /**
  * Tipo calculado, nunca cadastrado (ADR-0083 §3; a mesma regra do `offerKindExpr` da análise): upsell quando o carrinho
- * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo.
+ * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo. Com mais de uma
+ * linha do mesmo produto, o alvo (o que a `replace` troca) é a de menor duração, e no empate a de menor chave de item.
  */
 export declare function classify(offered: ResolvedLine, chosen: ResolvedLine[]): Classification;
 /**

package/dist/kind.js

@@ -6,12 +6,20 @@ function directionOf(offered, target) {
         return null;
     return offered.durationDays > target.durationDays ? 'up' : 'down';
 }
+/** Menor duração primeiro (sem duração por último), depois a chave do item: o alvo não depende da ordem das linhas. */
+function byTarget(a, b) {
+    const byDuration = (a.durationDays ?? Number.MAX_SAFE_INTEGER) - (b.durationDays ?? Number.MAX_SAFE_INTEGER);
+    if (byDuration !== 0)
+        return byDuration;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+}
 /**
  * Tipo calculado, nunca cadastrado (ADR-0083 §3; a mesma regra do `offerKindExpr` da análise): upsell quando o carrinho
- * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo.
+ * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo. Com mais de uma
+ * linha do mesmo produto, o alvo (o que a `replace` troca) é a de menor duração, e no empate a de menor chave de item.
  */
 export function classify(offered, chosen) {
-    const target = chosen.find((line) => sameProduct(offered, line)) ?? null;
+    const target = chosen.filter((line) => sameProduct(offered, line)).sort(byTarget)[0] ?? null;
     if (!target)
         return { kind: 'cross_sell', direction: null, target: null };
     return { kind: 'upsell', direction: directionOf(offered, target), target };
@@ -22,8 +30,8 @@ function triggerLines(items, offer) {
     const matches = offer.conditions.flatMap((condition) => (condition.type === 'cart_has_any' ? [condition.match] : []));
     return matches.flatMap((match) => [
         ...(match.items ?? []).map((item) => resolveLine(items, { item, quantity: 1 })),
-        ...(match.storeProductIds ?? []).map((id) => ({ line: BLANK_LINE, key: '', storeProductId: id, catalogProductIds: [], durationDays: null })),
-        ...(match.catalogProductIds ?? []).map((id) => ({ line: BLANK_LINE, key: '', storeProductId: null, catalogProductIds: [id], durationDays: null })),
+        ...(match.storeProductIds ?? []).map((id) => ({ line: BLANK_LINE, key: '', storeProductId: id, catalogProductIds: [], durationDays: null, swapped: false })),
+        ...(match.catalogProductIds ?? []).map((id) => ({ line: BLANK_LINE, key: '', storeProductId: null, catalogProductIds: [id], durationDays: null, swapped: false })),
     ]);
 }
 /**

package/dist/money.d.ts

@@ -1,8 +1,16 @@
 import type { Cents, OfferPrice } from './types.js';
+/** O preço é de um tipo que o pacote sabe calcular, com inteiro no campo do valor (centavos; pontos-base até 100%). */
+export declare function isKnownPrice(price: OfferPrice): boolean;
+/**
+ * Quantas unidades da linha levam o preço da oferta: o `maxQuantity` da oferta; sem ele, **1** quando a oferta sai de
+ * graça (brinde) e a linha toda nos outros casos. O resto da linha vai a preço cheio.
+ */
+export declare function discountedQuantity(quantity: number, maxQuantity: number | undefined, offerPrice: Cents): number;
 /**
  * Preço da oferta por unidade, a partir do preço da loja. O desconto percentual é arredondado meio para cima (15% de
  * 79,90 = 11,985 → 11,99, cobra 67,91). A oferta é **teto**, nunca acréscimo: o resultado fica entre 0 e o preço da
- * loja (preço fixo acima da loja cobra o da loja, desconto maior que o preço vira grátis).
+ * loja (preço fixo acima da loja cobra o da loja, desconto maior que o preço vira grátis). Tipo que o pacote não
+ * conhece não desconta: devolve o preço da loja, nunca `NaN` (o `decide`/`price` nem chegam a usar essa oferta).
  */
 export declare function offerUnitPrice(price: OfferPrice, storePrice: Cents): Cents;
 /** O preço "de": o da loja, só quando há o que riscar. */

package/dist/money.js

@@ -2,12 +2,32 @@
 function divideHalfUp(numerator, denominator) {
     return Math.floor((2 * numerator + denominator) / (2 * denominator));
 }
+const isWhole = (value, max = Number.MAX_SAFE_INTEGER) => Number.isSafeInteger(value) && value >= 0 && value <= max;
+/** O preço é de um tipo que o pacote sabe calcular, com inteiro no campo do valor (centavos; pontos-base até 100%). */
+export function isKnownPrice(price) {
+    if (price.type === 'percent_off')
+        return isWhole(price.basisPoints, 10_000);
+    if (price.type === 'fixed' || price.type === 'amount_off')
+        return isWhole(price.amount);
+    return false;
+}
+/**
+ * Quantas unidades da linha levam o preço da oferta: o `maxQuantity` da oferta; sem ele, **1** quando a oferta sai de
+ * graça (brinde) e a linha toda nos outros casos. O resto da linha vai a preço cheio.
+ */
+export function discountedQuantity(quantity, maxQuantity, offerPrice) {
+    const cap = maxQuantity ?? (offerPrice === 0 ? 1 : quantity);
+    return Math.min(quantity, cap);
+}
 /**
  * Preço da oferta por unidade, a partir do preço da loja. O desconto percentual é arredondado meio para cima (15% de
  * 79,90 = 11,985 → 11,99, cobra 67,91). A oferta é **teto**, nunca acréscimo: o resultado fica entre 0 e o preço da
- * loja (preço fixo acima da loja cobra o da loja, desconto maior que o preço vira grátis).
+ * loja (preço fixo acima da loja cobra o da loja, desconto maior que o preço vira grátis). Tipo que o pacote não
+ * conhece não desconta: devolve o preço da loja, nunca `NaN` (o `decide`/`price` nem chegam a usar essa oferta).
  */
 export function offerUnitPrice(price, storePrice) {
+    if (!isKnownPrice(price))
+        return storePrice;
     const raw = price.type === 'fixed'
         ? price.amount
         : price.type === 'amount_off'

package/dist/price.d.ts

@@ -3,8 +3,11 @@ import type { OfferDocument } from './types.js';
 /**
  * O preço de cada linha de oferta aceita, **conferindo as condições de novo** com o carrinho real (ADR-0083 §1,
  * princípio 2, e §6). Linha que perdeu a condição volta `ineligible` com o motivo, e a ponte escolhe remover ou cobrar
- * o preço cheio. Documento de formato mais novo que o pacote não é precificado: toda linha volta `unsupported_schema`.
- * A variante do teste é sorteada de novo pelo visitante (com as mesmas `assignments`), a mesma que o `decide` deu. O "produto que
- * esconde" (`cart_has_none`) não é conferido aqui: esconder não desfaz a oferta já aceita (app ADR 0025).
+ * o preço cheio. A reconferência usa o carrinho de antes da troca, o mesmo do `decide` (linha de oferta não sustenta
+ * outra; a de troca volta a ser o item trocado) e as vagas da posição, na ordem de prioridade. Cada linha `ok` diz em
+ * `discountedQuantity` quantas unidades levam o preço da oferta (`maxQuantity`); o resto vai a preço cheio. Documento de formato mais novo que o
+ * pacote não é precificado: toda linha volta `unsupported_schema`; visitante do grupo de fora geral, `holdout`. A
+ * variante do teste é sorteada de novo pelo visitante (com as mesmas `assignments`), a mesma que o `decide` deu. O
+ * "produto que esconde" (`cart_has_none`) não é conferido aqui: esconder não desfaz a oferta já aceita (app ADR 0025).
  */
 export declare function price(doc: OfferDocument, input: PriceInput): PriceResult;

package/dist/price.js

@@ -1,77 +1,34 @@
-import { indexItems, itemKey, resolveLine, sameProduct, viewCart } from './cart.js';
-import { conditionsFailure, validityFailure } from './conditions.js';
-import { applyVariant } from './effective.js';
-import { assignExperiment } from './experiments.js';
-import { compareAtPrice, offerUnitPrice } from './money.js';
+import { assessOfferLines, assessor, refused } from './assess.js';
+import { indexItems, viewCart } from './cart.js';
+import { inHoldout } from './experiments.js';
 import { isSupportedSchema } from './schema-version.js';
-/** O id repetido em duas posições (oferta migrada do app) desempata pela posição da linha; sem ela, vale a primeira. */
-function findOffer(doc, line) {
-    const same = doc.offers.filter((offer) => offer.id === line.offerId);
-    return same.find((offer) => offer.placement === line.placement) ?? same[0];
+import { slotLosers } from './slots.js';
+/** As linhas que passaram disputam as vagas da posição; quem fica de fora volta `no_slot`. */
+function withSlots(ctx, assessed) {
+    const view = viewCart(ctx.items, ctx.input.cart, ctx.isSwap);
+    const claims = assessed.flatMap(({ claim }) => (claim ? [claim] : []));
+    const losers = slotLosers(ctx.doc, view, claims);
+    return assessed.map(({ priced }) => (losers.has(priced.index) ? refused(priced.index, priced.offerId, 'no_slot') : priced));
 }
-/**
- * O carrinho como no instante em que a oferta apareceu: sem a própria linha (senão uma oferta por valor mínimo se
- * sustenta sozinha, o preço dela empurra o subtotal que ela exige) e, no `replace`, com o item trocado de volta no
- * lugar. Nulo quando o `replace` não diz o que trocou, ou diz um item que não é o mesmo produto.
- */
-function recheckView(ctx, offer, index) {
-    const line = ctx.input.cart[index];
-    const others = ctx.input.cart.filter((_, position) => position !== index);
-    if (offer.action === 'add')
-        return viewCart(ctx.items, others);
-    if (!line.replacedItem)
-        return null;
-    const replaced = { item: line.replacedItem, quantity: line.quantity };
-    if (!sameProduct(resolveLine(ctx.items, replaced), resolveLine(ctx.items, line)))
-        return null;
-    return viewCart(ctx.items, [...others, replaced]);
-}
-function lineFailure(ctx, offer, index) {
-    const line = ctx.input.cart[index];
-    if (!offer.active)
-        return 'inactive';
-    if (!ctx.items.has(itemKey(offer.item)))
-        return 'unknown_offer';
-    if (itemKey(line.item) !== itemKey(offer.item))
-        return 'item_mismatch';
-    const validity = validityFailure(offer, ctx.input.at);
-    if (validity)
-        return validity;
-    const view = recheckView(ctx, offer, index);
-    if (!view)
-        return 'trigger_missing';
-    const failure = conditionsFailure(offer.conditions, view, 'price');
-    return failure === 'excluded' ? null : failure;
-}
-function priceLine(ctx, line, index) {
-    const offerId = line.offerId;
-    const found = findOffer(ctx.doc, line);
-    if (!found)
-        return { index, offerId, status: 'ineligible', reason: 'unknown_offer' };
-    const assignment = assignExperiment(ctx.doc, found.placement, ctx.input);
-    const offer = applyVariant(found, assignment?.variant ?? null);
-    const reason = lineFailure(ctx, offer, index);
-    if (reason)
-        return { index, offerId, status: 'ineligible', reason };
-    const storePrice = ctx.items.get(itemKey(offer.item)).price;
-    const charged = line.unitPrice ?? storePrice;
-    const unitPrice = Math.min(offerUnitPrice(offer.price, storePrice), charged);
-    return { index, offerId, status: 'ok', unitPrice, compareAtPrice: compareAtPrice(charged, unitPrice) };
+function refuseAll(cart, reason) {
+    return cart.flatMap((line, index) => (line.offerId ? [refused(index, line.offerId, reason)] : []));
 }
 /**
  * O preço de cada linha de oferta aceita, **conferindo as condições de novo** com o carrinho real (ADR-0083 §1,
  * princípio 2, e §6). Linha que perdeu a condição volta `ineligible` com o motivo, e a ponte escolhe remover ou cobrar
- * o preço cheio. Documento de formato mais novo que o pacote não é precificado: toda linha volta `unsupported_schema`.
- * A variante do teste é sorteada de novo pelo visitante (com as mesmas `assignments`), a mesma que o `decide` deu. O "produto que
- * esconde" (`cart_has_none`) não é conferido aqui: esconder não desfaz a oferta já aceita (app ADR 0025).
+ * o preço cheio. A reconferência usa o carrinho de antes da troca, o mesmo do `decide` (linha de oferta não sustenta
+ * outra; a de troca volta a ser o item trocado) e as vagas da posição, na ordem de prioridade. Cada linha `ok` diz em
+ * `discountedQuantity` quantas unidades levam o preço da oferta (`maxQuantity`); o resto vai a preço cheio. Documento de formato mais novo que o
+ * pacote não é precificado: toda linha volta `unsupported_schema`; visitante do grupo de fora geral, `holdout`. A
+ * variante do teste é sorteada de novo pelo visitante (com as mesmas `assignments`), a mesma que o `decide` deu. O
+ * "produto que esconde" (`cart_has_none`) não é conferido aqui: esconder não desfaz a oferta já aceita (app ADR 0025).
  */
 export function price(doc, input) {
     const head = { version: doc.version, currency: doc.currency };
-    if (!isSupportedSchema(doc.schemaVersion)) {
-        const lines = input.cart.flatMap((line, index) => line.offerId ? [{ index, offerId: line.offerId, status: 'ineligible', reason: 'unsupported_schema' }] : []);
-        return { status: 'unsupported_schema', ...head, lines };
-    }
-    const ctx = { doc, items: indexItems(doc), input };
-    const lines = input.cart.flatMap((line, index) => (line.offerId ? [priceLine(ctx, line, index)] : []));
-    return { status: 'ok', ...head, lines };
+    if (!isSupportedSchema(doc.schemaVersion))
+        return { status: 'unsupported_schema', ...head, lines: refuseAll(input.cart, 'unsupported_schema') };
+    if (input.visitorId && inHoldout(doc.holdout, input.visitorId))
+        return { status: 'ok', ...head, lines: refuseAll(input.cart, 'holdout') };
+    const ctx = assessor(doc, indexItems(doc), input);
+    return { status: 'ok', ...head, lines: withSlots(ctx, assessOfferLines(ctx)) };
 }

package/dist/schema-version.d.ts

@@ -4,5 +4,6 @@
  * precificado: a resposta diz `unsupported_schema` e a ponte sabe que precisa atualizar o pacote, em vez de cobrar
  * com uma regra que não conhece.
  */
-export declare const SUPPORTED_SCHEMA_VERSION = 1;
+/** 2 = pacote 0.3.2: brinde vale 1 unidade por padrão e `maxQuantity` limita as unidades com desconto. */
+export declare const SUPPORTED_SCHEMA_VERSION = 2;
 export declare function isSupportedSchema(schemaVersion: number): boolean;

package/dist/schema-version.js

@@ -4,7 +4,8 @@
  * precificado: a resposta diz `unsupported_schema` e a ponte sabe que precisa atualizar o pacote, em vez de cobrar
  * com uma regra que não conhece.
  */
-export const SUPPORTED_SCHEMA_VERSION = 1;
+/** 2 = pacote 0.3.2: brinde vale 1 unidade por padrão e `maxQuantity` limita as unidades com desconto. */
+export const SUPPORTED_SCHEMA_VERSION = 2;
 export function isSupportedSchema(schemaVersion) {
     return Number.isInteger(schemaVersion) && schemaVersion >= 1 && schemaVersion <= SUPPORTED_SCHEMA_VERSION;
 }

package/dist/slots.d.ts

@@ -0,0 +1,15 @@
+import { type CartView } from './cart.js';
+import type { Offer, OfferDocument, Placement } from './types.js';
+/** Vagas deste carrinho: as da posição, mais a extra quando o carrinho escolhido casa (a 2ª vaga presa a produtos). */
+export declare function slotsFor(placement: Placement, view: CartView): number;
+/** Uma linha de oferta que passou em tudo e pede vaga: a posição no carrinho, a oferta e a ordem dela no documento. */
+export interface SlotClaim {
+    index: number;
+    offer: Offer;
+    order: number;
+}
+/**
+ * As linhas que ficam sem vaga, a regra do `decide` na cobrança: por posição, na ordem de prioridade, até as vagas do
+ * carrinho (com a extra); a mesma oferta ou o mesmo item numa segunda linha não ganha outra vaga.
+ */
+export declare function slotLosers(doc: OfferDocument, view: CartView, claims: SlotClaim[]): Set<number>;

package/dist/slots.js

@@ -0,0 +1,29 @@
+import { anyLineMatches, itemKey } from './cart.js';
+/** Vagas deste carrinho: as da posição, mais a extra quando o carrinho escolhido casa (a 2ª vaga presa a produtos). */
+export function slotsFor(placement, view) {
+    const extra = placement.extraSlot && anyLineMatches(placement.extraSlot.when, view.chosen) ? 1 : 0;
+    return placement.slots + extra;
+}
+const byPriority = (a, b) => a.offer.priority - b.offer.priority || a.order - b.order || a.index - b.index;
+/**
+ * As linhas que ficam sem vaga, a regra do `decide` na cobrança: por posição, na ordem de prioridade, até as vagas do
+ * carrinho (com a extra); a mesma oferta ou o mesmo item numa segunda linha não ganha outra vaga.
+ */
+export function slotLosers(doc, view, claims) {
+    const losers = new Set();
+    const used = new Map();
+    const seen = new Set();
+    for (const claim of [...claims].sort(byPriority)) {
+        const key = claim.offer.placement;
+        const placement = doc.placements.find((candidate) => candidate.key === key);
+        const marks = [`${key}|offer|${claim.offer.id}`, `${key}|item|${itemKey(claim.offer.item)}`];
+        const taken = used.get(key) ?? 0;
+        if (!placement || taken >= slotsFor(placement, view) || marks.some((mark) => seen.has(mark))) {
+            losers.add(claim.index);
+            continue;
+        }
+        used.set(key, taken + 1);
+        marks.forEach((mark) => seen.add(mark));
+    }
+    return losers;
+}

package/dist/types.d.ts

@@ -82,6 +82,12 @@ export interface Offer {
     /** Nome do visual que a ponte implementa; sem ele vale o da posição. */
     presentation?: string;
     conditions: OfferCondition[];
+    /**
+     * Quantas unidades da linha levam o preço da oferta (inteiro ≥ 1, pacote 0.3.2); o resto vai a preço cheio. Ausente:
+     * **1** quando o preço da oferta dá 0 (brinde), a linha toda nos outros casos. O `price` devolve a conta em
+     * `discountedQuantity`.
+     */
+    maxQuantity?: number;
     /** Instantes ISO com offset; início inclusivo, fim exclusivo. */
     validFrom?: string;
     validUntil?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zolve/offers",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Motor de ofertas headless (ADR-0083): tipos do documento publicado, decide() e price(), sorteio A/B do PostHog. Sem dependências de runtime, para caber numa Shopify Function",
   "type": "module",
   "sideEffects": false,