@rudra-js/core 0.4.0 → 0.6.0

package/src/claim-screening.ts

@@ -0,0 +1,242 @@
+import { offeredCandidates } from './model-prompt.js';
+import type { Product, TrackingInput } from './tracking-input.js';
+
+const CLAIM_PATTERNS: { kind: string; patterns: RegExp[] }[] = [
+  {
+    // Customers scoring the product. "rated for winter use", "rated to -10C"
+    // and "an IPX7 water rating" are about what the product can take.
+    kind: 'rating',
+    patterns: [
+      /\breviews?\b|\breviewed\b/,
+      /\b(?:\d+(?:\.\d+)?|three|four|five)[\s-]?stars?\b/,
+      /\bstars?[\s-]?ratings?\b/,
+      // A rating somebody gave it, rather than one it was built to.
+      /\b(?:customer|shopper|buyer|user|average|overall)[\s-]ratings?\b/,
+      // A score out of five is written as a decimal. A spec is "-5C" or "20,000mm".
+      /\bratings?\s+of\s+[0-5]\.\d\b/,
+      // The same score with the word "rating" nowhere near it: "4.8 out of 5".
+      /\b[0-5](?:\.\d)?\s+out of\s+(?:5|five)\b/,
+      /\b(?:highly|top|best|well|poorly|five|four)[\s-]rated\b/,
+      // "rated 4.8" is a score. "rated 3 season" is what the tent is built for.
+      /\brated\s+(?:[0-5]\.\d|(?:[0-5]|three|four|five)\s+(?:stars?|out of))\b/,
+      // How many other people bought or liked it is a customer claim too.
+      /\bbest[\s-]?sell(?:er|ers|ing)\b/,
+      // The words a model reaches for when "best" is banned. Each branch carries its own
+      // \b — one in front of the group demands a word character before the #, never there.
+      /(?:\bnumber one|\bno\.? ?1|#\s?1)[\s-]?sell(?:er|ers|ing)\b/,
+      /\bloved by (?:thousands|hundreds|millions|\d)/,
+    ],
+  },
+  {
+    kind: 'price',
+    patterns: [
+      // No digit beside it: asking for one let "$thirty-nine and it is yours" through.
+      /[$£€¥₹]/,
+      /\b\d+(?:\.\d+)?\s?(?:usd|eur|gbp|dollars?|pounds?|euros?)\b/,
+      // The same spelled out. "pounds" is left off on purpose — a pack weighs two of those.
+      /\bdollars?\b|\beuros?\b/,
+      // The same codes on the other side of the number: "USD 20", "EUR 5.99".
+      /\b(?:usd|eur|gbp)\s?\d/,
+      // The krona is spelled out rather than drawn, so it needs a number beside it.
+      /\bkr\s?\d|\d\s?kr\b/,
+      /\bpric(?:e|es|ed|ing)\b/,
+      // A before-and-after is a price claim even with no currency on it.
+      /\bwas\s+[$£€¥]?\s?\d[\d,.]*\s*[,;–—-]?\s*now\s+[$£€¥]?\s?\d/,
+      // "does not feel cheap" is about quality. Only the comparison is money.
+      /\bcheap(?:er|est)\b/,
+      /\baffordable\b|\bbargain\b/,
+      // "at no cost to comfort" is not money. "costs less" is.
+      /\bcosts?\s+(?:less|more|only|just|about|around|[$£€¥]?\d)/,
+      /\blow(?:er)?[\s-]cost\b/,
+      // "saves weight" and "saves on weight" are both about grams.
+      /\bsaves?\s+(?:you\s+)?(?:money|cash|[$£€¥]\s?\d)/,
+    ],
+  },
+  {
+    // A percentage in outdoor copy is a specification far more often than it is
+    // money off, so it only counts beside a money word: "20% off", not
+    // "100% recycled".
+    kind: 'discount',
+    patterns: [
+      /\d+(?:\.\d+)?\s?(?:%|percent)\s*(?:off\b|discount|reduction|less\b)/,
+      /\b(?:save|saving|savings|off|discount|extra|up to)\s+(?:up to\s+)?\d+(?:\.\d+)?\s?(?:%|percent)/,
+      /\bdiscount(?:s|ed)?\b/,
+      /\bsale\b|\bmarked down\b|\bdeal of\b/,
+      /\bhalf[\s-]?(?:price|off)\b/,
+      // Money off with no percent sign anywhere on it: "save 20 off".
+      /\bsaves?\s+\d[\d.,]*\s+off\b/,
+      // "extra clearance for thick socks" is room inside the shoe.
+      /\bclearance\s+(?:sale|price|event|deal)\b|\bon clearance\b/,
+      // "reduced weight" and "reduced to 900g" are specifications. Only a
+      // reduced price, or a reduction with a date on it, is money off.
+      /\bprice reduced\b|\breduced price\b|\breduced by \d+\s?(?:%|percent)|\breduced\s+(?:this|next|last)\s+week\b/,
+    ],
+  },
+  {
+    // When it turns up, not what turns up. "ships in a recycled box" and
+    // "arrives flat-packed" describe the thing, so the verb alone is not enough
+    // — it needs a day or a date beside it.
+    kind: 'delivery',
+    patterns: [
+      /\bdelivery\b|\bshipping\b/,
+      /\bnext[\s-]day\b|\bsame[\s-]day\b|\bovernight\b/,
+      /\b(?:ships?|arrives?|arriving|delivered|by|before|in time for)\s+(?:on\s+)?(?:today|tomorrow|tonight|this week|next week|the weekend|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/,
+      /\b(?:ships?|arrives?|arriving)\s+(?:in|within)\s+\d/,
+      /\bin time for\b/,
+    ],
+  },
+  {
+    kind: 'stock',
+    patterns: [
+      /\b(?:in|out of|low on) stock\b/,
+      /\blimited stock\b/,
+      /\brestocked?\b|\bsold out\b/,
+      // "the last few miles" is a distance, so a count needs "left" after it.
+      /\b(?:only\s+)?(?:\d+|a few|a handful|a couple|one|few)\s+(?:left|remain(?:s|ing)?)\b/,
+      /\bselling fast\b|\b(?:almost|nearly) gone\b|\bwhile stocks last\b/,
+    ],
+  },
+];
+
+/** Letters that render as a Latin letter but are not one — a Cyrillic о in "in stоck". */
+const CONFUSABLES: Record<string, string> = {
+  а: 'a',
+  в: 'b',
+  е: 'e',
+  к: 'k',
+  м: 'm',
+  н: 'h',
+  о: 'o',
+  р: 'p',
+  с: 'c',
+  т: 't',
+  х: 'x',
+  у: 'y',
+  ѕ: 's',
+  і: 'i',
+  ј: 'j',
+  ԁ: 'd',
+  һ: 'h',
+  ӏ: 'l',
+  α: 'a',
+  ε: 'e',
+  ι: 'i',
+  κ: 'k',
+  ν: 'v',
+  ο: 'o',
+  ρ: 'p',
+  τ: 't',
+  υ: 'u',
+  χ: 'x',
+  ϲ: 'c',
+};
+
+/**
+ * Characters that render as nothing: format characters, default-ignorable code points and the
+ * controls. Cf and Default_Ignorable each hold characters the other does not.
+ * 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: string): string {
+  const lowered = text
+    .replace(INVISIBLE, (char) => (SPACING.test(char) ? char : ''))
+    .normalize('NFKC')
+    .toLowerCase()
+    .normalize('NFC')
+    .replace(MARKS, '');
+
+  let folded = '';
+  for (const char of lowered) folded += CONFUSABLES[char] ?? char;
+  return folded;
+}
+
+/**
+ * Wording attested bans that this project has already ruled is not a claim. An allowance
+ * forgives a banned phrase sitting inside it, so an entry ending on a preposition — "extra
+ * clearance for" — forgives whatever follows it. Exported so a test can hold the list
+ * against attested's own.
+ */
+export const ALLOWED_PHRASES = ['does not feel cheap', "doesn't feel cheap", 'last few miles'];
+
+/** Only a string with one of these in it can stand behind a numeral. */
+const DIGIT = /\p{Nd}/u;
+
+/** A fact whose whole content is a number in exponent notation. attested lays those out in place. */
+const BARE_EXPONENT = /^[+-]?\d+(?:\.\d+)?[eE]([+-]?\d+)$/;
+
+/** Wide enough for every finite JavaScript number, and for anything a shop sells. */
+const MAX_EXPONENT = 1000;
+
+// `1e2000000000` is twelve characters and lays out into a run long enough to end the process.
+// attested caps that itself, but it is a peer dependency and a host's copy of it may be older.
+function canLayOut(fact: string): boolean {
+  const match = BARE_EXPONENT.exec(fact.trim());
+  if (match === null) return true;
+  return Math.abs(Number(match[1] ?? '')) <= MAX_EXPONENT;
+}
+
+/**
+ * The numbers the shop published about one product: its category and tags, only the strings
+ * carrying a digit. Exported so a test can pin what never reaches attested.
+ */
+export function productFacts(product: Product): string[] {
+  const facts: string[] = [];
+  if (DIGIT.test(product.category) && canLayOut(product.category)) facts.push(product.category);
+  for (const tag of product.tags) {
+    if (DIGIT.test(tag) && canLayOut(tag)) facts.push(tag);
+  }
+  return facts;
+}
+
+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 function hostFacts(input: TrackingInput): HostFacts {
+  const pooled = new Set<string>();
+  const bySku = new Map<string, string[]>();
+
+  for (const product of offeredCandidates(input)) {
+    const own = productFacts(product);
+    bySku.set(product.sku, own);
+    for (const fact of own) pooled.add(fact);
+  }
+
+  return { pooled: [...pooled], bySku };
+}
+
+export function claimIn(text: string): string | null {
+  const normalised = normaliseForClaims(text);
+  for (const claim of CLAIM_PATTERNS) {
+    for (const pattern of claim.patterns) {
+      if (pattern.test(normalised)) return claim.kind;
+    }
+  }
+  return null;
+}

package/src/component-generator.ts

@@ -11,14 +11,9 @@ import {
 import { buildFallbackSpec } from './fallback-component.js';
 import { buildPrompt } from './model-prompt.js';
 import type { ComponentProvider, TokenUsage } from './provider.js';
-import {
-  MAX_BLOCKS,
-  bundleForShopper,
-  placeableHeroSkus,
-  reconcileSpec,
-} from './reconciliation.js';
+import { bundleForShopper, capBlocks, placeableHeroSkus, reconcileSpec } from './reconciliation.js';
 import { selectProducts, type RankOrder, type ProductPick } from './product-selection.js';
-import { fitToShopper } from './fit-to-shopper.js';
+import { fitToShopper, type FittedSpec } from './fit-to-shopper.js';
 import { buildDigest, toCohortDigest, type SignalDigest } from './signal-digest.js';
 import {
   createMemorySpecCache,
@@ -139,18 +134,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<T>(
   label: string,
@@ -178,21 +165,13 @@ async function withinBudget<T>(
   }
 }
 
-/**
- * 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<T>() {
-  const inFlight = new Map<string, Promise<T>>();
+function createSingleFlight() {
+  const inFlight = new Map<string, Promise<ModelCall>>();
 
   return {
     isRunning: (key: string) => inFlight.has(key),
 
-    run(key: string, task: () => Promise<T>): Promise<T> {
+    run(key: string, task: () => Promise<ModelCall>): Promise<ModelCall> {
       const existing = inFlight.get(key);
       if (existing) return existing;
 
@@ -214,48 +193,32 @@ interface CacheRead {
   entry?: CachedSpec;
 }
 
-/**
- * What one call to the model produced.
- *
- * `spec` is null when the answer did not satisfy the schema. `usage` is carried
- * either way: the request went out and was paid for whether or not anything
- * usable came back, and those are the calls most worth seeing.
- */
+/** `spec` is null when the answer did not satisfy the schema. `usage` is carried either way: the call was still billed. */
 interface ModelCall {
   spec: GeneratedSpec | null;
   usage?: TokenUsage;
 }
 
-/** A model call whose answer can be reconciled and served. */
 interface ModelAnswer extends ModelCall {
   spec: GeneratedSpec;
 }
 
 /**
- * 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: GeneratedSpec,
   input: TrackingInput,
   digest: SignalDigest,
   rank: RankOrder,
-  hostReasonSkus: Set<string>,
-): GeneratedSpec {
+): FittedSpec {
   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: Block[] = [];
@@ -266,29 +229,28 @@ function fitCohortSpec(
     }
     aboveBundle.push(block);
   }
-  if (!hasBundleBlock) return fitToShopper(spec, picks, digest.maxItems, hostReasonSkus);
+  if (!hasBundleBlock) 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));
-  if (!chosen) return fitToShopper(spec, picks, digest.maxItems, hostReasonSkus);
+  const chosen = bundleForShopper(input, digest, placeableHeroSkus(aboveBundle, input));
+  if (!chosen) return fitToShopper(spec, picks, digest.maxItems);
 
   const spokenFor = new Set<string>(chosen.skus);
-  for (const sku of placeableHeroSkus(blocks, input, digest)) spokenFor.add(sku);
+  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, hostReasonSkus);
+  if (roomLeft <= 0) return fitToShopper(spec, picks, digest.maxItems);
 
   const forGrid: ProductPick[] = [];
   for (const pick of picks) {
     if (!spokenFor.has(pick.product.sku)) forGrid.push(pick);
   }
 
-  return fitToShopper(spec, forGrid, roomLeft, hostReasonSkus);
+  return fitToShopper(spec, forGrid, roomLeft);
 }
 
-/** Attaches the provenance the server owns. The model never supplies any of it. */
 function withProvenance(
   spec: GeneratedSpec,
   provenance: Omit<ComponentSpec, keyof GeneratedSpec | 'specVersion'>,
@@ -305,7 +267,7 @@ export function createComponentGenerator(
   const rank = options.rank ?? 'signals';
   const modelTimeoutMs = options.modelTimeoutMs ?? 1_500;
   const cacheTimeoutMs = options.cacheTimeoutMs ?? 50;
-  const singleFlight = createSingleFlight<ModelCall>();
+  const singleFlight = createSingleFlight();
 
   const report = (event: GenerationEvent): void => {
     if (!options.onEvent) return;
@@ -322,12 +284,6 @@ export function createComponentGenerator(
     startedAt: number,
     key: string | null,
     degradedReason: 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: Pick<GenerationEvent, 'calledModel' | 'usage' | 'violations' | 'cache' | 'error'> = {
       calledModel: false,
     },
@@ -352,36 +308,18 @@ export function createComponentGenerator(
     });
   };
 
-  /**
-   * 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: string): Promise<CacheRead> => {
     try {
       const stored = await withinBudget('cache read', cacheTimeoutMs, () => cache.get(key));
       const parsed = cachedSpecSchema.safeParse(stored);
       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: string, cached: CachedSpec): void => {
     void Promise.resolve()
       .then(() => cache.set(key, cached))
@@ -391,15 +329,10 @@ export function createComponentGenerator(
   };
 
   /**
-   * 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: ComponentProvider,
@@ -439,27 +372,18 @@ export function createComponentGenerator(
         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: ModelAnswer;
-      // 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: number;
 
       if (cached) {
@@ -467,8 +391,7 @@ export function createComponentGenerator(
         generatedAt = cached.generatedAt;
       } 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: ModelCall;
@@ -478,9 +401,6 @@ export function createComponentGenerator(
           );
         } 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,
@@ -502,24 +422,19 @@ export function createComponentGenerator(
         // 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.
-      // Only the cohort path writes a host reason into a spec, so in
+      // 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. In
       // per-shopper mode this stays empty and every reason is screened.
-      const hostReasonSkus = new Set<string>();
-      const served =
+      const { spec: served, ourReasons } =
         generation === 'cohort'
-          ? fitCohortSpec(answer.spec, input, digest, rank, hostReasonSkus)
-          : answer.spec;
+          ? fitCohortSpec(answer.spec, input, digest, rank)
+          : { spec: answer.spec, ourReasons: new Map<string, string>() };
 
-      const reconciled = reconcileSpec(served, input, digest, hostReasonSkus);
+      const reconciled = reconcileSpec(served, input, digest, ourReasons);
       if (!reconciled.isUsable) {
         return buildDeterministic(input, digest, startedAt, key, 'unusable-on-serve', {
           calledModel,

package/src/component-spec.ts

@@ -77,20 +77,9 @@ export const RECOMMENDATION_BASES = [
 export const productReferenceSchema = z.object({
   /** Must be a SKU the host supplied in `TrackingInput.candidates`. */
   sku: z.string(),
-  /**
-   * The strategy behind this pick. Reconciliation checks it against the
-   * shopper's signals, so the model cannot assert a relationship that is not
-   * there.
-   */
+  /** Checked against the shopper's signals, so the model cannot assert a pick it did not earn. */
   basis: z.enum(RECOMMENDATION_BASES),
-  /**
-   * How the basis is phrased for the shopper, e.g. "Pairs with the boots you
-   * bought". Free text, but it has to be consistent with `basis`, which is not.
-   *
-   * Nullable because reconciliation clears it when it cannot verify the basis:
-   * a pick may still be worth showing when the stated reason for it is not
-   * true, but the prose asserting that reason must not render.
-   */
+  /** How the basis is phrased, e.g. "Pairs with the boots you bought". Null once unverifiable. */
   reason: z.string().nullable(),
   /** Short accent label, e.g. "Worth a look". Null when nothing warrants one. */
   badge: z.string().nullable(),
@@ -177,13 +166,11 @@ export const generatedSpecSchema = z.object({
   headline: z.string(),
   subheadline: z.string().nullable(),
   blocks: z.array(blockSchema),
-  /**
-   * One sentence on why this arrangement was chosen. For engineers reading
-   * generation logs, not for shoppers; it is not rendered by default.
-   */
+  /** One sentence for generation logs, not for shoppers. Not rendered by default. */
   rationale: z.string(),
 });
 export type GeneratedSpec = z.infer<typeof generatedSpecSchema>;
+export type GeneratedSpecResult = z.ZodSafeParseResult<GeneratedSpec>;
 
 /** How a spec came to exist. Surfaced for benchmarking and observability. */
 export type SpecSource = 'llm' | 'cache' | 'fallback';
@@ -238,6 +225,6 @@ export function parseGeneratedSpec(value: unknown): GeneratedSpec {
 }
 
 /** Non-throwing variant, for validating untrusted model output. */
-export function safeParseGeneratedSpec(value: unknown) {
+export function safeParseGeneratedSpec(value: unknown): GeneratedSpecResult {
   return generatedSpecSchema.safeParse(value);
 }

package/src/fallback-component.ts

@@ -3,20 +3,6 @@ import type { SignalDigest } from './signal-digest.js';
 import { selectProducts, type SelectOptions, type ProductPick } from './product-selection.js';
 import type { TrackingInput } from './tracking-input.js';
 
-/**
- * The deterministic component — what renders when no model does.
- *
- * The manuscript names data latency as the central risk of moving
- * personalisation onto the server path: any delay in the recommendation engine
- * blocks the page. This module is the answer. It is pure, synchronous, and
- * cannot fail, so the server always has something correct to render — whether
- * the model is slow, erroring, rate-limited, or simply not configured.
- *
- * It reads the same digest and uses the same selector the model path does, so a
- * degraded render is a weaker version of the same decision rather than an
- * unrelated one. Only the presentation is fixed.
- */
-
 /** A featured lead only reads as deliberate when something follows it. */
 const MIN_PICKS_FOR_A_FEATURED_LEAD = 3;
 
@@ -56,6 +42,9 @@ function toProductReference(pick: ProductPick, index: number, total: number): Pr
  * no blocks only when there is genuinely nothing in stock left to show, which
  * the renderer treats as "render nothing" — an empty recommendation region is
  * worse than none.
+ *
+ * Reads the same digest and selector the model path does, so a degraded render is
+ * a weaker version of the same decision rather than an unrelated one.
  */
 export function buildFallbackSpec(
   input: TrackingInput,