@zolve/offers 0.3.0 → 0.3.1

package/README.md

@@ -16,9 +16,13 @@ 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 } | { status: 'ineligible', reason }
 ```
 
+`unitPrice` é por unidade e vale para a **quantidade toda** da linha (duas unidades da oferta custam duas vezes o
+preço da oferta), como a function de desconto do app sempre cobrou (`appliesToEachItem`). `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 +53,46 @@ 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): é o que a cliente leva no lugar do que escolheu e conta como
+  escolhida para as **outras** ofertas. Para a própria troca vale o item trocado, nunca a linha dela (não se sustenta
+  com o próprio preço). 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 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.
+
+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 |
+
 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,27 @@
+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.
+ */
+export interface Assessor {
+    doc: OfferDocument;
+    items: ItemIndex;
+    input: PriceInput;
+    isSwap: SwapCheck;
+}
+/** 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;
+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,99 @@
+import { isSameProductSwap, itemKey, replacedLine, viewCart } from './cart.js';
+import { conditionsFailure, isSupportedOffer, validityFailure } from './conditions.js';
+import { applyVariant } from './effective.js';
+import { assignExperiment } from './experiments.js';
+import { compareAtPrice, 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);
+}
+/**
+ * Linha de troca: uma oferta `replace` do documento com aquele id e aquele item, que passa no portão (com a variante
+ * do visitante e o `at`), e o item trocado do mesmo produto. Forjar os campos só rende o que o caminho legítimo daria;
+ * a troca desligada, vencida ou de tipo desconhecido é linha de oferta comum, e não sustenta outra oferta.
+ */
+function swapCheck(doc, items, input) {
+    const isLiveReplace = (offer, line) => offer.id === line.offerId && offer.action === 'replace' && itemKey(offer.item) === itemKey(line.item) && offerGate(liveOffer(doc, offer, input), input.at) === null;
+    return (line) => line.offerId !== undefined && isSameProductSwap(items, line) && doc.offers.some((offer) => isLiveReplace(offer, line));
+}
+export function assessor(doc, items, input) {
+    return { doc, items, input, isSwap: swapCheck(doc, items, input) };
+}
+/**
+ * O carrinho como no instante em que a oferta apareceu: só o que a cliente escolheu (com as linhas de troca), sem a
+ * própria linha 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, ctx.isSwap);
+    const replaced = replacedLine(line);
+    if (!replaced || !isSameProductSwap(ctx.items, line))
+        return null;
+    return viewCart(ctx.items, [...others, replaced], ctx.isSwap);
+}
+function lineFailure(ctx, offer, index) {
+    const line = ctx.input.cart[index];
+    if (!isSupportedOffer(offer))
+        return 'unsupported_offer';
+    if (!offer.active)
+        return 'inactive';
+    const item = ctx.items.get(itemKey(offer.item));
+    if (!item)
+        return 'unknown_offer';
+    if (itemKey(line.item) !== itemKey(offer.item))
+        return 'item_mismatch';
+    if (!item.available || item.price <= 0)
+        return 'unavailable';
+    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;
+}
+/** 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 unitPrice = Math.min(offerUnitPrice(offer.price, storePrice), line.unitPrice ?? storePrice);
+    const priced = { index, offerId, status: 'ok', unitPrice, compareAtPrice: compareAtPrice(storePrice, unitPrice) };
+    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.
+ */
+function assessLine(ctx, line, index) {
+    const offerId = line.offerId;
+    const same = ctx.doc.offers.filter((offer) => offer.id === offerId);
+    const declared = same.filter((offer) => offer.placement === line.placement);
+    const options = declared.length > 0 ? declared : same;
+    if (options.length === 0)
+        return { priced: refused(index, offerId, 'unknown_offer'), claim: null, placement: null };
+    const results = options.map((offer) => assessOffer(ctx, offer, index));
+    return results.find((result) => result.claim !== null) ?? results[0];
+}
+/** 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) => (line.offerId ? [assessLine(ctx, line, index)] : []));
+}

package/dist/cart.d.ts

@@ -10,21 +10,28 @@ export interface ResolvedLine {
     durationDays: number | null;
 }
 /**
- * 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 gatilho e o subtotal 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 exceção é a **linha de troca** (`replace`): ela é o produto que a cliente leva no
+ * lugar do que escolheu, e conta como escolhida para as outras ofertas. `keys` é o carrinho inteiro: não se oferece o
+ * que ela já tem, 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;
+/** 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 é de troca (`assess.ts`): conta como escolhida. */
+export type SwapCheck = (line: CartLine) => boolean;
+export declare function viewCart(items: ItemIndex, lines: CartLine[], isSwap: SwapCheck): CartView;
 export declare function lineMatches(match: ProductMatch, line: ResolvedLine): boolean;
 export declare function anyLineMatches(match: ProductMatch, lines: ResolvedLine[]): boolean;
 /**

package/dist/cart.js

@@ -17,13 +17,25 @@ function lineTotal(items, line) {
     const unit = line.unitPrice ?? items.get(itemKey(line.item))?.price ?? 0;
     return unit * line.quantity;
 }
-export function viewCart(items, lines) {
+/** 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));
+}
+export function viewCart(items, lines, isSwap) {
     const resolved = lines.map((line) => resolveLine(items, line));
+    const chosen = resolved.filter(({ line }) => !line.gift && (!line.offerId || isSwap(line)));
     return {
-        chosen: resolved.filter(({ line }) => !line.gift && !line.offerId),
-        accepted: resolved.filter(({ line }) => !line.gift && line.offerId),
+        chosen,
         keys: new Set(resolved.map(({ key }) => key)),
-        subtotal: lines.filter((line) => !line.gift).reduce((sum, line) => sum + lineTotal(items, line), 0),
+        subtotal: chosen.reduce((sum, { line }) => sum + lineTotal(items, line), 0),
     };
 }
 export function lineMatches(match, line) {

package/dist/conditions.d.ts

@@ -3,7 +3,13 @@ import type { IneligibleReason } from './io.js';
 import type { Offer, OfferCondition } 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;
+/** 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,26 @@
 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) {
+    return isKnownPrice(offer.price) && ACTIONS.has(offer.action) && offer.conditions.every((condition) => CONDITION_TYPES.has(condition.type));
+}
+/** 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 +28,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,33 +1,29 @@
+import { assessOfferLines, assessor, offerGate } from './assess.js';
 import { anyLineMatches, indexItems, itemKey, resolveLine, viewCart } from './cart.js';
-import { conditionsFailure, validityFailure } from './conditions.js';
+import { conditionsFailure } 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);
 }
+/** Item vendável pela oferta: disponível e com preço da loja (sem ele a compilação grava 0, e a oferta sairia de graça). */
+const sellable = (item) => item !== undefined && item.available && item.price > 0;
 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 (!sellable(item) || ctx.view.keys.has(itemKey(offer.item)))
         return null;
     if (conditionsFailure(offer.conditions, ctx.view, 'decide'))
         return null;
