@rudra-js/core 0.2.0 → 0.3.1

package/src/component-generator.ts

@@ -17,7 +17,7 @@ import {
   placeableHeroSkus,
   reconcileSpec,
 } from './reconciliation.js';
-import { selectProducts, type ProductPick } from './product-selection.js';
+import { selectProducts, type RankOrder, type ProductPick } from './product-selection.js';
 import { fitToShopper } from './fit-to-shopper.js';
 import { buildDigest, toCohortDigest, type SignalDigest } from './signal-digest.js';
 import {
@@ -113,6 +113,14 @@ export interface ComponentGeneratorOptions {
    * 'cohort'.
    */
   generation?: 'cohort' | 'per-shopper';
+  /**
+   * How the products are ordered. 'signals' scores each candidate from this
+   * shopper's signals. '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 each product still carries a basis
+   * reconciliation can verify. Defaults to 'signals'.
+   */
+  rank?: RankOrder;
   /** Observability. Never allowed to break a render. */
   onEvent?: (event: GenerationEvent) => void;
 }
@@ -242,8 +250,10 @@ function fitCohortSpec(
   spec: GeneratedSpec,
   input: TrackingInput,
   digest: SignalDigest,
+  rank: RankOrder,
+  hostReasonSkus: Set<string>,
 ): GeneratedSpec {
-  const picks = selectProducts(input, digest);
+  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);
 
@@ -256,26 +266,26 @@ function fitCohortSpec(
     }
     aboveBundle.push(block);
   }
-  if (!hasBundleBlock) return fitToShopper(spec, picks, digest.maxItems);
+  if (!hasBundleBlock) return fitToShopper(spec, picks, digest.maxItems, hostReasonSkus);
 
   // 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);
+  if (!chosen) return fitToShopper(spec, picks, digest.maxItems, hostReasonSkus);
 
   const spokenFor = new Set<string>(chosen.skus);
   for (const sku of placeableHeroSkus(blocks, input, digest)) 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);
+  if (roomLeft <= 0) return fitToShopper(spec, picks, digest.maxItems, hostReasonSkus);
 
   const forGrid: ProductPick[] = [];
   for (const pick of picks) {
     if (!spokenFor.has(pick.product.sku)) forGrid.push(pick);
   }
 
-  return fitToShopper(spec, forGrid, roomLeft);
+  return fitToShopper(spec, forGrid, roomLeft, hostReasonSkus);
 }
 
 /** Attaches the provenance the server owns. The model never supplies any of it. */
@@ -292,6 +302,7 @@ export function createComponentGenerator(
   const provider = options.provider ?? null;
   const cache = options.cache ?? createMemorySpecCache();
   const generation = options.generation ?? 'cohort';
+  const rank = options.rank ?? 'signals';
   const modelTimeoutMs = options.modelTimeoutMs ?? 1_500;
   const cacheTimeoutMs = options.cacheTimeoutMs ?? 50;
   const singleFlight = createSingleFlight<ModelCall>();
@@ -330,7 +341,7 @@ export function createComponentGenerator(
       degradedReason,
     });
 
-    return withProvenance(buildFallbackSpec(input, digest), {
+    return withProvenance(buildFallbackSpec(input, digest, { rank }), {
       slot: digest.slot,
       source: 'fallback',
       generatedAt: finishedAt,
@@ -500,10 +511,15 @@ export function createComponentGenerator(
       // 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
+      // per-shopper mode this stays empty and every reason is screened.
+      const hostReasonSkus = new Set<string>();
       const served =
-        generation === 'cohort' ? fitCohortSpec(answer.spec, input, digest) : answer.spec;
+        generation === 'cohort'
+          ? fitCohortSpec(answer.spec, input, digest, rank, hostReasonSkus)
+          : answer.spec;
 
-      const reconciled = reconcileSpec(served, input, digest);
+      const reconciled = reconcileSpec(served, input, digest, hostReasonSkus);
       if (!reconciled.isUsable) {
         return buildDeterministic(input, digest, startedAt, key, 'unusable-on-serve', {
           calledModel,

package/src/component-spec.ts

@@ -92,7 +92,7 @@ export const productReferenceSchema = z.object({
    * true, but the prose asserting that reason must not render.
    */
   reason: z.string().nullable(),
-  /** Short accent label, e.g. "Back in stock". Null when nothing warrants one. */
+  /** Short accent label, e.g. "Worth a look". Null when nothing warrants one. */
   badge: z.string().nullable(),
   emphasis: z.enum(EMPHASIS),
 });

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

@@ -7,6 +7,7 @@ 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/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

@@ -356,6 +356,7 @@ function reconcileItems(
   candidatesBySku: Map<string, Product>,
   digest: SignalDigest,
   tracker: PlacementTracker,
+  hostReasonSkus: ReadonlySet<string>,
 ): ProductReference[] {
   const kept: ProductReference[] = [];
 
@@ -375,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,
     });
   }
@@ -516,6 +525,7 @@ function reconcileBlock(
   digest: SignalDigest,
   bundles: readonly Bundle[],
   tracker: PlacementTracker,
+  hostReasonSkus: ReadonlySet<string>,
 ): Block | null {
   switch (block.kind) {
     case 'hero': {
@@ -552,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;
@@ -567,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;
@@ -643,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]));
@@ -661,6 +691,7 @@ export function reconcileSpec(
       digest,
       input.bundles,
       tracker,
+      hostReasonSkus,
     );
     if (reconciled !== null) blocks.push(reconciled);
   }

package/src/tracking-input.ts

@@ -44,6 +44,9 @@ export const FIELD_LIMITS = {
   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. */
@@ -95,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))