@rudra-js/core 0.5.0 → 0.6.0

package/README.md

@@ -120,10 +120,23 @@ before anything renders. A product you left out doesn't reach the page.
 `bundles` is optional. These are the sets you sell together, each with your own
 price for the set, the currency that price is in, and, if you want one, your own
 name for it. Every product in a set has to be a candidate as well. That's what
-lets the same checks that pass a single product pass a whole set, and what lets
+lets the checks that pass a single product run over a whole set, and what lets
 the renderer look the members up in the catalog it already has. Ids must be
 unique, and one set must not name the same product twice.
 
+A set is placed whole, so one check runs differently: a set may hold something
+the shopper already bought or has in the basket, where a grid or a carousel
+would drop it. A thumbs-down on a member still blocks the whole set, and so does
+a member that is out of stock, already on the page, or the product being looked
+at right now.
+
+That last one has a cost. A "frequently bought together, including this item"
+set names the product whose page it sits on, so it is refused on exactly the
+page you wrote it for. Leave the item out and sell the companions as the set —
+that rejection goes away, and the rest of the checks still apply. And when a
+bundle block is the only block the model asked for, refusing the set leaves
+nothing to render, so the deterministic component takes over.
+
 The model _never_ picks a set and is never told a price. All it does is ask for a
 bundle block and write the words around it. We pick which set when the page is
 served, going on what the shopper has in their basket, has looked at, or is
@@ -244,6 +257,30 @@ everyone looking at it shares them. If you pick candidates per shopper you'll ge
 smaller cohorts. That's the honest outcome, because your prompt really is
 personal.
 
+What goes in the key is the _set_ of candidate SKUs. Not the order you sent them
+in, not which ones were in stock, and not where the 60-product cut fell. So two
+requests carrying the same SKUs in a different order share one component, and the
+one generated first is the one both get. If your ranking is personal, order your
+candidates and the products in the copy won't be the ones you put at the top.
+Prices, titles and stock are always read from your catalog at render time, so
+nothing stale is ever shown — a product that sold out is dropped as the page is
+served, and any sentence written about it stays.
+
+#### Who can create a cohort
+
+Every field above is one you supply, and each distinct value is a cohort of its
+own — a fresh model call, and a slot in the cache. If a visitor can choose one of
+them, a visitor can choose how many calls you pay for. A `locale` copied straight
+out of `Accept-Language`, a `currentCategory` read off a URL slug and a `segment`
+built from a query parameter are the three that go wrong. The shipped cache holds
+10,000 entries and drops the oldest, so enough made-up values also evict the
+cohorts your real shoppers were being served from.
+
+Draw those fields from sets you control: your own locale list, your own category
+ids, your own segment labels. Nothing leaks either way — a cohort prompt carries
+no shopper text at all — the cost is the bill and the model round trip on a page
+that was being served from cache.
+
 Pass `generation: 'per-shopper'` to generate for the individual instead. The
 model then chooses the products too, and every shopper pays for their own call.
 
@@ -311,9 +348,19 @@ const generator = createComponentGenerator({ provider, rank: 'given' });
 
 You keep the rest either way. We still drop anything the shopper shouldn't be
 shown, whether it's out of stock, already bought, in the basket, disliked, or
-the product they're looking at right now. Every product still carries a basis
-we check against their real signals, and everything the model writes is still
-screened.
+the product they're looking at right now — read from the payload you sent, not
+from the shortened history the model was shown, so a shopper with a long order
+book is covered too. Every product still carries a basis we check against their
+real signals, and everything the model writes is still screened.
+
+How much each basis proves is worth knowing, because two of the six prove less
+than they read. `most_viewed` is checked against the SKUs they viewed,
+`similar_to_current` against the category being browsed, `liked_category`
+against the categories they bought, liked, carted or viewed in — standing on a
+category page is not one of those — and `popular` claims nothing.
+`complements_cart` and `complements_purchase` check only that the basket, or the
+order history, isn't empty: nothing here can know that one product goes with
+another. A basis that fails takes the sentence and the badge stating it with it.
 
 Each candidate can carry its own `reason`, the phrase shown under the product.
 Reach for it when your ranking knows something the signals don't:

package/dist/claim-screening.d.ts

