@rudra-js/core 0.1.0 → 0.3.1

package/src/fallback-component.ts

@@ -1,6 +1,6 @@
 import type { GeneratedSpec, ProductReference } from './component-spec.js';
 import type { SignalDigest } from './signal-digest.js';
-import { selectProducts, type ProductPick } from './product-selection.js';
+import { selectProducts, type SelectOptions, type ProductPick } from './product-selection.js';
 import type { TrackingInput } from './tracking-input.js';
 
 /**
@@ -57,8 +57,12 @@ function toProductReference(pick: ProductPick, index: number, total: number): Pr
  * the renderer treats as "render nothing" — an empty recommendation region is
  * worse than none.
  */
-export function buildFallbackSpec(input: TrackingInput, digest: SignalDigest): GeneratedSpec {
-  const picks = selectProducts(input, digest).slice(0, digest.maxItems);
+export function buildFallbackSpec(
+  input: TrackingInput,
+  digest: SignalDigest,
+  options: SelectOptions = {},
+): GeneratedSpec {
+  const picks = selectProducts(input, digest, options).slice(0, digest.maxItems);
   const { headline, subheadline } = headlineFor(digest);
   const items = picks.map((pick, index) => toProductReference(pick, index, picks.length));
 

package/src/fit-to-shopper.ts

@@ -1,12 +1,13 @@
 import type { Block, GeneratedSpec, ProductReference } from './component-spec.js';
 import type { ProductPick } from './product-selection.js';
 
-// The model picks the shape of the component. Selection picks the products and
+// The model picks the shape. Selection picks the grid and carousel products and
 // what may be said about them, so a shared component still fits one shopper.
 export function fitToShopper(
   spec: GeneratedSpec,
   picks: readonly ProductPick[],
   maxItems: number,
+  hostReasonSkus?: Set<string>,
 ): GeneratedSpec {
   // Picks are ordered best first. Every slot takes the next one.
   let next = 0;
@@ -24,6 +25,7 @@ export function fitToShopper(
       for (const item of block.items) {
         if (next >= limit) break; // shrink, never pad
         const chosen = picks[next]!;
+        if (chosen.reasonFromHost) hostReasonSkus?.add(chosen.product.sku);
         items.push({
           sku: chosen.product.sku,
           basis: chosen.basis,

package/src/index.ts

@@ -69,10 +69,8 @@ export {
   type SpecSource,
 } from './component-spec.js';
 
-export { neverRecommend, reconcileSpec, type ReconcileResult } from './reconciliation.js';
+export { reconcileSpec, type ReconcileResult } from './reconciliation.js';
 export { selectProducts, type ProductPick } from './product-selection.js';
-export { fitToShopper } from './fit-to-shopper.js';
-export { buildFallbackSpec } from './fallback-component.js';
 
 export {
   createFixedSpecProvider,
@@ -85,14 +83,12 @@ export {
 export {
   createMemorySpecCache,
   createNullSpecCache,
-  cohortCacheKey,
-  specCacheKey,
   type CachedSpec,
   type MemorySpecCacheOptions,
   type SpecCache,
 } from './spec-cache.js';
 
-export { SYSTEM_PROMPT, buildPrompt, type PromptPair } from './model-prompt.js';
+export { buildPrompt, type PromptPair } from './model-prompt.js';
 
 export {
   createComponentGenerator,

package/src/product-selection.ts

@@ -23,6 +23,8 @@ export interface ProductPick {
   basis: RecommendationBasis;
   /** How the basis reads to a shopper. */
   reason: string;
+  /** True when `reason` is the host's own sentence from the candidate. */
+  reasonFromHost: boolean;
   /** Unnormalised. Only the ordering is meaningful. */
   score: number;
 }
@@ -95,9 +97,6 @@ function basisFor(
   if (evidence.hasCart) {
     return { basis: 'complements_cart', reason: 'Goes with what is in your cart' };
   }
-  if ((product.rating ?? 0) >= 4.5) {
-    return { basis: 'popular', reason: 'Highly rated' };
-  }
   return { basis: 'popular', reason: `Popular in ${product.category}` };
 }
 
@@ -107,7 +106,24 @@ function basisFor(
  * Ties break on SKU so the order is total: two runs over the same payload
  * produce the same list, which is what makes the control arm reproducible.
  */
-export function selectProducts(input: TrackingInput, digest: SignalDigest): ProductPick[] {
+/** How the picks are ordered once the unplaceable ones are gone. */
+export type RankOrder = 'signals' | 'given';
+
+export interface SelectOptions {
+  /**
+   * `signals` scores each candidate and orders by that score. `given` keeps the
+   * order you sent, for a shop whose own ranking is better than four weights.
+   * Either way the exclusions and the stock check still apply, and every pick
+   * still carries a basis reconciliation can verify.
+   */
+  rank?: RankOrder;
+}
+
+export function selectProducts(
+  input: TrackingInput,
+  digest: SignalDigest,
+  options: SelectOptions = {},
+): ProductPick[] {
   const affinityByCategory = new Map(
     digest.categoryAffinity.map((affinity) => [affinity.category, affinity.score]),
   );
@@ -144,9 +160,17 @@ export function selectProducts(input: TrackingInput, digest: SignalDigest): Prod
       hasCart,
     });
 
-    picks.push({ product, basis, reason, score });
+    picks.push({
+      product,
+      basis,
+      reason: product.reason ?? reason,
+      reasonFromHost: product.reason !== undefined,
+      score,
+    });
   }
 
+  if (options.rank === 'given') return picks;
+
   return picks.toSorted(
     (left, right) => right.score - left.score || left.product.sku.localeCompare(right.product.sku),
   );

package/src/reconciliation.ts

@@ -40,6 +40,8 @@ const CLAMP = {
   bannerText: 160,
   copyBody: 420,
   rationale: 300,
+  // Not rendered anywhere — this is the SKU as it reads back in a violation.
+  violationSku: 32,
 } as const;
 
 /**
@@ -175,6 +177,8 @@ const CLAIM_PATTERNS: { kind: string; patterns: RegExp[] }[] = [
       /\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/,
@@ -186,8 +190,12 @@ const CLAIM_PATTERNS: { kind: string; patterns: RegExp[] }[] = [
   {
     kind: 'price',
     patterns: [
-      /[$£€¥]\s?\d/,
+      /[$£€¥₹]\s?\d/,
       /\b\d+(?:\.\d+)?\s?(?:usd|eur|gbp|dollars?|pounds?|euros?)\b/,
+      // The same codes on the other side of the number: "USD 20", "EUR 5.99".
+      /\b(?:usd|eur|gbp)\s?\d/,
+      // The krona is spelled out rather than drawn, so it needs a number beside it.
+      /\bkr\s?\d|\d\s?kr\b/,
       /\bpric(?:e|es|ed|ing)\b/,
       // A before-and-after is a price claim even with no currency on it.
       /\bwas\s+[$£€¥]?\s?\d[\d,.]*\s*[,;–—-]?\s*now\s+[$£€¥]?\s?\d/,
@@ -212,6 +220,8 @@ const CLAIM_PATTERNS: { kind: string; patterns: RegExp[] }[] = [
       /\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
@@ -236,10 +246,10 @@ const CLAIM_PATTERNS: { kind: string; patterns: RegExp[] }[] = [
     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|remaining)\b/,
-      /\blast (?:one|few)\s+(?:left|remaining|in stock)\b/,
+      /\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/,
     ],
   },
@@ -329,11 +339,14 @@ function screenRequired(value: string, field: string, tracker: PlacementTracker)
  * so each one has to name the fault that actually fired.
  */
 function rejectionFor(sku: string, allowlist: Allowlist, tracker: PlacementTracker): string | null {
+  // 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:${sku}`;
-  if (allowlist.blocked.has(sku)) return `blocked-sku:${sku}`;
-  if (tracker.hasPlaced(sku)) return `duplicate-sku:${sku}`;
-  if (tracker.remaining <= 0) return `budget:dropped:${sku}`;
+  if (!allowlist.allowed.has(sku)) return `unknown-sku:${named}`;
+  if (allowlist.blocked.has(sku)) return `blocked-sku:${named}`;
+  if (tracker.hasPlaced(sku)) return `duplicate-sku:${named}`;
+  if (tracker.remaining <= 0) return `budget:dropped:${named}`;
   return null;
 }
 
@@ -343,6 +356,7 @@ function reconcileItems(
   candidatesBySku: Map<string, Product>,
   digest: SignalDigest,
   tracker: PlacementTracker,
+  hostReasonSkus: ReadonlySet<string>,
 ): ProductReference[] {
   const kept: ProductReference[] = [];
 
@@ -362,15 +376,23 @@ function reconcileItems(
     const hasSupportedBasis = verifyBasis(item.basis, product, digest);
     if (!hasSupportedBasis) tracker.record(`unsupported-basis:${item.basis}:${item.sku}`);
 
+    const isHostReason =
+      item.reason !== null && hostReasonSkus.has(item.sku) && item.reason === product.reason;
+
     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
-        ? screenClaim(clampNullable(item.reason, CLAMP.reason), `reason:${item.sku}`, tracker)
+        ? isHostReason
+          ? clampNullable(item.reason, CLAMP.reason)
+          : screenClaim(clampNullable(item.reason, CLAMP.reason), `reason:${item.sku}`, tracker)
         : null,
-      badge: clampNullable(item.badge, CLAMP.badge),
+      // 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),
       emphasis: item.emphasis,
     });
   }
@@ -503,6 +525,7 @@ function reconcileBlock(
   digest: SignalDigest,
   bundles: readonly Bundle[],
   tracker: PlacementTracker,
+  hostReasonSkus: ReadonlySet<string>,
 ): Block | null {
   switch (block.kind) {
     case 'hero': {
@@ -539,7 +562,14 @@ function reconcileBlock(
     }
 
     case 'grid': {
-      const items = reconcileItems(block.items, allowlist, candidatesBySku, digest, tracker);
+      const items = reconcileItems(
+        block.items,
+        allowlist,
+        candidatesBySku,
+        digest,
+        tracker,
+        hostReasonSkus,
+      );
       if (items.length === 0) {
         tracker.record('empty-block:grid');
         return null;
@@ -554,7 +584,14 @@ function reconcileBlock(
     }
 
     case 'carousel': {
-      const items = reconcileItems(block.items, allowlist, candidatesBySku, digest, tracker);
+      const items = reconcileItems(
+        block.items,
+        allowlist,
+        candidatesBySku,
+        digest,
+        tracker,
+        hostReasonSkus,
+      );
       if (items.length === 0) {
         tracker.record('empty-block:carousel');
         return null;
@@ -630,6 +667,12 @@ export function reconcileSpec(
   generated: GeneratedSpec,
   input: TrackingInput,
   digest: SignalDigest,
+  /**
+   * SKUs whose reason this request wrote from the host's own candidate. Only
+   * `fitToShopper` fills it, so in `per-shopper` mode it is empty and every
+   * reason is the model's, including one that happens to read the same.
+   */
+  hostReasonSkus: ReadonlySet<string> = new Set(),
 ): ReconcileResult {
   const allowlist = buildAllowlist(input, digest);
   const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
@@ -648,6 +691,7 @@ export function reconcileSpec(
       digest,
       input.bundles,
       tracker,
+      hostReasonSkus,
     );
     if (reconciled !== null) blocks.push(reconciled);
   }
@@ -661,7 +705,7 @@ export function reconcileSpec(
       tracker,
     ),
     blocks,
-    rationale: clamp(generated.rationale, CLAMP.rationale),
+    rationale: screenRequired(clamp(generated.rationale, CLAMP.rationale), 'rationale', tracker),
   };
 
   // A component that recommends nothing is worse than no component at all.

package/src/signal-digest.ts

@@ -230,14 +230,17 @@ function mergeViewsBySku(views: ViewSignal[]): MergedView[] {
 
 /** The most-viewed few, as the digest reports them. */
 function mostViewedProducts(views: ViewSignal[]): ViewedProduct[] {
-  return mergeViewsBySku(views)
+  const top = mergeViewsBySku(views)
     .toSorted((left, right) => right.views - left.views)
-    .slice(0, DIGEST_LIMITS.viewed)
-    .map(({ sku, views: viewCount, dwellMs }) => ({
-      sku,
-      views: viewCount,
-      ...(dwellMs !== undefined ? { dwellMs } : {}),
-    }));
+    .slice(0, DIGEST_LIMITS.viewed);
+
+  const products: ViewedProduct[] = [];
+  for (const merged of top) {
+    const product: ViewedProduct = { sku: merged.sku, views: merged.views };
+    if (merged.dwellMs !== undefined) product.dwellMs = merged.dwellMs;
+    products.push(product);
+  }
+  return products;
 }
 
 /** The open-vocabulary long tail, reduced to "which kinds, and how often". */

package/src/spec-cache.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { SPEC_VERSION, type GeneratedSpec } from './component-spec.js';
+import { SYSTEM_PROMPT } from './model-prompt.js';
 import type { SignalDigest } from './signal-digest.js';
 
 /**
@@ -15,11 +16,6 @@ import type { SignalDigest } from './signal-digest.js';
  * instance count.
  */
 
-/**
- * Asynchronous on purpose. A synchronous `get` would look simpler and would
- * make the shared store the docs recommend impossible to write, since no Redis
- * or Memcached client can return a value without awaiting.
- */
 /**
  * A stored generation, with the moment it was produced.
  *
@@ -33,9 +29,15 @@ export interface CachedSpec {
   generatedAt: number;
 }
 
+/**
+ * Asynchronous on purpose. A synchronous `get` would look simpler and would
+ * make the shared store the docs recommend impossible to write, since no Redis
+ * or Memcached client can return a value without awaiting.
+ */
 export interface SpecCache {
   get(key: string): Promise<CachedSpec | undefined>;
   set(key: string, cached: CachedSpec): Promise<void>;
+  delete?(key: string): Promise<void>;
 }
 
 export interface MemorySpecCacheOptions {
@@ -115,6 +117,10 @@ export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): Spe
         entries.delete(oldest.value);
       }
     },
+
+    async delete(key) {
+      entries.delete(key);
+    },
   };
 }
 
@@ -148,6 +154,8 @@ function canonicalise(value: unknown): string {
   return `{${entries.map(([name, fieldValue]) => `${JSON.stringify(name)}:${canonicalise(fieldValue)}`).join(',')}}`;
 }
 
+const PROMPT_FINGERPRINT = createHash('sha256').update(SYSTEM_PROMPT).digest('hex').slice(0, 16);
+
 /**
  * Derives the cache key.
  *
@@ -182,6 +190,7 @@ export function specCacheKey(
     // The spec's own version, so a shape change cannot read entries written by
     // the previous shape out of a shared store that outlives a deploy.
     specVersion: SPEC_VERSION,
+    prompt: PROMPT_FINGERPRINT,
     provider: providerId,
     digest,
     candidates: candidateSkus.toSorted(),
@@ -201,6 +210,7 @@ export function cohortCacheKey(
 ): string {
   const material = canonicalise({
     specVersion: SPEC_VERSION,
+    prompt: PROMPT_FINGERPRINT,
     provider: providerId,
     segment: digest.segment ?? null,
     surface: digest.surface,

package/src/tracking-input.ts

@@ -42,6 +42,11 @@ export const FIELD_LIMITS = {
   candidates: 200,
   productsPerBundle: 5,
   bundles: 20,
+  localeTag: 35,
+  maxItems: 12,
+  // Matches CLAMP.reason in reconciliation: a host reason is rendered in the
+  // same place a model's is, so the same length has to hold.
+  reason: 120,
 } as const;
 
 /** Assigning this as an object key mutates the prototype instead of the object. */
@@ -93,6 +98,10 @@ export const productSchema = z.strictObject({
   // scheme to abuse.
   imageUrl: imageReference().optional(),
   rating: z.number().min(0).max(5).optional(),
+  // Your phrase for why this product is here, when your own ranking already has
+  // one. It renders as the item's reason and is not screened: these are your
+  // words about your product, like the title, so you stand behind them.
+  reason: z.string().min(1).max(FIELD_LIMITS.reason).optional(),
   isInStock: z.boolean().default(true),
   tags: z
     .array(z.string().min(1).max(FIELD_LIMITS.tag))
@@ -179,9 +188,15 @@ export const renderContextSchema = z.strictObject({
   currentSku: optionalIdentifier(),
   currentCategory: optionalIdentifier(),
   searchQuery: z.string().max(FIELD_LIMITS.searchQuery).optional(),
-  locale: z.string().min(2).max(35).default('en-US'),
+  // One language tag, not the Accept-Language header it is often copied from:
+  // the locale is part of the cohort cache key, so a list makes its own cohort.
+  locale: z
+    .string()
+    .max(FIELD_LIMITS.localeTag)
+    .regex(/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/, 'expected one language tag, such as en-US')
+    .default('en-US'),
   /** Upper bound on products across the whole generated component. */
-  maxItems: z.number().int().min(1).max(12).default(4),
+  maxItems: z.number().int().min(1).max(FIELD_LIMITS.maxItems).default(4),
 });
 export type RenderContext = z.infer<typeof renderContextSchema>;