@rudra-js/core 0.4.0 → 0.6.0

package/dist/reconciliation.js

@@ -1,25 +1,12 @@
+import { verify } from '@rudra-js/attested';
+import { ALLOWED_PHRASES, claimIn, hostFacts } from './claim-screening.js';
+import { engagedCategories } from './signal-digest.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`.
+ * 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.
  */
+/** Truncation ceilings. Not in the schema — a provider's strict mode rejects length bounds. See `component-spec.ts`. */
 const CLAMP = {
     headline: 90,
     subheadline: 140,
@@ -33,19 +20,17 @@ const CLAMP = {
     // Not rendered anywhere — this is the SKU as it reads back in a violation.
     violationSku: 32,
 };
-/**
- * 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) {
+    return blocks.slice(0, MAX_BLOCKS);
+}
 function clamp(value, limit) {
     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;
@@ -57,45 +42,55 @@ function clampNullable(value, limit) {
     const clamped = clamp(value, limit);
     return clamped.length === 0 ? null : clamped;
 }
+/**
+ * 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) {
+    const refused = new Set();
+    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) {
-    const blocked = new Set([
-        ...digest.dislikedSkus,
-        ...digest.purchasedSkus,
-        ...digest.cartSkus,
-    ]);
-    if (digest.currentSku)
-        blocked.add(digest.currentSku);
+export function neverRecommend(input) {
+    const { signals } = input;
+    const blocked = refusedEverywhere(input);
+    for (const signal of [...signals.lastPurchased, ...signals.cart]) {
+        blocked.add(signal.sku);
+    }
     return blocked;
 }
-function buildAllowlist(input, digest) {
+function buildAllowlist(input) {
     const allowed = new Set();
     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, product, digest) {
+function verifyBasis(basis, product, digest, engaged) {
     switch (basis) {
         case 'most_viewed':
             return digest.topViewed.some((viewed) => viewed.sku === product.sku);
@@ -104,7 +99,11 @@ function verifyBasis(basis, product, digest) {
         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':
@@ -112,221 +111,18 @@ function verifyBasis(basis, product, digest) {
             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.
- *
- * 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 = [
-    {
-        // 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 = {
-    а: '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]/;
-/**
- * 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) {
-    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) {
-    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) {
+/** 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 = [];
+/** The budget and the de-duplication set are global to a spec, not to a block. */
+function createPlacementTracker(maxItems, facts) {
     const placedSkus = new Set();
     const violations = [];
     let remaining = maxItems;
     return {
         violations,
+        facts: facts.pooled,
+        factsFor: (sku) => facts.bySku.get(sku) ?? NO_FACTS,
         get remaining() {
             return remaining;
         },
@@ -341,39 +137,53 @@ function createPlacementTracker(maxItems) {
     };
 }
 /**
- * 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, field, tracker) {
+function screenClaim(value, limit, field, tracker, facts = tracker.facts) {
     if (value === null)
         return null;
-    const kind = claimIn(value);
-    if (kind === null)
-        return value;
-    tracker.record(`unverifiable-claim:${kind}:${field}`);
-    return null;
+    const clamped = clamp(value, limit);
+    if (clamped.length === 0)
+        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, field, tracker) {
-    return screenClaim(value, field, tracker) ?? '';
+function screenRequired(value, limit, field, tracker) {
+    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, allowlist, tracker) {
     // A rejected SKU is whatever the model wrote, and the schema cannot bound it.
@@ -389,7 +199,7 @@ function rejectionFor(sku, allowlist, tracker) {
         return `budget:dropped:${named}`;
     return null;
 }
-function reconcileItems(items, allowlist, candidatesBySku, digest, tracker, hostReasonSkus) {
+function reconcileItems(items, allowlist, candidatesBySku, digest, engaged, tracker, ourReasons) {
     const kept = [];
     for (const item of items) {
         const rejection = rejectionFor(item.sku, allowlist, tracker);
@@ -402,24 +212,30 @@ function reconcileItems(items, allowlist, candidatesBySku, digest, tracker, host
         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}`);
-        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 = null;
+        let badge = 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,
         });
     }
@@ -437,7 +253,6 @@ function fitOf(bundle, digest, candidatesBySku) {
     }
     return fit;
 }
-/** In the cart beats recently viewed, which beats the category being looked at. */
 function isBetterFit(fit, best) {
     if (!best)
         return true;
@@ -451,16 +266,14 @@ function chooseBundle(bundles, allowlist, digest, candidatesBySku, tracker) {
     let best;
     let bestFit;
     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))
+            if (allowlist.blockedInBundle.has(sku))
                 isPlaceable = false;
-            // Already shown by an earlier block — twice on a page looks broken.
             if (tracker.hasPlaced(sku))
                 isPlaceable = false;
         }
@@ -486,9 +299,9 @@ function chooseBundle(bundles, allowlist, digest, candidatesBySku, tracker) {
  * a set is only pre-chosen if reconciliation could still reach for it.
  */
 export function bundleForShopper(input, digest, spokenFor) {
-    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);
     return chooseBundle(input.bundles, allowlist, digest, candidatesBySku, tracker);
@@ -501,8 +314,8 @@ export function bundleForShopper(input, digest, spokenFor) {
  * One this shopper cannot see is dropped below and spends nothing, so it is not
  * counted here either.
  */
-export function placeableHeroSkus(blocks, input, digest) {
-    const allowlist = buildAllowlist(input, digest);
+export function placeableHeroSkus(blocks, input) {
+    const allowlist = buildAllowlist(input);
     const skus = [];
     for (const block of blocks) {
         if (block.kind !== 'hero')
@@ -511,14 +324,13 @@ export function placeableHeroSkus(blocks, input, digest) {
             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);
     }
     return skus;
 }
-function reconcileBlock(block, allowlist, candidatesBySku, digest, bundles, tracker, hostReasonSkus) {
+function reconcileBlock(block, allowlist, candidatesBySku, digest, engaged, bundles, tracker, ourReasons) {
     switch (block.kind) {
         case 'hero': {
             let sku = block.sku;
@@ -533,10 +345,8 @@ function reconcileBlock(block, allowlist, candidatesBySku, digest, bundles, trac
                     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;
@@ -544,39 +354,39 @@ function reconcileBlock(block, allowlist, candidatesBySku, digest, bundles, trac
             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),
             };
         }
         case 'grid': {
-            const items = reconcileItems(block.items, allowlist, candidatesBySku, digest, tracker, hostReasonSkus);
+            const items = reconcileItems(block.items, allowlist, candidatesBySku, digest, engaged, tracker, ourReasons);
             if (items.length === 0) {
                 tracker.record('empty-block:grid');
                 return null;
             }
             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)),
                 items,
             };
         }
         case 'carousel': {
-            const items = reconcileItems(block.items, allowlist, candidatesBySku, digest, tracker, hostReasonSkus);
+            const items = reconcileItems(block.items, allowlist, candidatesBySku, digest, engaged, tracker, ourReasons);
             if (items.length === 0) {
                 tracker.record('empty-block:carousel');
                 return null;
             }
             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;
@@ -585,18 +395,18 @@ function reconcileBlock(block, allowlist, candidatesBySku, digest, bundles, trac
                 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,
             };
         }
@@ -610,52 +420,52 @@ function reconcileBlock(block, allowlist, candidatesBySku, digest, bundles, trac
                 tracker.place(sku);
             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,
             };
         }
     }
 }
-/** True when a spec contains at least one block that actually shows a product. */
 function showsAnyProduct(blocks) {
     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));
 }
 export function reconcileSpec(generated, input, digest, 
 /**
- * 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 = new Set()) {
-    const allowlist = buildAllowlist(input, digest);
+ourReasons = new Map()) {
+    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 = [];
-    for (const block of generated.blocks.slice(0, MAX_BLOCKS)) {
-        const reconciled = reconcileBlock(block, allowlist, candidatesBySku, digest, input.bundles, tracker, hostReasonSkus);
+    for (const block of capBlocks(generated.blocks)) {
+        const reconciled = reconcileBlock(block, allowlist, candidatesBySku, digest, engaged, input.bundles, tracker, ourReasons);
         if (reconciled !== null)
             blocks.push(reconciled);
     }
     const spec = {
         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)