@rudra-js/core 0.5.0 → 0.7.0

package/dist/reconciliation.js

@@ -1,27 +1,6 @@
 import { verify } from '@rudra-js/attested';
-import { offeredCandidates } from './model-prompt.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`.
- */
+import { ALLOWED_PHRASES, claimIn, hostFacts } from './claim-screening.js';
+import { engagedCategories } from './signal-digest.js';
 const CLAMP = {
     headline: 90,
     subheadline: 140,
@@ -32,72 +11,50 @@ const CLAMP = {
     bannerText: 160,
     copyBody: 420,
     rationale: 300,
-    // 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.
- */
 export const MAX_BLOCKS = 4;
+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.
     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, limit) {
-    if (value === null)
-        return null;
-    const clamped = clamp(value, limit);
-    return clamped.length === 0 ? null : clamped;
+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.
- *
- * 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);
@@ -106,289 +63,16 @@ 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);
+            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 = [
-    {
-        // 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 = {
-    а: '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) {
-    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 = [];
-/** 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) {
-    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) {
-    const facts = [];
-    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;
-}
-/**
- * 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) {
-    const pooled = new Set();
-    const bySku = new Map();
-    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) {
-    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, facts) {
     const placedSkus = new Set();
     const violations = [];
@@ -410,30 +94,19 @@ function createPlacementTracker(maxItems, facts) {
         },
     };
 }
-/**
- * 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, field, tracker, facts = tracker.facts) {
+function screenClaim(value, limit, field, tracker, facts = tracker.facts) {
     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 result = verify(value, { values: weighed, allowedPhrases: ALLOWED_PHRASES });
+    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;
@@ -442,31 +115,13 @@ function screenClaim(value, field, tracker, facts = tracker.facts) {
         tracker.record(`unverifiable-claim:wording:${field}`);
         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, 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.
- */
 function rejectionFor(sku, allowlist, tracker) {
-    // 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))
@@ -477,7 +132,7 @@ function rejectionFor(sku, allowlist, tracker) {
         return `budget:dropped:${named}`;
     return null;
 }
-function reconcileItems(items, allowlist, candidatesBySku, digest, tracker, ourReasons) {
+function reconcileItems(items, allowlist, candidatesBySku, digest, engaged, tracker, ourReasons) {
     const kept = [];
     for (const item of items) {
         const rejection = rejectionFor(item.sku, allowlist, tracker);
@@ -486,30 +141,27 @@ function reconcileItems(items, allowlist, candidatesBySku, digest, tracker, ourR
             continue;
         }
         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 = null;
+        let badge = 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,
         });
     }
@@ -527,7 +179,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;
@@ -541,16 +192,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;
         }
@@ -564,35 +213,16 @@ function chooseBundle(bundles, allowlist, digest, candidatesBySku, tracker) {
     }
     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, 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, hostFacts(input));
     for (const sku of spokenFor)
         tracker.place(sku);
     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, 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')
@@ -601,14 +231,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, ourReasons) {
+function reconcileBlock(block, allowlist, candidatesBySku, digest, engaged, bundles, tracker, ourReasons) {
     switch (block.kind) {
         case 'hero': {
             let sku = block.sku;
@@ -616,17 +245,13 @@ function reconcileBlock(block, allowlist, candidatesBySku, digest, bundles, trac
                 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;
@@ -634,39 +259,38 @@ 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, ourReasons);
+            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),
-                // 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)),
                 items,
             };
         }
         case 'carousel': {
-            const items = reconcileItems(block.items, allowlist, candidatesBySku, digest, tracker, ourReasons);
+            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;
@@ -675,18 +299,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,
             };
         }
@@ -700,55 +324,41 @@ 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),
-                // 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) {
     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, 
-/**
- * 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 = new Map()) {
-    const allowlist = buildAllowlist(input, digest);
+export function reconcileSpec(generated, input, digest, ourReasons = new Map()) {
+    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) {
         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, ourReasons);
+    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.
     if (!showsAnyProduct(blocks))
         tracker.record('unusable:no-products');
     if (spec.headline.length === 0)