@rudra-js/core 0.7.4 → 0.7.6

package/src/signal-digest.ts

@@ -8,7 +8,6 @@ import type {
 
 export interface CategoryAffinity {
   category: string;
-
   score: number;
 }
 
@@ -62,27 +61,29 @@ export const DIGEST_LIMITS = {
 const SIGNAL_WEIGHTS = {
   purchase: 5,
   like: 4,
+  browsing: 4,
   cart: 3,
   view: 1,
   dislike: -6,
 } as const;
 
-const effectiveWeight = (signal: { weight?: number | undefined }): number => signal.weight ?? 1;
+interface MergedView extends ViewedProduct {
+  category?: string;
+  weight: number;
+}
 
-function byMostRecent(
-  left: { at?: number | undefined },
-  right: { at?: number | undefined },
-): number {
-  return (right.at ?? 0) - (left.at ?? 0);
+function weightOf(signal: SkuSignal): number {
+  return signal.weight ?? 1;
 }
 
 function recentUniqueSkus(signals: SkuSignal[], limit: number): string[] {
+  const newestFirst = signals.toSorted((left, right) => (right.at ?? 0) - (left.at ?? 0));
   const skus: string[] = [];
-  const alreadySeen = new Set<string>();
+  const seen = new Set<string>();
 
-  for (const signal of signals.toSorted(byMostRecent)) {
-    if (alreadySeen.has(signal.sku)) continue;
-    alreadySeen.add(signal.sku);
+  for (const signal of newestFirst) {
+    if (seen.has(signal.sku)) continue;
+    seen.add(signal.sku);
     skus.push(signal.sku);
     if (skus.length >= limit) break;
   }
@@ -90,54 +91,34 @@ function recentUniqueSkus(signals: SkuSignal[], limit: number): string[] {
   return skus;
 }
 
-function categoryOf(
-  signal: { sku: string; category?: string | undefined },
-  candidatesBySku: Map<string, Product>,
-): string | undefined {
+function categoryOf(signal: SkuSignal, candidatesBySku: Map<string, Product>): string | undefined {
   return signal.category ?? candidatesBySku.get(signal.sku)?.category;
 }
 
-function computeCategoryAffinity(
-  input: TrackingInput,
-  candidatesBySku: Map<string, Product>,
-): CategoryAffinity[] {
-  const scoreByCategory = new Map<string, number>();
+function scoreCategories(input: TrackingInput): CategoryAffinity[] {
+  const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
+  const scores = new Map<string, number>();
 
-  const addScore = (category: string | undefined, score: number): void => {
+  const add = (category: string | undefined, score: number): void => {
     if (!category) return;
-    scoreByCategory.set(category, (scoreByCategory.get(category) ?? 0) + score);
+    scores.set(category, (scores.get(category) ?? 0) + score);
+  };
+  const addSignal = (signal: SkuSignal, base: number): void => {
+    add(categoryOf(signal, candidatesBySku), base * weightOf(signal));
   };
 
   const { signals } = input;
-
-  for (const purchase of signals.lastPurchased) {
-    addScore(
-      categoryOf(purchase, candidatesBySku),
-      SIGNAL_WEIGHTS.purchase * effectiveWeight(purchase),
-    );
-  }
-  for (const like of signals.likes) {
-    addScore(categoryOf(like, candidatesBySku), SIGNAL_WEIGHTS.like * effectiveWeight(like));
-  }
-  for (const inCart of signals.cart) {
-    addScore(categoryOf(inCart, candidatesBySku), SIGNAL_WEIGHTS.cart * effectiveWeight(inCart));
-  }
-
+  for (const purchase of signals.lastPurchased) addSignal(purchase, SIGNAL_WEIGHTS.purchase);
+  for (const like of signals.likes) addSignal(like, SIGNAL_WEIGHTS.like);
+  for (const inCart of signals.cart) addSignal(inCart, SIGNAL_WEIGHTS.cart);
   for (const view of mergeViewsBySku(signals.mostViewed)) {
-    const scaledViews = Math.log2(1 + view.views);
-    addScore(categoryOf(view, candidatesBySku), SIGNAL_WEIGHTS.view * scaledViews * view.weight);
+    addSignal(view, SIGNAL_WEIGHTS.view * Math.log2(1 + view.views));
   }
-  for (const dislike of signals.dislikes) {
-    addScore(
-      categoryOf(dislike, candidatesBySku),
-      SIGNAL_WEIGHTS.dislike * effectiveWeight(dislike),
-    );
-  }
-
-  addScore(input.context.currentCategory, SIGNAL_WEIGHTS.like);
+  for (const dislike of signals.dislikes) addSignal(dislike, SIGNAL_WEIGHTS.dislike);
+  add(input.context.currentCategory, SIGNAL_WEIGHTS.browsing);
 
   const affinities: CategoryAffinity[] = [];
-  for (const [category, score] of scoreByCategory) {
+  for (const [category, score] of scores) {
     const rounded = Math.round(score * 100) / 100;
     if (rounded > 0) affinities.push({ category, score: rounded });
   }
@@ -147,7 +128,7 @@ function computeCategoryAffinity(
     .slice(0, DIGEST_LIMITS.affinity);
 }
 
-export function engagedCategories(input: TrackingInput): Set<string> {
+export function categoriesTouchedBySignals(input: TrackingInput): Set<string> {
   const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
   const { signals } = input;
   const categories = new Set<string>();
@@ -165,53 +146,44 @@ export function engagedCategories(input: TrackingInput): Set<string> {
   return categories;
 }
 
-interface MergedView extends ViewedProduct {
-  category?: string;
-  weight: number;
-}
-
 function mergeViewsBySku(views: ViewSignal[]): MergedView[] {
-  const totalsBySku = new Map<string, MergedView>();
+  const totals = new Map<string, MergedView>();
 
   for (const view of views) {
-    const running = totalsBySku.get(view.sku);
-    if (running) {
-      running.views += view.views;
-      if (view.dwellMs !== undefined) running.dwellMs = (running.dwellMs ?? 0) + view.dwellMs;
-      if (view.category !== undefined) running.category ??= view.category;
-      running.weight = Math.max(running.weight, effectiveWeight(view));
+    const total = totals.get(view.sku);
+    if (!total) {
+      const first: MergedView = { sku: view.sku, views: view.views, weight: weightOf(view) };
+      if (view.dwellMs !== undefined) first.dwellMs = view.dwellMs;
+      if (view.category !== undefined) first.category = view.category;
+      totals.set(view.sku, first);
       continue;
     }
-    totalsBySku.set(view.sku, {
-      sku: view.sku,
-      views: view.views,
-      ...(view.dwellMs !== undefined ? { dwellMs: view.dwellMs } : {}),
-      ...(view.category !== undefined ? { category: view.category } : {}),
-      weight: effectiveWeight(view),
-    });
+
+    total.views += view.views;
+    if (view.dwellMs !== undefined) total.dwellMs = (total.dwellMs ?? 0) + view.dwellMs;
+    if (view.category !== undefined) total.category ??= view.category;
+    total.weight = Math.max(total.weight, weightOf(view));
   }
 
-  return [...totalsBySku.values()];
+  return [...totals.values()];
 }
 
-function mostViewedProducts(views: ViewSignal[]): ViewedProduct[] {
-  const top = mergeViewsBySku(views)
+function mostViewedProducts(viewSignals: ViewSignal[]): ViewedProduct[] {
+  const top = mergeViewsBySku(viewSignals)
     .toSorted((left, right) => right.views - left.views)
     .slice(0, DIGEST_LIMITS.viewed);
 
-  return top.map(({ sku, views: count, dwellMs }) =>
-    dwellMs === undefined ? { sku, views: count } : { sku, views: count, dwellMs },
+  return top.map(({ sku, views, dwellMs }) =>
+    dwellMs === undefined ? { sku, views } : { sku, views, dwellMs },
   );
 }
 
 function countByInteractionType(interactions: Interaction[]): InteractionCount[] {
   const countByType = new Map<string, number>();
+  for (const { type } of interactions) countByType.set(type, (countByType.get(type) ?? 0) + 1);
 
-  for (const interaction of interactions) {
-    countByType.set(interaction.type, (countByType.get(interaction.type) ?? 0) + 1);
-  }
-
-  const counts = [...countByType.entries()].map(([type, count]) => ({ type, count }));
+  const counts: InteractionCount[] = [];
+  for (const [type, count] of countByType) counts.push({ type, count });
 
   return counts
     .toSorted((left, right) => right.count - left.count)
@@ -219,7 +191,6 @@ function countByInteractionType(interactions: Interaction[]): InteractionCount[]
 }
 
 export function buildDigest(input: TrackingInput): SignalDigest {
-  const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
   const { signals, context, user } = input;
 
   const likedSkus = recentUniqueSkus(signals.likes, DIGEST_LIMITS.liked);
@@ -254,7 +225,7 @@ export function buildDigest(input: TrackingInput): SignalDigest {
     cartSkus,
     topViewed,
     recentSearches: signals.recentSearches.slice(0, DIGEST_LIMITS.searches),
-    categoryAffinity: computeCategoryAffinity(input, candidatesBySku),
+    categoryAffinity: scoreCategories(input),
     interactionCounts: countByInteractionType(signals.interactions),
 
     isColdStart: evidenceCount === 0,

package/src/spec-cache.ts

@@ -5,7 +5,6 @@ import type { SignalDigest } from './signal-digest.js';
 
 export interface CachedSpec {
   spec: GeneratedSpec;
-
   generatedAt: number;
 }
 
@@ -17,9 +16,7 @@ export interface SpecCache {
 
 export interface MemorySpecCacheOptions {
   ttlMs?: number;
-
   maxEntries?: number;
-
   now?: () => number;
 }
 
@@ -55,12 +52,9 @@ export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): Spe
       const entry = entries.get(key);
       if (!entry) return undefined;
 
-      if (entry.expiresAt <= now()) {
-        entries.delete(key);
-        return undefined;
-      }
-
+      const isExpired = entry.expiresAt <= now();
       entries.delete(key);
+      if (isExpired) return undefined;
       entries.set(key, entry);
       return entry.cached;
     },
@@ -69,10 +63,9 @@ export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): Spe
       entries.delete(key);
       entries.set(key, { cached, expiresAt: now() + ttlMs });
 
-      while (entries.size > maxEntries) {
-        const oldest = entries.keys().next();
-        if (oldest.done) break;
-        entries.delete(oldest.value);
+      for (const oldest of entries.keys()) {
+        if (entries.size <= maxEntries) break;
+        entries.delete(oldest);
       }
     },
 
@@ -83,23 +76,22 @@ export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): Spe
 }
 
 export function createNullSpecCache(): SpecCache {
-  return {
-    async get() {
-      return undefined;
-    },
-    async set() {},
-  };
+  return { get: async () => undefined, set: async () => {} };
 }
 
 function canonicalise(value: unknown): string {
   if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
   if (Array.isArray(value)) return `[${value.map(canonicalise).join(',')}]`;
 
-  const entries = Object.entries(value as Record<string, unknown>)
-    .filter(([, fieldValue]) => fieldValue !== undefined)
-    .toSorted(([left], [right]) => (left < right ? -1 : 1));
-
-  return `{${entries.map(([name, fieldValue]) => `${JSON.stringify(name)}:${canonicalise(fieldValue)}`).join(',')}}`;
+  const sorted = Object.entries(value as Record<string, unknown>).toSorted(([left], [right]) =>
+    left < right ? -1 : 1,
+  );
+  const fields: string[] = [];
+  for (const [name, fieldValue] of sorted) {
+    if (fieldValue === undefined) continue;
+    fields.push(`${JSON.stringify(name)}:${canonicalise(fieldValue)}`);
+  }
+  return `{${fields.join(',')}}`;
 }
 
 const PROMPT_FINGERPRINT = createHash('sha256').update(SYSTEM_PROMPT).digest('hex').slice(0, 16);
@@ -119,28 +111,3 @@ export function specCacheKey(
 
   return createHash('sha256').update(material).digest('hex').slice(0, 32);
 }
-
-export function cohortCacheKey(
-  digest: SignalDigest,
-  candidateSkus: readonly string[],
-  provider: { name: string; model: string },
-): string {
-  const material = canonicalise({
-    specVersion: SPEC_VERSION,
-    prompt: PROMPT_FINGERPRINT,
-    provider,
-    segment: digest.segment ?? null,
-    surface: digest.surface,
-    slot: digest.slot,
-    locale: digest.locale,
-    maxItems: digest.maxItems,
-    isColdStart: digest.isColdStart,
-
-    currentCategory: digest.currentCategory ?? null,
-    topCategory: digest.categoryAffinity[0]?.category ?? null,
-
-    candidates: candidateSkus.toSorted(),
-  });
-
-  return createHash('sha256').update(material).digest('hex').slice(0, 32);
-}

package/src/tracking-input.ts

@@ -13,7 +13,6 @@ export const FIELD_LIMITS = {
   bundles: 20,
   localeTag: 35,
   maxItems: 12,
-
   reason: 120,
 } as const;
 
@@ -22,13 +21,21 @@ const RESERVED_META_KEY = '__proto__';
 const MAX_EPOCH_MS = Date.UTC(2100, 0, 1);
 
 const identifier = () => z.string().min(1).max(FIELD_LIMITS.identifier);
-const optionalIdentifier = () => z.string().min(1).max(FIELD_LIMITS.identifier).optional();
+const optionalIdentifier = () => identifier().optional();
+
+const currencyCode = () =>
+  z
+    .string()
+    .regex(/^[A-Z]{3}$/, 'expected a three-letter ISO 4217 code')
+    .default('USD');
+
+const isUnique = (values: string[]) => new Set(values).size === values.length;
 
 const epochMs = () => z.number().int().min(0).max(MAX_EPOCH_MS).optional();
 
 const isRootRelative = (value: string) => {
-  const asParsed = value.replace(/[\t\n\r]/g, '');
-  return value.startsWith('/') && /^\/(?![/\\])/.test(asParsed);
+  const asBrowserReadsIt = value.replace(/[\t\n\r]/g, '');
+  return value.startsWith('/') && /^\/(?![/\\])/.test(asBrowserReadsIt);
 };
 
 const imageReference = () =>
@@ -36,8 +43,7 @@ const imageReference = () =>
     .string()
     .max(FIELD_LIMITS.shortText)
     .refine(
-      (value) =>
-        isRootRelative(value) ? true : z.url({ protocol: /^https?$/ }).safeParse(value).success,
+      (value) => isRootRelative(value) || z.url({ protocol: /^https?$/ }).safeParse(value).success,
       { message: 'expected an http(s) URL or a root-relative path' },
     );
 
@@ -46,14 +52,9 @@ export const productSchema = z.strictObject({
   title: z.string().min(1).max(FIELD_LIMITS.shortText),
   category: identifier(),
   price: z.number().nonnegative(),
-  currency: z
-    .string()
-    .regex(/^[A-Z]{3}$/, 'expected a three-letter ISO 4217 code')
-    .default('USD'),
-
+  currency: currencyCode(),
   imageUrl: imageReference().optional(),
   rating: z.number().min(0).max(5).optional(),
-
   reason: z.string().min(1).max(FIELD_LIMITS.reason).optional(),
   isInStock: z.boolean().default(true),
   tags: z
@@ -67,7 +68,6 @@ export const skuSignalSchema = z.strictObject({
   sku: identifier(),
   category: optionalIdentifier(),
   at: epochMs(),
-
   weight: z.number().min(0).max(1).optional(),
 });
 export type SkuSignal = z.infer<typeof skuSignalSchema>;
@@ -93,7 +93,7 @@ const metaKeysAreSafe = z.custom<Record<string, string | number | boolean>>(
 const metaSchema = metaKeysAreSafe.pipe(
   z
     .record(
-      z.string().min(1).max(FIELD_LIMITS.identifier),
+      identifier(),
       z.union([z.string().max(FIELD_LIMITS.shortText), z.number(), z.boolean()]),
     )
     .refine((entries) => Object.keys(entries).length <= FIELD_LIMITS.metaEntries, {
@@ -113,18 +113,15 @@ export type Interaction = z.infer<typeof interactionSchema>;
 
 export const renderContextSchema = z.strictObject({
   surface: identifier(),
-
-  slot: z.string().min(1).max(FIELD_LIMITS.identifier).default('recommendations'),
+  slot: identifier().default('recommendations'),
   currentSku: optionalIdentifier(),
   currentCategory: optionalIdentifier(),
   searchQuery: z.string().max(FIELD_LIMITS.searchQuery).optional(),
-
   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'),
-
   maxItems: z.number().int().min(1).max(FIELD_LIMITS.maxItems).default(4),
 });
 export type RenderContext = z.infer<typeof renderContextSchema>;
@@ -149,15 +146,9 @@ export const bundleSchema = z.strictObject({
     .array(identifier())
     .min(2)
     .max(FIELD_LIMITS.productsPerBundle)
-    .refine((skus) => new Set(skus).size === skus.length, {
-      message: 'a bundle must not list the same product twice',
-    }),
-
+    .refine(isUnique, { message: 'a bundle must not list the same product twice' }),
   price: z.number().nonnegative(),
-  currency: z
-    .string()
-    .regex(/^[A-Z]{3}$/, 'expected a three-letter ISO 4217 code')
-    .default('USD'),
+  currency: currencyCode(),
   label: z.string().min(1).max(FIELD_LIMITS.shortText).optional(),
 });
 export type Bundle = z.infer<typeof bundleSchema>;
@@ -171,24 +162,18 @@ export const trackingInputSchema = z
       isReturning: z.boolean().optional(),
     }),
     context: renderContextSchema,
-
     signals: trackingSignalsSchema.prefault({}),
-
     candidates: z
       .array(productSchema)
       .min(1)
       .max(FIELD_LIMITS.candidates)
-      .refine(
-        (products) => new Set(products.map((product) => product.sku)).size === products.length,
-        {
-          message: 'candidates must have unique SKUs',
-        },
-      ),
-
+      .refine((products) => isUnique(products.map((product) => product.sku)), {
+        message: 'candidates must have unique SKUs',
+      }),
     bundles: z
       .array(bundleSchema)
       .max(FIELD_LIMITS.bundles)
-      .refine((bundles) => new Set(bundles.map((bundle) => bundle.id)).size === bundles.length, {
+      .refine((bundles) => isUnique(bundles.map((bundle) => bundle.id)), {
         message: 'bundles must have unique ids',
       })
       .default([]),