@@ -0,0 +1,33 @@
+import type { Product, TrackingInput } from './tracking-input.js';
+/**
+ * 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 declare const ALLOWED_PHRASES: string[];
+/**
+ * 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 declare function productFacts(product: Product): string[];
+export interface HostFacts {
+    pooled: string[];
+    bySku: Map<string, string[]>;
+}
+/**
+ * The shop's own numbers for this request, for attested to check numerals against.
+ *
+ * `offeredCandidates` rather than `input.candidates` — out of stock or past the prompt's cap
+ * means a product the model never saw. A title and a rating it is shown but told never to
+ * repeat, so a numeral out of one is one it was told not to write. The browsed category comes
+ * from the request rather than the catalogue, so a host passing a URL segment through would
+ * hand this list to whoever types the URL.
+ *
+ * `pooled` is the soft part of the check: one candidate's "40 litre" backs "take 40 off"
+ * written about another. A `reason` and a `badge` read `bySku`, because they sit under a
+ * named product — off the pooled list, a badge reading "Only 2" stood on a tent's tag.
+ */
+export declare function hostFacts(input: TrackingInput): HostFacts;
+export declare function claimIn(text: string): string | null;
+//# sourceMappingURL=claim-screening.d.ts.map

package/dist/claim-screening.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim-screening.d.ts","sourceRoot":"","sources":["../src/claim-screening.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAmKlE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,UAAkE,CAAC;AAmB/F;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAOvD;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAWzD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQnD"}

package/dist/claim-screening.js

@@ -0,0 +1,226 @@
+import { offeredCandidates } from './model-prompt.js';
+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". */
+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.
+ * A second copy of the class in attested's `hidden.ts`, pinned to it by a test.
+ */
+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. */
+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;
+/** 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;
+/** 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.
+ */
+export 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 };
+}
+export 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;
+}
+//# sourceMappingURL=claim-screening.js.map

package/dist/claim-screening.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim-screening.js","sourceRoot":"","sources":["../src/claim-screening.ts"],"names":[],"mappings":"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"}

package/dist/component-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-generator.d.ts","sourceRoot":"","sources":["../src/component-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAOnE,OAAO,EAAkB,KAAK,SAAS,EAAoB,MAAM,wBAAwB,CAAC;AAG1F,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACtC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAAC;CACjE;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAG9C;CACF;AAgKD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CA8PpB"}
+{"version":3,"file":"component-generator.d.ts","sourceRoot":"","sources":["../src/component-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEnE,OAAO,EAAkB,KAAK,SAAS,EAAoB,MAAM,wBAAwB,CAAC;AAG1F,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACtC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAAC;CACjE;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAG9C;CACF;AA+HD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CA8MpB"}

package/dist/component-generator.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { SPEC_VERSION, generatedSpecSchema, } from './component-spec.js';
 import { buildFallbackSpec } from './fallback-component.js';
 import { buildPrompt } from './model-prompt.js';
-import { MAX_BLOCKS, bundleForShopper, placeableHeroSkus, reconcileSpec, } from './reconciliation.js';
+import { bundleForShopper, capBlocks, placeableHeroSkus, reconcileSpec } from './reconciliation.js';
 import { selectProducts } from './product-selection.js';
 import { fitToShopper } from './fit-to-shopper.js';
 import { buildDigest, toCohortDigest } from './signal-digest.js';
@@ -15,18 +15,10 @@ export class TimeoutError extends Error {
     }
 }
 /**
- * Races a promise against a deadline.
- *
- * The deadline is enforced here rather than trusted to the thing being waited
- * on. A provider that ignores its abort signal, or a store that never settles,
- * must still not hold a page open.
- *
- * Once the deadline has fired the caller is told so, whatever the race
- * actually settled with. Aborting is what makes that necessary: a provider
- * honouring its half of the contract rejects from inside the `abort()` below,
- * so its rejection reaches the race first and the deadline's own never wins.
- * Reporting the error that happened to arrive would blame the vendor for the
- * caller's deadline — and blame it most often on the best-behaved adapters.
+ * Once the deadline has fired the caller is told so, whatever the race actually
+ * settled with: a provider honouring its half of the contract rejects from
+ * inside the `abort()` below, so its rejection reaches the race first and the
+ * deadline's own never wins.
  */
 async function withinBudget(label, milliseconds, start) {
     const controller = new AbortController();
@@ -49,14 +41,6 @@ async function withinBudget(label, milliseconds, start) {
         clearTimeout(timer);
     }
 }
