@rudra-js/core 0.4.0 → 0.6.0

package/src/reconciliation.ts

@@ -1,35 +1,21 @@
+import { verify } from '@rudra-js/attested';
+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.
+ * Nothing here trusts the model. Repair, not rejection, is the default: text is
+ * truncated and unverifiable claims are downgraded, and 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`.
- */
+/** Truncation ceilings. Not in the schema — a provider's strict mode rejects length bounds. See `component-spec.ts`. */
 const CLAMP = {
   headline: 90,
   subheadline: 140,
@@ -44,14 +30,14 @@ const CLAMP = {
   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.
- */
+/** More than this and the component stops being a component. */
 export const MAX_BLOCKS = 4;
 
+/** The fill pass calls this too: one past the cap never renders, so nothing is worth reserving for it. */
+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. */
@@ -64,8 +50,7 @@ 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.
+  // The ellipsis counts against the limit, so leave room for it.
   const cut = collapsed.slice(0, limit - 1);
   const lastSpace = cut.lastIndexOf(' ');
   const base = lastSpace > limit * 0.6 ? cut.slice(0, lastSpace) : cut;
@@ -79,52 +64,70 @@ function clampNullable(value: string | null, limit: number): string | null {
 }
 
 interface Allowlist {
-  /** SKUs the model may place. */
   allowed: Set<string>;
-  /** SKUs that must never be placed, whatever the model decided. */
   blocked: Set<string>;
+  /** A bundle is placed whole, so it checks this narrower set. See `refusedEverywhere`. */
+  blockedInBundle: Set<string>;
+}
+
+/**
+ * A thumbs-down, and the product on the screen right now. No block may hold one
+ * of these, a bundle included.
+ *
+ * Read from the payload rather than the digest on purpose. `DIGEST_LIMITS`
+ * trims each history to what fits in a prompt, and a shopper with thirteen
+ * dislikes would otherwise be shown the thirteenth. The cap exists to bound
+ * what the model is told, not what the shopper may be shown.
+ */
+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;
 }
 
 /**
  * SKUs that must never be recommended, whatever chose them.
  *
+ * Everything above plus what the shopper already has, read from the payload for
+ * the same reason: a shopper with nine purchases must not be sold the ninth back.
+ *
  * 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);
+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);
@@ -133,7 +136,13 @@ 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);
+      // Affinity alone is not enough: it scores the category the shopper is
+      // standing in, and standing somewhere is not liking it. That claim is
+      // `similar_to_current`, which says so honestly.
+      return (
+        engaged.has(product.category) &&
+        digest.categoryAffinity.some((affinity) => affinity.category === product.category)
+      );
     case 'similar_to_current':
       return digest.currentCategory === product.category;
     case 'popular':
@@ -142,228 +151,21 @@ function verifyBasis(basis: RecommendationBasis, product: Product, digest: Signa
   }
 }
 
-/**
- * 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.
- *
- * A claim is about money, a customer score, when it arrives, or how many are
- * left. A specification is not a claim, even when it has a number or a
- * percentage in it: "100% recycled nylon", "a comfort rating of -5C" and
- * "arrives flat-packed" are all things a shop can say about the product itself,
- * and they stay. That is why almost every rule below needs a second word beside
- * the first — "20% off", not "20%"; "rated 4.8", not "rated". A careful
- * rewording will get past this, and that is the trade we want: missing one
- * claim is better than deleting honest copy on every page.
- *
- * 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/,
-      /\bloved by (?:thousands|hundreds|millions|\d)/,
-    ],
-  },
-  {
-    kind: 'price',
-    patterns: [
-      /[$£€¥₹]\s?\d/,
-      /\b\d+(?:\.\d+)?\s?(?:usd|eur|gbp|dollars?|pounds?|euros?)\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`. A second copy,
- * because core carries no dependencies and is not about to take one — which means
- * widening one and not the other is 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]/;
+/** Anything attested reads as a numeral — ½ ² Ⅲ included, which it reports rather than ignores. */
+const NUMERAL = /[\p{Nd}\p{No}\p{Nl}]/u;
 
