@rudra-js/core 0.5.0 → 0.7.0

package/src/reconciliation.ts

@@ -1,37 +1,14 @@
 import { verify } from '@rudra-js/attested';
-import { offeredCandidates } from './model-prompt.js';
+import { ALLOWED_PHRASES, claimIn, hostFacts, type HostFacts } from './claim-screening.js';
 import type {
   Block,
   GeneratedSpec,
   ProductReference,
   RecommendationBasis,
 } from './component-spec.js';
-import type { SignalDigest } from './signal-digest.js';
+import { engagedCategories, type SignalDigest } from './signal-digest.js';
 import type { Bundle, Product, TrackingInput } from './tracking-input.js';
 
-/**
- * Reconciliation — the boundary between what the model said and what renders.
- *
- * Schema validation guarantees shape. It cannot guarantee truth: a well-formed
- * spec can still name a product that does not exist, one the shopper told us
- * they dislike, one that sold out since the candidate set was assembled, or
- * claim the shopper viewed something they never saw. This pass is where those
- * become impossible.
- *
- * Nothing here trusts the model. A generation that survives every rule and
- * still has nothing to show degrades to `isUsable: false`, and the caller renders
- * the deterministic component instead.
- *
- * Repair, not rejection, is the default. A slightly clipped headline is a better
- * outcome for the shopper than a discarded generation, so text is truncated and
- * unverifiable claims are downgraded. Only an empty result fails outright.
- */
-
-/**
- * Length ceilings, applied by truncation. These live here rather than in the
- * schema because a provider's strict structured-output mode rejects string
- * length bounds — see the note in `component-spec.ts`.
- */
 const CLAMP = {
   headline: 90,
   subheadline: 140,
@@ -42,23 +19,21 @@ const CLAMP = {
   bannerText: 160,
   copyBody: 420,
   rationale: 300,
-  // Not rendered anywhere — this is the SKU as it reads back in a violation.
+
   violationSku: 32,
 } as const;
 
-/**
- * More than this and the component stops being a component.
- *
- * Exported because the fill pass has to read the same blocks this module will:
- * one past the cap never renders, so nothing is worth reserving for it.
- */
 export const MAX_BLOCKS = 4;
 
+export function capBlocks(blocks: Block[]): Block[] {
+  return blocks.slice(0, MAX_BLOCKS);
+}
+
 export interface ReconcileResult {
   spec: GeneratedSpec;
-  /** True when something survived that is worth rendering. */
+
   isUsable: boolean;
-  /** Machine-readable notes on what was removed or changed, for evaluation. */
+
   violations: string[];
 }
 
@@ -66,67 +41,57 @@ function clamp(value: string, limit: number): string {
   const collapsed = value.trim().replace(/\s+/g, ' ');
   if (collapsed.length <= limit) return collapsed;
 
-  // The ellipsis counts against the limit, so leave room for it. Otherwise a
-  // clamped string is one character longer than the cap it was clamped to.
   const cut = collapsed.slice(0, limit - 1);
   const lastSpace = cut.lastIndexOf(' ');
   const base = lastSpace > limit * 0.6 ? cut.slice(0, lastSpace) : cut;
   return `${base.replace(/[.,;:!?-]+$/, '')}…`;
 }
 
-function clampNullable(value: string | null, limit: number): string | null {
-  if (value === null) return null;
-  const clamped = clamp(value, limit);
-  return clamped.length === 0 ? null : clamped;
-}
-
 interface Allowlist {
-  /** SKUs the model may place. */
   allowed: Set<string>;
-  /** SKUs that must never be placed, whatever the model decided. */
   blocked: Set<string>;
+
+  blockedInBundle: Set<string>;
 }
 
-/**
- * SKUs that must never be recommended, whatever chose them.
- *
- * Exported because the deterministic selector applies the same rule when it
- * picks. Two copies of "never recommend these" would drift, and the pair that
- * drifted would be the model path and the fallback path — the two whose
- * comparability the whole evaluation depends on.
- */
-export function neverRecommend(digest: SignalDigest): Set<string> {
-  const blocked = new Set<string>([
-    ...digest.dislikedSkus,
-    ...digest.purchasedSkus,
-    ...digest.cartSkus,
-  ]);
-  if (digest.currentSku) blocked.add(digest.currentSku);
+function refusedEverywhere(input: TrackingInput): Set<string> {
+  const refused = new Set<string>();
+  for (const signal of input.signals.dislikes) refused.add(signal.sku);
+  if (input.context.currentSku) refused.add(input.context.currentSku);
+
+  return refused;
+}
+
+export function neverRecommend(input: TrackingInput): Set<string> {
+  const { signals } = input;
+
+  const blocked = refusedEverywhere(input);
+  for (const signal of [...signals.lastPurchased, ...signals.cart]) {
+    blocked.add(signal.sku);
+  }
+
   return blocked;
 }
 
-function buildAllowlist(input: TrackingInput, digest: SignalDigest): Allowlist {
+function buildAllowlist(input: TrackingInput): Allowlist {
   const allowed = new Set<string>();
   for (const product of input.candidates) {
-    // An out-of-stock candidate is not a recommendation, it is a dead end.
     if (product.isInStock) allowed.add(product.sku);
   }
 
-  // Blocked structurally rather than by asking the model nicely. The prompt
-  // says not to place these; this is what makes it true when it ignores us.
-  return { allowed, blocked: neverRecommend(digest) };
+  return {
+    allowed,
+    blocked: neverRecommend(input),
+    blockedInBundle: refusedEverywhere(input),
+  };
 }
 
-/**
- * Checks the model's stated reason for a pick against the shopper's actual
- * signals.
- *
- * `basis` is a factual claim — "you viewed this", "this goes with your cart" —
- * and the model has every incentive to reach for the most flattering one. A
- * claim we cannot support becomes `popular`, which asserts nothing, and the
- * prose that stated it is dropped along with it.
- */
-function verifyBasis(basis: RecommendationBasis, product: Product, digest: SignalDigest): boolean {
+function verifyBasis(
+  basis: RecommendationBasis,
+  product: Product,
+  digest: SignalDigest,
+  engaged: ReadonlySet<string>,
+): boolean {
   switch (basis) {
     case 'most_viewed':
       return digest.topViewed.some((viewed) => viewed.sku === product.sku);
@@ -135,308 +100,21 @@ function verifyBasis(basis: RecommendationBasis, product: Product, digest: Signa
     case 'complements_purchase':
       return digest.purchasedSkus.length > 0;
     case 'liked_category':
-      return digest.categoryAffinity.some((affinity) => affinity.category === product.category);
+      return (
+        engaged.has(product.category) &&
+        digest.categoryAffinity.some((affinity) => affinity.category === product.category)
+      );
     case 'similar_to_current':
       return digest.currentCategory === product.category;
     case 'popular':
-      // Makes no claim about this shopper, so there is nothing to check.
       return true;
   }
 }
 
-/**
- * Free text that states something the renderer cannot check.
- *
- * The prompt bans prices, discounts, delivery dates, stock levels and ratings
- * because every one of them moves after the words are written, and a cohort
- * component is cached and served again later. `verifyBasis` checks the basis a
- * pick claims; nothing checks the sentences around it, so every string the
- * model writes is checked here — a heading is not a safer place for a claim
- * than the small print under it.
- *
- * These patterns are the first of three passes and the only one that names which
- * of the five kinds a sentence claimed, so they read the domain: "20% off", not
- * "20%"; "rated 4.8", not "rated". A specification walks past all of them and is
- * then weighed by @rudra-js/attested, which reads no domain at all and asks only
- * whether the shop supplied the number.
- *
- * One rule per line, because each line is a separate judgement about where the
- * boundary sits and each one wants its own reason written next to it.
- */
-const CLAIM_PATTERNS: { kind: string; patterns: RegExp[] }[] = [
-  {
-    // Customers scoring the product. "rated for winter use", "rated to -10C"
-    // and "an IPX7 water rating" are about what the product can take.
-    kind: 'rating',
-    patterns: [
-      /\breviews?\b|\breviewed\b/,
-      /\b(?:\d+(?:\.\d+)?|three|four|five)[\s-]?stars?\b/,
-      /\bstars?[\s-]?ratings?\b/,
-      // A rating somebody gave it, rather than one it was built to.
-      /\b(?:customer|shopper|buyer|user|average|overall)[\s-]ratings?\b/,
-      // A score out of five is written as a decimal. A spec is "-5C" or "20,000mm".
-      /\bratings?\s+of\s+[0-5]\.\d\b/,
-      // The same score with the word "rating" nowhere near it: "4.8 out of 5".
-      /\b[0-5](?:\.\d)?\s+out of\s+(?:5|five)\b/,
-      /\b(?:highly|top|best|well|poorly|five|four)[\s-]rated\b/,
-      // "rated 4.8" is a score. "rated 3 season" is what the tent is built for.
-      /\brated\s+(?:[0-5]\.\d|(?:[0-5]|three|four|five)\s+(?:stars?|out of))\b/,
-      // How many other people bought or liked it is a customer claim too.
-      /\bbest[\s-]?sell(?:er|ers|ing)\b/,
-      // The words a model reaches for when "best" is banned. Each branch carries its own
-      // \b — one in front of the group demands a word character before the #, never there.
-      /(?:\bnumber one|\bno\.? ?1|#\s?1)[\s-]?sell(?:er|ers|ing)\b/,
-      /\bloved by (?:thousands|hundreds|millions|\d)/,
-    ],
-  },
-  {
-    kind: 'price',
-    patterns: [
-      // No digit beside it: asking for one let "$thirty-nine and it is yours" through.
-      /[$£€¥₹]/,
-      /\b\d+(?:\.\d+)?\s?(?:usd|eur|gbp|dollars?|pounds?|euros?)\b/,
-      // The same spelled out. "pounds" is left off on purpose — a pack weighs two of those.
-      /\bdollars?\b|\beuros?\b/,
-      // The same codes on the other side of the number: "USD 20", "EUR 5.99".
-      /\b(?:usd|eur|gbp)\s?\d/,
-      // The krona is spelled out rather than drawn, so it needs a number beside it.
-      /\bkr\s?\d|\d\s?kr\b/,
-      /\bpric(?:e|es|ed|ing)\b/,
-      // A before-and-after is a price claim even with no currency on it.
-      /\bwas\s+[$£€¥]?\s?\d[\d,.]*\s*[,;–—-]?\s*now\s+[$£€¥]?\s?\d/,
-      // "does not feel cheap" is about quality. Only the comparison is money.
-      /\bcheap(?:er|est)\b/,
-      /\baffordable\b|\bbargain\b/,
-      // "at no cost to comfort" is not money. "costs less" is.
-      /\bcosts?\s+(?:less|more|only|just|about|around|[$£€¥]?\d)/,
-      /\blow(?:er)?[\s-]cost\b/,
-      // "saves weight" and "saves on weight" are both about grams.
-      /\bsaves?\s+(?:you\s+)?(?:money|cash|[$£€¥]\s?\d)/,
-    ],
-  },
-  {
-    // A percentage in outdoor copy is a specification far more often than it is
-    // money off, so it only counts beside a money word: "20% off", not
-    // "100% recycled".
-    kind: 'discount',
-    patterns: [
-      /\d+(?:\.\d+)?\s?(?:%|percent)\s*(?:off\b|discount|reduction|less\b)/,
-      /\b(?:save|saving|savings|off|discount|extra|up to)\s+(?:up to\s+)?\d+(?:\.\d+)?\s?(?:%|percent)/,
-      /\bdiscount(?:s|ed)?\b/,
-      /\bsale\b|\bmarked down\b|\bdeal of\b/,
-      /\bhalf[\s-]?(?:price|off)\b/,
-      // Money off with no percent sign anywhere on it: "save 20 off".
-      /\bsaves?\s+\d[\d.,]*\s+off\b/,
-      // "extra clearance for thick socks" is room inside the shoe.
-      /\bclearance\s+(?:sale|price|event|deal)\b|\bon clearance\b/,
-      // "reduced weight" and "reduced to 900g" are specifications. Only a
-      // reduced price, or a reduction with a date on it, is money off.
-      /\bprice reduced\b|\breduced price\b|\breduced by \d+\s?(?:%|percent)|\breduced\s+(?:this|next|last)\s+week\b/,
-    ],
-  },
-  {
-    // When it turns up, not what turns up. "ships in a recycled box" and
-    // "arrives flat-packed" describe the thing, so the verb alone is not enough
-    // — it needs a day or a date beside it.
-    kind: 'delivery',
-    patterns: [
-      /\bdelivery\b|\bshipping\b/,
-      /\bnext[\s-]day\b|\bsame[\s-]day\b|\bovernight\b/,
-      /\b(?:ships?|arrives?|arriving|delivered|by|before|in time for)\s+(?:on\s+)?(?:today|tomorrow|tonight|this week|next week|the weekend|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/,
-      /\b(?:ships?|arrives?|arriving)\s+(?:in|within)\s+\d/,
-      /\bin time for\b/,
-    ],
-  },
-  {
-    kind: 'stock',
-    patterns: [
-      /\b(?:in|out of|low on) stock\b/,
-      /\blimited stock\b/,
-      /\brestocked?\b|\bsold out\b/,
-      // "the last few miles" is a distance, so a count needs "left" after it.
-      /\b(?:only\s+)?(?:\d+|a few|a handful|a couple|one|few)\s+(?:left|remain(?:s|ing)?)\b/,
-      /\bselling fast\b|\b(?:almost|nearly) gone\b|\bwhile stocks last\b/,
-    ],
-  },
-];
-
-/**
- * Letters that render as a Latin letter but are not one. A Cyrillic о in
- * "in stоck" would otherwise carry a stock claim straight past the rule written
- * for it, and the shopper would read the claim anyway.
- */
-const CONFUSABLES: Record<string, string> = {
-  а: 'a',
-  в: 'b',
-  е: 'e',
-  к: 'k',
-  м: 'm',
-  н: 'h',
-  о: 'o',
-  р: 'p',
-  с: 'c',
-  т: 't',
-  х: 'x',
-  у: 'y',
-  ѕ: 's',
-  і: 'i',
-  ј: 'j',
-  ԁ: 'd',
-  һ: 'h',
-  ӏ: 'l',
-  α: 'a',
-  ε: 'e',
-  ι: 'i',
-  κ: 'k',
-  ν: 'v',
-  ο: 'o',
-  ρ: 'p',
-  τ: 't',
-  υ: 'u',
-  χ: 'x',
-  ϲ: 'c',
-};
-
-/**
- * Characters that render as nothing: format characters, default-ignorable code
- * points and the controls. Cf and Default_Ignorable each hold characters the
- * other does not.
- *
- * The same class @rudra-js/attested strips in its own `hidden.ts`. The second copy stays
- * now that core calls attested, because it feeds core's own patterns and those reach two
- * things attested's phrase list does not hold: "20% οff" spelled with a Greek omicron,
- * and "PRİCED to move". Widening one and not the other is still the mistake to watch for.
- */
-const INVISIBLE = /[\p{Cf}\p{Default_Ignorable_Code_Point}\p{Cc}]/gu;
-
-/**
- * The controls that do take room. Deleting these would read `Only 2\n3 left` as 23.
- *
- * No test pins this line, and none can: clamping collapses every run of whitespace
- * before a claim is screened, so nothing here ever sees one. It is kept so the class
- * reads the same in both copies.
- */
-const SPACING = /[\t\n\v\f\r\u0085]/;
-
-/**
- * Marks that hang on the character before them instead of taking a column of their
- * own. Dropped after composition, so an accented e keeps its accent while an
- * overline, which composes with nothing, cannot hide a word from its own rule.
- */
-const MARKS = /[\p{Mn}\p{Me}]/gu;
-
-/**
- * One shape for the text before the patterns read it, so a word that renders as
- * "in stock" is read as "in stock" however it was spelled.
- *
- * Only the reading is normalised. What renders is what the model wrote.
- */
-function normaliseForClaims(text: string): string {
-  const lowered = text
-    .replace(INVISIBLE, (char) => (SPACING.test(char) ? char : ''))
-    .normalize('NFKC')
-    .toLowerCase()
-    .normalize('NFC')
-    .replace(MARKS, '');
-
-  let folded = '';
-  for (const char of lowered) folded += CONFUSABLES[char] ?? char;
-  return folded;
-}
-
-/**
- * Wording attested bans that this project has already ruled is not a claim. An allowance
- * forgives a banned phrase sitting inside it, so an entry ending on a preposition — "extra
- * clearance for" — forgives whatever follows it. Exported so a test can hold the list
- * against attested's own.
- */
-export const ALLOWED_PHRASES = ['does not feel cheap', "doesn't feel cheap", 'last few miles'];
-
-/** Only a string with one of these in it can stand behind a numeral. */
-const DIGIT = /\p{Nd}/u;
-
-/** Anything attested reads as a numeral — ½ ² Ⅲ included, which it reports rather than ignores. */
 const NUMERAL = /[\p{Nd}\p{No}\p{Nl}]/u;
 
 const NO_FACTS: readonly string[] = [];
 
-/** A fact whose whole content is a number in exponent notation. attested lays those out in place. */
-const BARE_EXPONENT = /^[+-]?\d+(?:\.\d+)?[eE]([+-]?\d+)$/;
-
-/** Wide enough for every finite JavaScript number, and for anything a shop sells. */
-const MAX_EXPONENT = 1000;
-
-// `1e2000000000` is twelve characters and lays out into a run long enough to end the process.
-// attested caps that itself, but it is a peer dependency and a host's copy of it may be older.
-function canLayOut(fact: string): boolean {
-  const match = BARE_EXPONENT.exec(fact.trim());
-  if (match === null) return true;
-  return Math.abs(Number(match[1] ?? '')) <= MAX_EXPONENT;
-}
-
-/**
- * The numbers the shop published about one product: its category and tags, only the strings
- * carrying a digit. Exported so a test can pin what never reaches attested.
- */
-export function productFacts(product: Product): string[] {
-  const facts: string[] = [];
-  if (DIGIT.test(product.category) && canLayOut(product.category)) facts.push(product.category);
-  for (const tag of product.tags) {
-    if (DIGIT.test(tag) && canLayOut(tag)) facts.push(tag);
-  }
-  return facts;
-}
-
-interface HostFacts {
-  pooled: string[];
-  bySku: Map<string, string[]>;
-}
-
-/**
- * The shop's own numbers for this request, for attested to check numerals against.
- *
- * `offeredCandidates` rather than `input.candidates` — out of stock or past the prompt's cap
- * means a product the model never saw. A title and a rating it is shown but told never to
- * repeat, so a numeral out of one is one it was told not to write. The browsed category comes
- * from the request rather than the catalogue, so a host passing a URL segment through would
- * hand this list to whoever types the URL.
- *
- * `pooled` is the soft part of the check: one candidate's "40 litre" backs "take 40 off"
- * written about another. A `reason` and a `badge` read `bySku`, because they sit under a
- * named product — off the pooled list, a badge reading "Only 2" stood on a tent's tag.
- */
-function hostFacts(input: TrackingInput): HostFacts {
-  const pooled = new Set<string>();
-  const bySku = new Map<string, string[]>();
-
-  for (const product of offeredCandidates(input)) {
-    const own = productFacts(product);
-    bySku.set(product.sku, own);
-    for (const fact of own) pooled.add(fact);
-  }
-
-  return { pooled: [...pooled], bySku };
-}
-
-/** Names the first forbidden claim the text makes, or null when it makes none. */
-function claimIn(text: string): string | null {
-  const normalised = normaliseForClaims(text);
-  for (const claim of CLAIM_PATTERNS) {
-    for (const pattern of claim.patterns) {
-      if (pattern.test(normalised)) return claim.kind;
-    }
-  }
-  return null;
-}
-
-/**
- * The running state of one reconciliation pass: what has been placed, how much
- * of the item budget is left, and what was changed along the way.
- *
- * This is deliberately one named thing rather than three parameters threaded
- * through every function. The budget and the de-duplication set are global to a
- * spec, not to a block, which is the part that is easy to get wrong.
- */
 function createPlacementTracker(maxItems: number, facts: HostFacts) {
   const placedSkus = new Set<string>();
   const violations: string[] = [];
@@ -462,37 +140,27 @@ function createPlacementTracker(maxItems: number, facts: HostFacts) {
 
 type PlacementTracker = ReturnType<typeof createPlacementTracker>;
 
-/**
- * Drops text that makes a claim we cannot check, and names what it claimed.
- *
- * Runs after clamping, so what is screened is exactly what would have rendered.
- * Dropping means what it means everywhere else here: this field becomes null
- * and the rest of the block carries on.
- *
- * Three passes, most specific first. Core's patterns name one of the five kinds; `quantity`
- * is the only proof in the stack, every numeral having to be one the shop supplied; `wording`
- * is a second denylist and the weakest, so it answers last. `facts` defaults to the pooled
- * list, and a field that names one product passes that product's own.
- */
 function screenClaim(
   value: string | null,
+  limit: number,
   field: string,
   tracker: PlacementTracker,
   facts: readonly string[] = tracker.facts,
 ): string | null {
   if (value === null) return null;
 
-  const kind = claimIn(value);
+  const clamped = clamp(value, limit);
+  if (clamped.length === 0) return null;
+
+  const kind = claimIn(value) ?? claimIn(clamped);
   if (kind !== null) {
     tracker.record(`unverifiable-claim:${kind}:${field}`);
     return null;
   }
 
-  // Nothing for the quantity layer to weigh without a numeral, whatever the facts say,
-  // and reading the fact list to prove that again per field is most of what this costs.
-  const weighed = NUMERAL.test(value) ? facts : NO_FACTS;
+  const weighed = NUMERAL.test(clamped) ? facts : NO_FACTS;
 
-  const result = verify(value, { values: weighed, allowedPhrases: ALLOWED_PHRASES });
+  const result = verify(clamped, { values: weighed, allowedPhrases: ALLOWED_PHRASES });
   if (!result.quantity.supported) {
     tracker.record(`unverifiable-claim:quantity:${field}`);
     return null;
@@ -502,34 +170,21 @@ function screenClaim(
     return null;
   }
 
-  return value;
+  return clamped;
 }
 
-/**
- * The same screen for a field that cannot be null. Emptying it hands the field
- * to the rule that already drops a block, or a whole generation, whose text
- * clamps to nothing — so a banner reading "20% off" disappears rather than
- * rendering blank.
- */
-function screenRequired(value: string, field: string, tracker: PlacementTracker): string {
-  return screenClaim(value, field, tracker) ?? '';
+function screenRequired(
+  value: string,
+  limit: number,
+  field: string,
+  tracker: PlacementTracker,
+): string {
+  return screenClaim(value, limit, field, tracker) ?? '';
 }
 
-/**
- * Decides whether one SKU may be placed, and names the reason when it may not.
- * Does not consume budget — the caller does that once it commits.
- *
- * Order matters. The budget is checked last because it is the least specific
- * cause: a hallucinated SKU that arrives after the budget is spent is still a
- * hallucination, and reporting it as `budget:dropped` would understate how
- * often the model invents products. These strings are the evaluation signal,
- * so each one has to name the fault that actually fired.
- */
 function rejectionFor(sku: string, allowlist: Allowlist, tracker: PlacementTracker): string | null {
-  // A rejected SKU is whatever the model wrote, and the schema cannot bound it.
   const named = clamp(sku, CLAMP.violationSku);
 
-  // Either hallucinated or out of stock. Either way it cannot render.
   if (!allowlist.allowed.has(sku)) return `unknown-sku:${named}`;
   if (allowlist.blocked.has(sku)) return `blocked-sku:${named}`;
   if (tracker.hasPlaced(sku)) return `duplicate-sku:${named}`;
@@ -542,6 +197,7 @@ function reconcileItems(
   allowlist: Allowlist,
   candidatesBySku: Map<string, Product>,
   digest: SignalDigest,
+  engaged: ReadonlySet<string>,
   tracker: PlacementTracker,
   ourReasons: ReadonlyMap<string, string>,
 ): ProductReference[] {
@@ -555,38 +211,33 @@ function reconcileItems(
     }
 
     const product = candidatesBySku.get(item.sku);
-    // rejectionFor already proved the SKU is an in-stock candidate.
+
     if (!product) continue;
 
     tracker.place(item.sku);
 
-    const hasSupportedBasis = verifyBasis(item.basis, product, digest);
+    const hasSupportedBasis = verifyBasis(item.basis, product, digest, engaged);
     if (!hasSupportedBasis) tracker.record(`unsupported-basis:${item.basis}:${item.sku}`);
 
-    // Our sentence, not the model's. It has to match, so a lookalike is still screened.
     const isOurs = item.reason !== null && ourReasons.get(item.sku) === item.reason;
 
     const own = tracker.factsFor(item.sku);
 
+    let reason: string | null = null;
+    let badge: string | null = null;
+    if (hasSupportedBasis) {
+      reason = isOurs
+        ? clamp(item.reason ?? '', CLAMP.reason) || null
+        : screenClaim(item.reason, CLAMP.reason, `reason:${item.sku}`, tracker, own);
+
+      badge = screenClaim(item.badge, CLAMP.badge, `badge:${item.sku}`, tracker, own);
+    }
+
     kept.push({
       sku: item.sku,
       basis: hasSupportedBasis ? item.basis : 'popular',
-      // The prose exists to state the basis. If the basis did not hold, the
-      // prose is a claim we just decided is untrue.
-      reason: hasSupportedBasis
-        ? isOurs
-          ? clampNullable(item.reason, CLAMP.reason)
-          : screenClaim(
-              clampNullable(item.reason, CLAMP.reason),
-              `reason:${item.sku}`,
-              tracker,
-              own,
-            )
-        : null,
-      // A badge is the shortest, loudest text on the card, and the schema's own
-      // example for it was "Back in stock" — a stock claim. It renders, so it is
-      // read for claims like every other sentence the model writes.
-      badge: screenClaim(clampNullable(item.badge, CLAMP.badge), `badge:${item.sku}`, tracker, own),
+      reason,
+      badge,
       emphasis: item.emphasis,
     });
   }
@@ -594,8 +245,6 @@ function reconcileItems(
   return kept;
 }
 
-// Three separate counts, not one score — cart beats views beats category
-// regardless of how the counts compare, so they can't be summed.
 interface BundleFit {
   cartHits: number;
   viewedHits: number;
@@ -618,7 +267,6 @@ function fitOf(
   return fit;
 }
 
-/** In the cart beats recently viewed, which beats the category being looked at. */
 function isBetterFit(fit: BundleFit, best: BundleFit | undefined): boolean {
   if (!best) return true;
   if (fit.cartHits !== best.cartHits) return fit.cartHits > best.cartHits;
@@ -637,14 +285,12 @@ function chooseBundle(
   let bestFit: BundleFit | undefined;
 
   for (const bundle of bundles) {
-    // A bundle needs room for every product at once.
     if (bundle.skus.length > tracker.remaining) continue;
 
     let isPlaceable = true;
     for (const sku of bundle.skus) {
       if (!allowlist.allowed.has(sku)) isPlaceable = false;
-      if (digest.dislikedSkus.includes(sku)) isPlaceable = false;
-      // Already shown by an earlier block — twice on a page looks broken.
+      if (allowlist.blockedInBundle.has(sku)) isPlaceable = false;
       if (tracker.hasPlaced(sku)) isPlaceable = false;
     }
     if (!isPlaceable) continue;
@@ -659,23 +305,12 @@ function chooseBundle(
   return best;
 }
 
-/**
- * The set this shopper should get, decided before anything is placed.
- *
- * The generator needs the answer early, so it can keep the set's products out
- * of the grid and keep room for them. `chooseBundle` stays private: this hands
- * out the choice, not the machinery behind it.
- *
- * `spokenFor` is what the blocks above the bundle block will have placed by the
- * time it is reached. Placing it here first is what makes the two choices agree:
- * a set is only pre-chosen if reconciliation could still reach for it.
- */
 export function bundleForShopper(
   input: TrackingInput,
   digest: SignalDigest,
   spokenFor: readonly string[],
 ): Bundle | undefined {
-  const allowlist = buildAllowlist(input, digest);
+  const allowlist = buildAllowlist(input);
   const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
   const tracker = createPlacementTracker(digest.maxItems, hostFacts(input));
 
@@ -684,27 +319,14 @@ export function bundleForShopper(
   return chooseBundle(input.bundles, allowlist, digest, candidatesBySku, tracker);
 }
 
-/**
- * The hero products these blocks will really place.
- *
- * A hero keeps the product the model named — its headline was written about
- * that product — so it spends a slot of the item budget the grid cannot have.
- * One this shopper cannot see is dropped below and spends nothing, so it is not
- * counted here either.
- */
-export function placeableHeroSkus(
-  blocks: readonly Block[],
-  input: TrackingInput,
-  digest: SignalDigest,
-): string[] {
-  const allowlist = buildAllowlist(input, digest);
+export function placeableHeroSkus(blocks: readonly Block[], input: TrackingInput): string[] {
+  const allowlist = buildAllowlist(input);
 
   const skus: string[] = [];
   for (const block of blocks) {
     if (block.kind !== 'hero') continue;
     if (block.sku === null) continue;
     if (!allowlist.allowed.has(block.sku) || allowlist.blocked.has(block.sku)) continue;
-    // Two heroes naming the same product: only the first one gets to place it.
     if (skus.includes(block.sku)) continue;
     skus.push(block.sku);
   }
@@ -717,6 +339,7 @@ function reconcileBlock(
   allowlist: Allowlist,
   candidatesBySku: Map<string, Product>,
   digest: SignalDigest,
+  engaged: ReadonlySet<string>,
   bundles: readonly Bundle[],
   tracker: PlacementTracker,
   ourReasons: ReadonlyMap<string, string>,
@@ -728,20 +351,14 @@ function reconcileBlock(
         const rejection = rejectionFor(sku, allowlist, tracker);
         if (rejection) {
           tracker.record(rejection);
-          // A hero without its product is still a legitimate headline.
+
           sku = null;
         } else {
           tracker.place(sku);
         }
       }
-      // Every other block kind disappears when its content clamps to nothing.
-      // A hero with no headline and no product is the same empty region, and
-      // it would otherwise render above real content.
-      const headline = screenRequired(
-        clamp(block.headline, CLAMP.headline),
-        'hero-headline',
-        tracker,
-      );
+
+      const headline = screenRequired(block.headline, CLAMP.headline, 'hero-headline', tracker);
       if (headline.length === 0 && sku === null) {
         tracker.record('empty-block:hero');
         return null;
@@ -749,9 +366,9 @@ function reconcileBlock(
       return {
         kind: 'hero',
         headline,
-        body: screenClaim(clampNullable(block.body, CLAMP.subheadline), 'hero-body', tracker),
+        body: screenClaim(block.body, CLAMP.subheadline, 'hero-body', tracker),
         sku,
-        ctaLabel: screenClaim(clampNullable(block.ctaLabel, CLAMP.ctaLabel), 'hero-cta', tracker),
+        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'hero-cta', tracker),
       };
     }
 
@@ -761,6 +378,7 @@ function reconcileBlock(
         allowlist,
         candidatesBySku,
         digest,
+        engaged,
         tracker,
         ourReasons,
       );
@@ -770,8 +388,8 @@ function reconcileBlock(
       }
       return {
         kind: 'grid',
-        title: screenClaim(clampNullable(block.title, CLAMP.blockTitle), 'grid-title', tracker),
-        // Never leave a grid wider than it has items to fill.
+        title: screenClaim(block.title, CLAMP.blockTitle, 'grid-title', tracker),
+
         columns: Math.min(block.columns, Math.max(2, items.length)) as 2 | 3 | 4,
         items,
       };
@@ -783,6 +401,7 @@ function reconcileBlock(
         allowlist,
         candidatesBySku,
         digest,
+        engaged,
         tracker,
         ourReasons,
       );
@@ -792,13 +411,13 @@ function reconcileBlock(
       }
       return {
         kind: 'carousel',
-        title: screenClaim(clampNullable(block.title, CLAMP.blockTitle), 'carousel-title', tracker),
+        title: screenClaim(block.title, CLAMP.blockTitle, 'carousel-title', tracker),
         items,
       };
     }
 
     case 'banner': {
-      const text = screenRequired(clamp(block.text, CLAMP.bannerText), 'banner-text', tracker);
+      const text = screenRequired(block.text, CLAMP.bannerText, 'banner-text', tracker);
       if (text.length === 0) {
         tracker.record('empty-block:banner');
         return null;
@@ -807,19 +426,19 @@ function reconcileBlock(
         kind: 'banner',
         tone: block.tone,
         text,
-        ctaLabel: screenClaim(clampNullable(block.ctaLabel, CLAMP.ctaLabel), 'banner-cta', tracker),
+        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'banner-cta', tracker),
       };
     }
 
     case 'copy': {
-      const body = screenRequired(clamp(block.body, CLAMP.copyBody), 'copy-body', tracker);
+      const body = screenRequired(block.body, CLAMP.copyBody, 'copy-body', tracker);
       if (body.length === 0) {
         tracker.record('empty-block:copy');
         return null;
       }
       return {
         kind: 'copy',
-        title: screenClaim(clampNullable(block.title, CLAMP.blockTitle), 'copy-title', tracker),
+        title: screenClaim(block.title, CLAMP.blockTitle, 'copy-title', tracker),
         body,
       };
     }
@@ -835,24 +454,22 @@ function reconcileBlock(
 
       return {
         kind: 'bundle',
-        title: screenClaim(clampNullable(block.title, CLAMP.blockTitle), 'bundle-title', tracker),
-        body: screenClaim(clampNullable(block.body, CLAMP.subheadline), 'bundle-body', tracker),
-        ctaLabel: screenClaim(clampNullable(block.ctaLabel, CLAMP.ctaLabel), 'bundle-cta', tracker),
-        // The model's bundleId is ignored on purpose.
+        title: screenClaim(block.title, CLAMP.blockTitle, 'bundle-title', tracker),
+        body: screenClaim(block.body, CLAMP.subheadline, 'bundle-body', tracker),
+        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'bundle-cta', tracker),
+
         bundleId: chosen.id,
       };
     }
   }
 }
 
-/** True when a spec contains at least one block that actually shows a product. */
 function showsAnyProduct(blocks: Block[]): boolean {
   return blocks.some(
     (block) =>
       (block.kind === 'grid' && block.items.length > 0) ||
       (block.kind === 'carousel' && block.items.length > 0) ||
       (block.kind === 'hero' && block.sku !== null) ||
-      // A bundle shows products too, so it counts the same as grid/carousel/hero.
       (block.kind === 'bundle' && block.bundleId !== null),
   );
 }
@@ -861,18 +478,12 @@ export function reconcileSpec(
   generated: GeneratedSpec,
   input: TrackingInput,
   digest: SignalDigest,
-  /**
-   * The reason this request wrote itself, by SKU: the host's own `reason` on a
-   * candidate, or the sentence the selector wrote when there was none. Neither is the
-   * model's words, and the deterministic component renders the same sentence unscreened.
-   *
-   * Only `fitToShopper` fills it, so in `per-shopper` mode it is empty and every
-   * reason is the model's, including one that happens to read the same.
-   */
+
   ourReasons: ReadonlyMap<string, string> = new Map(),
 ): ReconcileResult {
-  const allowlist = buildAllowlist(input, digest);
+  const allowlist = buildAllowlist(input);
   const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
+  const engaged = engagedCategories(input);
   const tracker = createPlacementTracker(digest.maxItems, hostFacts(input));
 
   if (generated.blocks.length > MAX_BLOCKS) {
@@ -880,12 +491,13 @@ export function reconcileSpec(
   }
 
   const blocks: Block[] = [];
-  for (const block of generated.blocks.slice(0, MAX_BLOCKS)) {
+  for (const block of capBlocks(generated.blocks)) {
     const reconciled = reconcileBlock(
       block,
       allowlist,
       candidatesBySku,
       digest,
+      engaged,
       input.bundles,
       tracker,
       ourReasons,
@@ -895,19 +507,12 @@ export function reconcileSpec(
 
   const spec: GeneratedSpec = {
     tone: generated.tone,
-    headline: screenRequired(clamp(generated.headline, CLAMP.headline), 'headline', tracker),
-    subheadline: screenClaim(
-      clampNullable(generated.subheadline, CLAMP.subheadline),
-      'subheadline',
-      tracker,
-    ),
+    headline: screenRequired(generated.headline, CLAMP.headline, 'headline', tracker),
+    subheadline: screenClaim(generated.subheadline, CLAMP.subheadline, 'subheadline', tracker),
     blocks,
-    rationale: screenRequired(clamp(generated.rationale, CLAMP.rationale), 'rationale', tracker),
+    rationale: screenRequired(generated.rationale, CLAMP.rationale, 'rationale', tracker),
   };
 
-  // A component that recommends nothing is worse than no component at all.
-  // Recorded separately: "no products survived" and "the model returned no
-  // headline" are different failures and want different fixes.
   if (!showsAnyProduct(blocks)) tracker.record('unusable:no-products');
   if (spec.headline.length === 0) tracker.record('unusable:no-headline');
   const isUsable = showsAnyProduct(blocks) && spec.headline.length > 0;