@rudra-js/core 0.4.0 → 0.6.0

package/src/fit-to-shopper.ts

@@ -1,18 +1,23 @@
 import type { Block, GeneratedSpec, ProductReference } from './component-spec.js';
 import type { ProductPick } from './product-selection.js';
 
+export interface FittedSpec {
+  spec: GeneratedSpec;
+  ourReasons: Map<string, string>;
+}
+
 // 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 {
+): FittedSpec {
   // Picks are ordered best first. Every slot takes the next one.
   let next = 0;
   const limit = Math.min(picks.length, maxItems);
 
+  const ourReasons = new Map<string, string>();
   const blocks: Block[] = [];
   for (const block of spec.blocks) {
     // A hero is left alone. Its headline and body were written about the
@@ -25,7 +30,9 @@ 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);
+        // Every reason here is written by this library or handed to it by the
+        // shop. None of them is the model's, whatever the model wrote in this slot.
+        ourReasons.set(chosen.product.sku, chosen.reason);
         items.push({
           sku: chosen.product.sku,
           basis: chosen.basis,
@@ -43,5 +50,5 @@ export function fitToShopper(
     blocks.push(block);
   }
 
-  return { ...spec, blocks };
+  return { spec: { ...spec, blocks }, ourReasons };
 }

package/src/index.ts

@@ -61,6 +61,7 @@ export {
   type ComponentSpec,
   type CopyBlock,
   type GeneratedSpec,
+  type GeneratedSpecResult,
   type GridBlock,
   type HeroBlock,
   type ProductReference,

package/src/model-prompt.ts

@@ -1,6 +1,6 @@
 import { BANNER_TONES, EMPHASIS, RECOMMENDATION_BASES, TONES } from './component-spec.js';
 import type { SignalDigest } from './signal-digest.js';
-import type { Product, TrackingInput } from './tracking-input.js';
+import { FIELD_LIMITS, type Product, type TrackingInput } from './tracking-input.js';
 
 /**
  * What actually reaches the model.
@@ -140,34 +140,57 @@ on.`;
  * text exactly the same way, and it missed U+0085, U+061C and U+00AD as well.
  * Properties cover the ones nobody has thought of yet.
  *
- *  - Cc, control. Includes U+0085, a mandatory line break that is not U+000A.
- *  - Cf, format. Zero-width characters, the bidirectional overrides and
- *    isolates, and the tag block, which mirrors all of ASCII invisibly.
- *  - Zl and Zp, the line and paragraph separators.
- *  - Cn and Co, unassigned and private use — undefined rendering by definition.
- *  - The variation selectors supplement, which is assigned and therefore not
- *    caught by Cn, and is invisible.
+ * The general categories alone do not, though. Half of what renders as nothing
+ * is a mark or a letter rather than a format character \u2014 the Mongolian free
+ * variation selectors, U+034F, the Hangul fillers, and the sixteen variation
+ * selectors at U+FE00 \u2014 so `Default_Ignorable_Code_Point` is in the class too.
+ * It is the property that means "takes up no room", which is the thing that
+ * makes a character able to carry text nobody sees.
  *
- * The zero-width joiner is the one exception. It is a format character, but it
- * is also how a family emoji is spelled, so escaping it mangles ordinary
- * product titles. Emoji presentation selectors (U+FE00-U+FE0F) are excluded for
- * the same reason.
+ * Three are left out. The zero-width joiner is a format character, but it is
+ * also how a family emoji is spelled, and U+FE0E and U+FE0F are what make a
+ * character render as an emoji rather than as text. Escaping those mangles
+ * ordinary product titles. The other thirteen selectors at U+FE00 spell
+ * nothing and are escaped like the rest.
  */
-const UNPRINTABLE = /(?!\u200D)[\p{Cc}\p{Cf}\p{Cn}\p{Co}\p{Zl}\p{Zp}\u{E0100}-\u{E01EF}]/gu;
+const UNPRINTABLE =
+  /(?!\u{200D}|\u{FE0E}|\u{FE0F})[\p{Cc}\p{Cf}\p{Cn}\p{Co}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}]/gu;
 
 /**
- * Host-supplied text, written so it cannot introduce structure of its own.
+ * How long one quoted value may be once escaped.
  *
- * Quoting handles the obvious half. Escaping the characters above handles the
- * half that looks identical to a reader: after this, a value occupies exactly
- * one line, reads in one direction, and contains nothing a log cannot show.
+ * The contract caps the string a host may send, and this caps what that string
+ * turns into. They are not the same number: an escape writes up to eight
+ * characters for one, so a field on its cap can still buy eight times the
+ * prompt \u2014 and the bill \u2014 that the cap implies. Ordinary text escapes nothing
+ * and never comes near this.
  */
-const quote = (value: string) =>
-  JSON.stringify(value).replace(UNPRINTABLE, (character) => {
+const MAX_QUOTED = FIELD_LIMITS.shortText * 2;
+
+const escapeUnprintable = (text: string) =>
+  text.replace(UNPRINTABLE, (character) => {
     const codePoint = character.codePointAt(0)!;
     return `\\u{${codePoint.toString(16).toUpperCase()}}`;
   });
 
+/** Host-supplied text, written so it cannot introduce structure of its own. */
+const quote = (value: string) => {
+  const escaped = escapeUnprintable(JSON.stringify(value));
+  if (escaped.length <= MAX_QUOTED) return escaped;
+
+  // Cut whole characters, so the result cannot end inside an escape sequence.
+  let length = 2;
+  let kept = '';
+  for (const character of value) {
+    const cost = escapeUnprintable(JSON.stringify(character)).length - 2;
+    if (length + cost > MAX_QUOTED) break;
+    length += cost;
+    kept += character;
+  }
+
+  return escapeUnprintable(JSON.stringify(kept));
+};
+
 function section(heading: string, body: string | undefined): string | null {
   if (!body || body.length === 0) return null;
   return `${heading}: ${body}`;
@@ -207,7 +230,6 @@ function describeShopper(digest: SignalDigest): string {
   return lines.filter((line): line is string => line !== null).join('\n');
 }
 
-/** One candidate per line. Facts the model must not restate are left out. */
 function describeCandidate(product: Product): string {
   const parts = [quote(product.sku), quote(product.title), quote(product.category)];
   if (product.rating !== undefined) parts.push(`rated ${product.rating}`);
@@ -227,10 +249,23 @@ function describeCandidate(product: Product): string {
  */
 const MAX_CANDIDATES = 60;
 
+/**
+ * The candidates the model is actually shown.
+ *
+ * An out-of-stock product is dropped during reconciliation whatever the model
+ * does with it, so offering one only costs the shopper a slot.
+ *
+ * Exported because reconciliation checks the numerals the model writes against
+ * the strings on this list, and a candidate it was never shown cannot be where
+ * one came from. Two copies of "what the model saw" would drift, and the pair
+ * that drifted would be the prompt and the screen reading it back.
+ */
+export function offeredCandidates(input: TrackingInput): Product[] {
+  return input.candidates.filter((product) => product.isInStock).slice(0, MAX_CANDIDATES);
+}
+
 export function buildPrompt(input: TrackingInput, digest: SignalDigest): PromptPair {
-  // An out-of-stock product is dropped during reconciliation whatever the model
-  // does with it, so offering one only costs the shopper a slot.
-  const offered = input.candidates.filter((product) => product.isInStock).slice(0, MAX_CANDIDATES);
+  const offered = offeredCandidates(input);
 
   // The markers are OWASP's labelled-block recommendation. They are safe as
   // boundaries because every value between them is quoted and stripped of

package/src/product-selection.ts

@@ -21,10 +21,8 @@ export interface ProductPick {
   product: Product;
   /** Why this product, stated so reconciliation can check it. */
   basis: RecommendationBasis;
-  /** How the basis reads to a shopper. */
+  /** How the basis reads to a shopper. The host's own sentence when it wrote one. */
   reason: string;
-  /** True when `reason` is the host's own sentence from the candidate. */
-  reasonFromHost: boolean;
   /** Unnormalised. Only the ordering is meaningful. */
   score: number;
 }
@@ -44,10 +42,8 @@ const SCORE_WEIGHTS = {
 /** Beyond this many shared tags, more overlap says nothing new. */
 const MAX_TAG_OVERLAP = 3;
 
-/** Assumed rating for a product the catalog does not rate. */
 const UNRATED = 3.5;
 
-/** Tags on the products this shopper has actually engaged with. */
 function engagedTags(input: TrackingInput, digest: SignalDigest): Set<string> {
   const engagedSkus = new Set([
     ...digest.likedSkus,
@@ -100,12 +96,6 @@ function basisFor(
   return { basis: 'popular', reason: `Popular in ${product.category}` };
 }
 
-/**
- * Scores every eligible candidate and returns them best first.
- *
- * 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.
- */
 /** How the picks are ordered once the unplaceable ones are gone. */
 export type RankOrder = 'signals' | 'given';
 
@@ -131,7 +121,7 @@ export function selectProducts(
   // same thing whether a shopper has two signals or two hundred.
   const strongestAffinity = Math.max(1, ...affinityByCategory.values());
   const tags = engagedTags(input, digest);
-  const excluded = neverRecommend(digest);
+  const excluded = neverRecommend(input);
   const viewsBySku = new Map(digest.topViewed.map((viewed) => [viewed.sku, viewed.views]));
 
   const picks: ProductPick[] = [];
@@ -164,7 +154,6 @@ export function selectProducts(
       product,
       basis,
       reason: product.reason ?? reason,
-      reasonFromHost: product.reason !== undefined,
       score,
     });
   }

package/src/provider.ts

@@ -74,14 +74,7 @@ export interface ComponentProvider {
   generate(request: ProviderRequest): Promise<ProviderResult>;
 }
 
-/**
- * A provider that returns a fixed spec and never touches the network.
- *
- * This is the benchmark's control: it isolates the cost of the framework from
- * the latency of a model, which is the only way to report what server-side
- * rendering itself costs. It is also what the generator's tests run against,
- * since a test that needs an API key is a test nobody runs.
- */
+/** A provider that returns a fixed spec and never touches the network. */
 export function createFixedSpecProvider(spec: GeneratedSpec): ComponentProvider {
   return {
     name: 'fixed',