-/**
- * 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;
+const NO_FACTS: readonly string[] = [];
 
-/**
- * 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;
-}
-
-/** 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) {
+/** The budget and the de-duplication set are global to a spec, not to a block. */
+function createPlacementTracker(maxItems: number, facts: HostFacts) {
   const placedSkus = new Set<string>();
   const violations: string[] = [];
   let remaining = maxItems;
 
   return {
     violations,
+    facts: facts.pooled,
+    factsFor: (sku: string): readonly string[] => facts.bySku.get(sku) ?? NO_FACTS,
     get remaining() {
       return remaining;
     },
@@ -381,45 +183,69 @@ function createPlacementTracker(maxItems: number) {
 type PlacementTracker = ReturnType<typeof createPlacementTracker>;
 
 /**
- * Drops text that makes a claim we cannot check, and names what it claimed.
+ * Clamps, then screens. The cap has to happen here: clamping first can cut the word that
+ * makes a claim a claim, so "Ridge picks, only 2 left!" renders past the stock pattern.
  *
- * 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.
  */
 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);
-  if (kind === null) return value;
+  const clamped = clamp(value, limit);
+  if (clamped.length === 0) return null;
 
-  tracker.record(`unverifiable-claim:${kind}:${field}`);
-  return null;
+  // Both ways round: clamping collapses whitespace, so "in  stock" only reads as a claim after.
+  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(clamped) ? facts : NO_FACTS;
+
+  const result = verify(clamped, { values: weighed, allowedPhrases: ALLOWED_PHRASES });
+  if (!result.quantity.supported) {
+    tracker.record(`unverifiable-claim:quantity:${field}`);
+    return null;
+  }
+  if (!result.wording.supported) {
+    tracker.record(`unverifiable-claim:wording:${field}`);
+    return null;
+  }
+
+  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.
+ * Emptying a field that cannot be null hands it 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.
+ * Order matters. The budget is checked last because it is the least specific cause:
+ * these strings are the evaluation signal, and reporting a hallucinated SKU as
+ * `budget:dropped` would understate how often the model invents products.
  */
 function rejectionFor(sku: string, allowlist: Allowlist, tracker: PlacementTracker): string | null {
   // A rejected SKU is whatever the model wrote, and the schema cannot bound it.
@@ -438,8 +264,9 @@ function reconcileItems(
   allowlist: Allowlist,
   candidatesBySku: Map<string, Product>,
   digest: SignalDigest,
+  engaged: ReadonlySet<string>,
   tracker: PlacementTracker,
-  hostReasonSkus: ReadonlySet<string>,
+  ourReasons: ReadonlyMap<string, string>,
 ): ProductReference[] {
   const kept: ProductReference[] = [];
 
@@ -456,26 +283,33 @@ function reconcileItems(
 
     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}`);
 
-    const isHostReason =
-      item.reason !== null && hostReasonSkus.has(item.sku) && item.reason === product.reason;
+    // 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);
+    const clampedReason = clampNullable(item.reason, CLAMP.reason);
+
+    // The prose exists to state the basis. If the basis did not hold, the prose
+    // is untrue — and the badge is prose too. "You viewed this" beside a
+    // downgraded pick says the same thing the dropped sentence did.
+    let reason: string | null = null;
+    let badge: string | null = null;
+    if (hasSupportedBasis) {
+      reason = isOurs
+        ? clampedReason
+        : screenClaim(item.reason, CLAMP.reason, `reason:${item.sku}`, tracker, own);
+      // The schema's own example badge was "Back in stock" — a stock claim, and it renders.
+      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
-        ? isHostReason
-          ? clampNullable(item.reason, CLAMP.reason)
-          : screenClaim(clampNullable(item.reason, CLAMP.reason), `reason:${item.sku}`, tracker)
-        : 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),
+      reason,
+      badge,
       emphasis: item.emphasis,
     });
   }
@@ -483,8 +317,7 @@ 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.
+// Cart beats views beats category however the counts compare, so they can't be summed.
 interface BundleFit {
   cartHits: number;
   viewedHits: number;
@@ -507,7 +340,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;
@@ -526,14 +358,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;
@@ -564,9 +394,9 @@ export function bundleForShopper(
   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);
+  const tracker = createPlacementTracker(digest.maxItems, hostFacts(input));
 
   for (const sku of spokenFor) tracker.place(sku);
 
@@ -581,19 +411,14 @@ export function bundleForShopper(
  * 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);
   }
@@ -606,9 +431,10 @@ function reconcileBlock(
   allowlist: Allowlist,
   candidatesBySku: Map<string, Product>,
   digest: SignalDigest,
+  engaged: ReadonlySet<string>,
   bundles: readonly Bundle[],
   tracker: PlacementTracker,
-  hostReasonSkus: ReadonlySet<string>,
+  ourReasons: ReadonlyMap<string, string>,
 ): Block | null {
   switch (block.kind) {
     case 'hero': {
@@ -623,14 +449,8 @@ function reconcileBlock(
           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,
-      );
+      // A hero with no headline and no product is the empty region every other kind drops for.
+      const headline = screenRequired(block.headline, CLAMP.headline, 'hero-headline', tracker);
       if (headline.length === 0 && sku === null) {
         tracker.record('empty-block:hero');
         return null;
@@ -638,9 +458,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),
       };
     }
 
@@ -650,8 +470,9 @@ function reconcileBlock(
         allowlist,
         candidatesBySku,
         digest,
+        engaged,
         tracker,
-        hostReasonSkus,
+        ourReasons,
       );
       if (items.length === 0) {
         tracker.record('empty-block:grid');
@@ -659,7 +480,7 @@ function reconcileBlock(
       }
       return {
         kind: 'grid',
-        title: screenClaim(clampNullable(block.title, CLAMP.blockTitle), 'grid-title', tracker),
+        title: screenClaim(block.title, CLAMP.blockTitle, 'grid-title', tracker),
         // Never leave a grid wider than it has items to fill.
         columns: Math.min(block.columns, Math.max(2, items.length)) as 2 | 3 | 4,
         items,
@@ -672,8 +493,9 @@ function reconcileBlock(
         allowlist,
         candidatesBySku,
         digest,
+        engaged,
         tracker,
-        hostReasonSkus,
+        ourReasons,
       );
       if (items.length === 0) {
         tracker.record('empty-block:carousel');
@@ -681,13 +503,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;
@@ -696,19 +518,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,
       };
     }
@@ -724,9 +546,9 @@ 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),
+        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),
         // The model's bundleId is ignored on purpose.
         bundleId: chosen.id,
       };
@@ -734,14 +556,12 @@ function reconcileBlock(
   }
 }
 
-/** 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),
   );
 }
@@ -751,49 +571,48 @@ export function reconcileSpec(
   input: TrackingInput,
   digest: SignalDigest,
   /**
-   * SKUs whose reason this request wrote from the host's own candidate. Only
-   * `fitToShopper` fills it, so in `per-shopper` mode it is empty and every
+   * 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.
    */
-  hostReasonSkus: ReadonlySet<string> = new Set(),
+  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 tracker = createPlacementTracker(digest.maxItems);
+  const engaged = engagedCategories(input);
+  const tracker = createPlacementTracker(digest.maxItems, hostFacts(input));
 
   if (generated.blocks.length > MAX_BLOCKS) {
     tracker.record(`too-many-blocks:${generated.blocks.length}`);
   }
 
   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,
-      hostReasonSkus,
+      ourReasons,
     );
     if (reconciled !== null) blocks.push(reconciled);
   }
 
   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.
+  // Recorded separately: no products and no headline are different failures.
   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;