-/**
- * Collapses concurrent work for the same key into one execution.
- *
- * Without this, a key that is not yet cached fans out into one model call per
- * concurrent request — the same answer, bought many times over. The entry is
- * removed as soon as it settles, so one failure does not poison the next
- * attempt.
- */
 function createSingleFlight() {
     const inFlight = new Map();
     return {
@@ -77,24 +61,16 @@ const cachedSpecSchema = z.object({
     generatedAt: z.number(),
 });
 /**
- * Fills a cohort spec with this shopper's products, keeping room for a set.
- *
- * The grid used to take the whole item budget, so a bundle block later in the
- * spec found nothing left and was dropped. The set is chosen first, its
- * products are held back from the grid, and the grid's limit drops by what the
- * set and the heroes have already spoken for.
- *
  * The arithmetic has to hold whatever order the model put the blocks in, so it
  * is written as one sum over the whole spec rather than as a running budget:
  * the grid gets `maxItems` minus every distinct product the set and the heroes
- * will place. Nothing is then dropped for want of budget, and reconciliation
- * reaches the same set this did — it can only ever have more placed than the
- * pre-choice assumed, and never one of the set's own products.
+ * will place. Reconciliation then reaches the same set this did — it can only
+ * ever have more placed than the pre-choice assumed, and never one of the set's
+ * own products.
  */
-function fitCohortSpec(spec, input, digest, rank, ourReasons) {
+function fitCohortSpec(spec, input, digest, rank) {
     const picks = selectProducts(input, digest, { rank });
-    // Blocks past the cap never render, so a set is not worth reserving for one.
-    const blocks = spec.blocks.slice(0, MAX_BLOCKS);
+    const blocks = capBlocks(spec.blocks);
     let hasBundleBlock = false;
     const aboveBundle = [];
     for (const block of blocks) {
@@ -105,27 +81,26 @@ function fitCohortSpec(spec, input, digest, rank, ourReasons) {
         aboveBundle.push(block);
     }
     if (!hasBundleBlock)
-        return fitToShopper(spec, picks, digest.maxItems, ourReasons);
+        return fitToShopper(spec, picks, digest.maxItems);
     // Only the heroes above the bundle block are placed when it is reached, so
     // they are all the choice may account for.
-    const chosen = bundleForShopper(input, digest, placeableHeroSkus(aboveBundle, input, digest));
+    const chosen = bundleForShopper(input, digest, placeableHeroSkus(aboveBundle, input));
     if (!chosen)
-        return fitToShopper(spec, picks, digest.maxItems, ourReasons);
+        return fitToShopper(spec, picks, digest.maxItems);
     const spokenFor = new Set(chosen.skus);
-    for (const sku of placeableHeroSkus(blocks, input, digest))
+    for (const sku of placeableHeroSkus(blocks, input))
         spokenFor.add(sku);
     const roomLeft = digest.maxItems - spokenFor.size;
     // A set is worth showing, but not at the cost of an empty grid.
     if (roomLeft <= 0)
-        return fitToShopper(spec, picks, digest.maxItems, ourReasons);
+        return fitToShopper(spec, picks, digest.maxItems);
     const forGrid = [];
     for (const pick of picks) {
         if (!spokenFor.has(pick.product.sku))
             forGrid.push(pick);
     }
-    return fitToShopper(spec, forGrid, roomLeft, ourReasons);
+    return fitToShopper(spec, forGrid, roomLeft);
 }
-/** Attaches the provenance the server owns. The model never supplies any of it. */
 function withProvenance(spec, provenance) {
     return { ...spec, specVersion: SPEC_VERSION, ...provenance };
 }
@@ -147,14 +122,7 @@ export function createComponentGenerator(options = {}) {
             // A broken metrics hook must not take down a page.
         }
     };
-    const buildDeterministic = (input, digest, startedAt, key, degradedReason, 
-    /**
-     * What the model call cost, when there was one. A generation that is
-     * unusable for this shopper was still asked for and still billed, so
-     * omitting it here would hide the calls that produce nothing — exactly the
-     * ones worth knowing about.
-     */
-    modelCall = {
+    const buildDeterministic = (input, digest, startedAt, key, degradedReason, modelCall = {
         calledModel: false,
     }) => {
         const finishedAt = Date.now();
@@ -175,15 +143,6 @@ export function createComponentGenerator(options = {}) {
             degradedReason,
         });
     };
-    /**
-     * Reads the cache, treating anything unexpected as a miss.
-     *
-     * The value is re-validated because a store is a port a host implements, and
-     * what comes back is no more trustworthy than what a model returns — a shared
-     * store outlives a deploy, so it can hold entries written by an older shape of
-     * the spec. Generating again is always safe; handing an unvalidated object to
-     * reconciliation is not.
-     */
     const readCache = async (key) => {
         try {
             const stored = await withinBudget('cache read', cacheTimeoutMs, () => cache.get(key));
@@ -191,20 +150,11 @@ export function createComponentGenerator(options = {}) {
             return parsed.success ? { outcome: 'hit', entry: parsed.data } : { outcome: 'miss' };
         }
         catch (error) {
-            // A store that is down or slow degrades to generating, not to an error
-            // page. Nothing here is worth failing a render over.
+            // A store that is down or slow degrades to generating, not to an error page.
             return { outcome: error instanceof TimeoutError ? 'timeout' : 'error' };
         }
     };
-    /**
-     * Writes to the cache without the render waiting for it.
-     *
-     * The spec is already in hand; nothing downstream needs the write to finish.
-     * Awaiting it put a second unbounded call to a host-implemented store on the
-     * render path, which is the failure this module exists to prevent arriving
-     * through the other door. The `Promise.resolve` wrapper is what catches a
-     * store that throws synchronously rather than rejecting.
-     */
+    /** The `Promise.resolve` wrapper catches a store that throws synchronously rather than rejecting. */
     const storeInBackground = (key, cached) => {
         void Promise.resolve()
             .then(() => cache.set(key, cached))
@@ -213,15 +163,10 @@ export function createComponentGenerator(options = {}) {
         });
     };
     /**
-     * Asks the model.
-     *
      * Deliberately does not decide whether the answer is usable. That depends on
      * the asking shopper's live facts — stock, dislikes, what is in their basket
      * — and none of those are in the cache key, so a verdict reached here would
-     * be handed to every request that joined this one. A null `spec` in the
-     * result means the answer did not satisfy the schema, which is a fault of the
-     * adapter rather than a judgement about any shopper — and is still a call
-     * that happened, so its usage comes back with it.
+     * be handed to every request that joined this one.
      */
     const askModel = async (active, input, promptDigest) => {
         const { system, user } = buildPrompt(input, promptDigest);
@@ -248,17 +193,16 @@ export function createComponentGenerator(options = {}) {
             if (!provider) {
                 return buildDeterministic(input, digest, startedAt, null, 'no-provider');
             }
-            const providerId = `${provider.name}:${provider.model}`;
+            const identity = { name: provider.name, model: provider.model };
+            const candidateSkus = input.candidates.map((product) => product.sku);
             const key = generation === 'cohort'
-                ? cohortCacheKey(digest, input.candidates.map((product) => product.sku), providerId)
-                : specCacheKey(digest, input.candidates.map((product) => product.sku), providerId);
+                ? cohortCacheKey(digest, candidateSkus, identity)
+                : specCacheKey(digest, candidateSkus, identity);
             const read = await readCache(key);
             const cached = read.entry;
             let calledModel = false;
             let answer;
-            // When the model produced this, not when it was served. A cached
-            // component is not newly generated, and pretending otherwise makes any
-            // measure of how stale a page is showing read as zero.
+            // When the model produced this, not when it was served.
             let generatedAt;
             if (cached) {
                 answer = { spec: cached.spec };
@@ -266,8 +210,7 @@ export function createComponentGenerator(options = {}) {
             }
             else {
                 // Asked before joining, because by the time the shared promise settles
-                // the entry is gone and there is no way to tell a leader from a
-                // follower — and they must not both be counted as a model call.
+                // the entry is gone and there is no way to tell a leader from a follower.
                 calledModel = !singleFlight.isRunning(key);
                 let call;
                 try {
@@ -275,9 +218,6 @@ export function createComponentGenerator(options = {}) {
                 }
                 catch (error) {
                     const reason = error instanceof TimeoutError ? 'timeout' : 'provider-error';
-                    // The request went out. Leaving `calledModel` to default here reported
-                    // every failed call as no call at all, so the calls that cost money
-                    // and produced nothing were the only ones missing from the count.
                     return buildDeterministic(input, digest, startedAt, key, reason, {
                         calledModel,
                         cache: read.outcome,
@@ -296,22 +236,16 @@ export function createComponentGenerator(options = {}) {
                 // Stored unreconciled on purpose, and stored even when it is unusable
                 // for this shopper. Reconciliation narrows a spec to one shopper's live
                 // facts, and those move independently of the key — a product can sell
-                // out and come back without the candidate list changing. Keeping what
-                // the model said means the restock is picked up from cache rather than
-                // paid for again.
+                // out and come back without the candidate list changing.
                 if (calledModel)
                     storeInBackground(key, { spec: answer.spec, generatedAt });
             }
-            // One place where anything is served, whichever side of the cache it came
-            // from, and always against the facts of the shopper asking now.
             // A cohort spec names products chosen for whoever asked first, and every
-            // reason under one of them is written here rather than by the model. Only
-            // the cohort path does that, so in per-shopper mode this stays empty and
-            // every reason is screened.
-            const ourReasons = new Map();
-            const served = generation === 'cohort'
-                ? fitCohortSpec(answer.spec, input, digest, rank, ourReasons)
-                : answer.spec;
+            // reason under one of them is written here rather than by the model. In
+            // per-shopper mode this stays empty and every reason is screened.
+            const { spec: served, ourReasons } = generation === 'cohort'
+                ? fitCohortSpec(answer.spec, input, digest, rank)
+                : { spec: answer.spec, ourReasons: new Map() };
             const reconciled = reconcileSpec(served, input, digest, ourReasons);
             if (!reconciled.isUsable) {
                 return buildDeterministic(input, digest, startedAt, key, 'unusable-on-serve', {