@rudra-js/core 0.4.0 → 0.6.0

package/src/signal-digest.ts

@@ -1,7 +1,6 @@
 import type {
   Interaction,
   Product,
-  PurchaseSignal,
   SkuSignal,
   TrackingInput,
   ViewSignal,
@@ -78,11 +77,7 @@ export const DIGEST_LIMITS = {
   interactionTypes: 8,
 } as const;
 
-/**
- * How much intent each kind of signal implies. A purchase says more about a
- * shopper than a view; an explicit dislike says the most, and says it in the
- * opposite direction.
- */
+/** How much intent each kind of signal implies. */
 const SIGNAL_WEIGHTS = {
   purchase: 5,
   like: 4,
@@ -107,7 +102,6 @@ function byMostRecent(
   return (right.at ?? 0) - (left.at ?? 0);
 }
 
-/** The most recent `limit` SKUs, each appearing once. */
 function recentUniqueSkus(signals: SkuSignal[], limit: number): string[] {
   const skus: string[] = [];
   const alreadySeen = new Set<string>();
@@ -122,11 +116,6 @@ function recentUniqueSkus(signals: SkuSignal[], limit: number): string[] {
   return skus;
 }
 
-/**
- * A signal may name its own category; otherwise we look the SKU up in the
- * candidate set. A signal for a product that is not a candidate today and
- * carries no category simply contributes nothing.
- */
 function categoryOf(
   signal: { sku: string; category?: string | undefined },
   candidatesBySku: Map<string, Product>,
@@ -173,22 +162,50 @@ function computeCategoryAffinity(
     );
   }
 
-  // The category the shopper is standing in right now is itself evidence.
+  // The category the shopper is standing in right now is itself evidence — for
+  // ranking. It is not evidence that they like it: see `engagedCategories`.
   addScore(input.context.currentCategory, SIGNAL_WEIGHTS.like);
 
-  return [...scoreByCategory.entries()]
-    .map(([category, score]) => ({
-      category,
-      score: Math.round(score * 100) / 100,
-    }))
-    .filter((affinity) => affinity.score > 0)
+  const affinities: CategoryAffinity[] = [];
+  for (const [category, score] of scoreByCategory) {
+    const rounded = Math.round(score * 100) / 100;
+    if (rounded > 0) affinities.push({ category, score: rounded });
+  }
+
+  return affinities
     .toSorted((left, right) => right.score - left.score)
     .slice(0, DIGEST_LIMITS.affinity);
 }
 
+/**
+ * Categories this shopper did something in — bought, liked, carted or viewed.
+ *
+ * Not the same thing as `categoryAffinity`, which also scores the category the
+ * page itself is in. That scoring is right for ranking and wrong as evidence:
+ * a first-time visitor standing on a tent page has a tent affinity and has
+ * never touched a tent, so a sentence claiming they keep coming back to tents
+ * is checked against this instead.
+ */
+export function engagedCategories(input: TrackingInput): Set<string> {
+  const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
+  const { signals } = input;
+  const categories = new Set<string>();
+
+  for (const signal of [
+    ...signals.lastPurchased,
+    ...signals.likes,
+    ...signals.cart,
+    ...signals.mostViewed,
+  ]) {
+    const category = categoryOf(signal, candidatesBySku);
+    if (category) categories.add(category);
+  }
+
+  return categories;
+}
+
 interface MergedView extends ViewedProduct {
   category?: string;
-  /** Always resolved, so no consumer has to re-apply the default. */
   weight: number;
 }
 
@@ -201,8 +218,6 @@ interface MergedView extends ViewedProduct {
  * over, defeating the sub-linear scaling in `computeCategoryAffinity` entirely.
  * Merging first makes the score depend on how much someone looked, not on how
  * their tracking pipeline happens to batch.
- *
- * Where records disagree on `weight`, the strongest wins.
  */
 function mergeViewsBySku(views: ViewSignal[]): MergedView[] {
   const totalsBySku = new Map<string, MergedView>();
@@ -228,7 +243,6 @@ function mergeViewsBySku(views: ViewSignal[]): MergedView[] {
   return [...totalsBySku.values()];
 }
 
-/** The most-viewed few, as the digest reports them. */
 function mostViewedProducts(views: ViewSignal[]): ViewedProduct[] {
   const top = mergeViewsBySku(views)
     .toSorted((left, right) => right.views - left.views)
@@ -243,7 +257,6 @@ function mostViewedProducts(views: ViewSignal[]): ViewedProduct[] {
   return products;
 }
 
-/** The open-vocabulary long tail, reduced to "which kinds, and how often". */
 function countByInteractionType(interactions: Interaction[]): InteractionCount[] {
   const countByType = new Map<string, number>();
 
@@ -251,23 +264,20 @@ function countByInteractionType(interactions: Interaction[]): InteractionCount[]
     countByType.set(interaction.type, (countByType.get(interaction.type) ?? 0) + 1);
   }
 
-  return [...countByType.entries()]
-    .map(([type, count]) => ({ type, count }))
+  const counts = [...countByType.entries()].map(([type, count]) => ({ type, count }));
+
+  return counts
     .toSorted((left, right) => right.count - left.count)
     .slice(0, DIGEST_LIMITS.interactionTypes);
 }
 
-function recentPurchasedSkus(purchases: PurchaseSignal[]): string[] {
-  return recentUniqueSkus(purchases, DIGEST_LIMITS.purchased);
-}
-
 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);
   const dislikedSkus = recentUniqueSkus(signals.dislikes, DIGEST_LIMITS.disliked);
-  const purchasedSkus = recentPurchasedSkus(signals.lastPurchased);
+  const purchasedSkus = recentUniqueSkus(signals.lastPurchased, DIGEST_LIMITS.purchased);
   const cartSkus = recentUniqueSkus(signals.cart, DIGEST_LIMITS.cart);
   const topViewed = mostViewedProducts(signals.mostViewed);
 

package/src/spec-cache.ts

@@ -75,12 +75,8 @@ export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): Spe
   const ttlMs = options.ttlMs ?? 60_000;
   const maxEntries = options.maxEntries ?? 10_000;
 
-  // Checked rather than trusted, because the way these are usually supplied is
-  // `Number(process.env.SOMETHING)`, and an unset or misspelled variable makes
-  // that NaN. Every comparison against NaN is false, so the cache would then
-  // never expire an entry and never evict one — it would grow forever while
-  // serving a shopper the component they were given last week, and nothing
-  // would report it. Failing at construction is the only loud option.
+  // Usually `Number(process.env.X)`: an unset variable makes these NaN, and every
+  // comparison against NaN is false, so nothing would ever expire or be evicted.
   assertFiniteAtLeastZero('ttlMs', ttlMs);
   assertFiniteAtLeastZero('maxEntries', maxEntries);
   if (!Number.isSafeInteger(maxEntries)) {
@@ -100,8 +96,8 @@ export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): Spe
         return undefined;
       }
 
-      // Re-insert so insertion order tracks recency of use, which is what makes
-      // the eviction below least-recently-used rather than oldest-written.
+      // Re-insert so insertion order tracks recency, which makes the eviction below
+      // least-recently-used rather than oldest-written.
       entries.delete(key);
       entries.set(key, entry);
       return entry.cached;
@@ -156,6 +152,19 @@ function canonicalise(value: unknown): string {
 
 const PROMPT_FINGERPRINT = createHash('sha256').update(SYSTEM_PROMPT).digest('hex').slice(0, 16);
 
+/**
+ * Who answered, as two named fields rather than one joined string.
+ *
+ * Joining them with a colon is ambiguous, and model ids carry colons — an
+ * `anthropic` / `claude:1` pair and an `anthropic:claude` / `1` pair flatten to
+ * the same text and read each other's entries out of a shared store. The
+ * provider is in the key precisely so that cannot happen.
+ */
+export interface ProviderIdentity {
+  name: string;
+  model: string;
+}
+
 /**
  * Derives the cache key.
  *
@@ -184,14 +193,14 @@ const PROMPT_FINGERPRINT = createHash('sha256').update(SYSTEM_PROMPT).digest('he
 export function specCacheKey(
   digest: SignalDigest,
   candidateSkus: readonly string[],
-  providerId: string,
+  provider: ProviderIdentity,
 ): string {
   const material = canonicalise({
-    // 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.
+    // 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,
+    provider,
     digest,
     candidates: candidateSkus.toSorted(),
   });
@@ -199,33 +208,27 @@ export function specCacheKey(
   return createHash('sha256').update(material).digest('hex').slice(0, 32);
 }
 
-// Leaves out the fields that make a key personal: who the shopper is, what they
-// liked, viewed or searched for. Candidates go too, because every shopper's list
-// is different — that is safe because the SKUs in a cohort spec get replaced
-// before the page is served.
+// Leaves out the personal fields: who the shopper is, what they liked, viewed or searched.
 export function cohortCacheKey(
   digest: SignalDigest,
   candidateSkus: readonly string[],
-  providerId: string,
+  provider: ProviderIdentity,
 ): string {
   const material = canonicalise({
     specVersion: SPEC_VERSION,
     prompt: PROMPT_FINGERPRINT,
-    provider: providerId,
+    provider,
     segment: digest.segment ?? null,
     surface: digest.surface,
     slot: digest.slot,
     locale: digest.locale,
     maxItems: digest.maxItems,
     isColdStart: digest.isColdStart,
-    // The page being looked at, so copy written for a backpack page is not
-    // served on a tent page.
+    // So copy written for a backpack page is not served on a tent page.
     currentCategory: digest.currentCategory ?? null,
     topCategory: digest.categoryAffinity[0]?.category ?? null,
-    // The model is shown these, so they belong in the key. Normally they come
-    // from the page and everyone on it shares them. A shop that picks
-    // candidates per shopper gets smaller cohorts, which is the honest result:
-    // its prompt really is personal.
+    // The model is shown products drawn from this list, so a different list must not reuse the
+    // copy. A shop that picks candidates per shopper gets smaller cohorts, not a wrong answer.
     candidates: candidateSkus.toSorted(),
   });
 

package/src/tracking-input.ts

@@ -52,7 +52,6 @@ export const FIELD_LIMITS = {
 /** Assigning this as an object key mutates the prototype instead of the object. */
 const RESERVED_META_KEY = '__proto__';
 
-/** Upper bound on any timestamp: 2100-01-01. */
 const MAX_EPOCH_MS = Date.UTC(2100, 0, 1);
 
 const identifier = () => z.string().min(1).max(FIELD_LIMITS.identifier);
@@ -65,6 +64,20 @@ const optionalIdentifier = () => z.string().min(1).max(FIELD_LIMITS.identifier).
  */
 const epochMs = () => z.number().int().min(0).max(MAX_EPOCH_MS).optional();
 
+/**
+ * Whether a path stays on the page's own origin.
+ *
+ * Read the way a browser reads it, not the way it looks. A browser drops tab,
+ * carriage return and newline from a URL before parsing it, and treats a
+ * backslash as a slash, so `/\evil.example/x.png` and `/<tab>//evil.example/x.png`
+ * both point at someone else's host while passing a plain "starts with one
+ * slash" test.
+ */
+const isRootRelative = (value: string) => {
+  const asParsed = value.replace(/[\t\n\r]/g, '');
+  return value.startsWith('/') && /^\/(?![/\\])/.test(asParsed);
+};
+
 /**
  * An absolute http(s) URL, or a root-relative path such as `/images/tr-102.png`.
  * Anything else — a bare word, a `javascript:` URI, a protocol-relative `//host`
@@ -76,9 +89,7 @@ const imageReference = () =>
     .max(FIELD_LIMITS.shortText)
     .refine(
       (value) =>
-        value.startsWith('/') && !value.startsWith('//')
-          ? true
-          : z.url({ protocol: /^https?$/ }).safeParse(value).success,
+        isRootRelative(value) ? true : z.url({ protocol: /^https?$/ }).safeParse(value).success,
       { message: 'expected an http(s) URL or a root-relative path' },
     );
 
@@ -138,12 +149,6 @@ export type PurchaseSignal = z.infer<typeof purchaseSignalSchema>;
  * each key, and assigning `__proto__` sets the prototype instead of adding a
  * key — so the entry would vanish from the parsed output with no error, which
  * is the silent drop this module exists to prevent.
- *
- * `__proto__` is the only key that behaves this way. `constructor` and
- * `prototype` are ordinary own properties: assigning either shadows it on that
- * one object and leaves the prototype alone, so both survive a parse intact and
- * are accepted. `meta` is a host-defined vocabulary, and a shop with a facet,
- * filter, or CMS field by either name should get a component, not a throw.
  */
 const metaKeysAreSafe = z.custom<Record<string, string | number | boolean>>(
   (value) =>
@@ -244,9 +249,7 @@ export const trackingInputSchema = z
       isReturning: z.boolean().optional(),
     }),
     context: renderContextSchema,
-    // A payload with no `signals` block at all is the cold-start case, not an
-    // error. Every category defaults to empty, so a first-time visitor needs no
-    // special handling from the host.
+    // A payload with no `signals` block at all is the cold-start case, not an error.
     signals: trackingSignalsSchema.prefault({}),
     /**
      * The only products the generated component may place. Merchandising rules