@@ -95,26 +91,31 @@ 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) {
+function emptyDecision(doc, input, status, holdout = false) {
     const decisionId = decisionIdOf(input, doc.version, [], []);
-    return { status, version: doc.version, placement: input.placement, decisionId, offers: [], presentation: null, grouping: null, experiments: [] };
+    return { status, version: doc.version, placement: input.placement, decisionId, 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);
@@ -127,5 +128,6 @@ export function decide(doc, input) {
         presentation: placementPresentation(ctx),
         grouping: groupingFor(ctx),
         experiments,
+        holdout: false,
     };
 }

package/dist/io.d.ts

@@ -5,15 +5,22 @@ export interface CartLine {
     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á). */
     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. `price()` confere a condição da própria troca como se ele ainda
+     * estivesse lá; para as outras ofertas, a linha de troca conta como o produto que a cliente leva (gatilho, subtotal,
+     * vaga extra, combo).
+     */
     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 {
@@ -69,16 +76,34 @@ 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';
 export type PricedLine = {

package/dist/money.d.ts

@@ -1,8 +1,11 @@
 import type { Cents, OfferPrice } from './types.js';
+/** O preço é de um tipo que o pacote sabe calcular, com número no campo do valor. */
+export declare function isKnownPrice(price: OfferPrice): boolean;
 /**
  * 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,23 @@
 function divideHalfUp(numerator, denominator) {
     return Math.floor((2 * numerator + denominator) / (2 * denominator));
 }
+/** O preço é de um tipo que o pacote sabe calcular, com número no campo do valor. */
+export function isKnownPrice(price) {
+    if (price.type === 'percent_off')
+        return Number.isFinite(price.basisPoints);
+    if (price.type === 'fixed' || price.type === 'amount_off')
+        return Number.isFinite(price.amount);
+    return false;
+}
 /**
  * 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,10 @@ 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 só o que a cliente escolheu (linha de oferta não sustenta outra; a de troca conta
+ * como o produto que ela leva) e as vagas da posição, na ordem de prioridade. 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,33 @@
-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 só o que a cliente escolheu (linha de oferta não sustenta outra; a de troca conta
+ * como o produto que ela leva) e as vagas da posição, na ordem de prioridade. 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zolve/offers",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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,