@rudra-js/core 0.1.0

package/src/signal-digest.ts

@@ -0,0 +1,335 @@
+import type {
+  Interaction,
+  Product,
+  PurchaseSignal,
+  SkuSignal,
+  TrackingInput,
+  ViewSignal,
+} from './tracking-input.js';
+
+/**
+ * Reduces a validated tracking payload to the compact, ordered, bounded view
+ * that everything downstream reads.
+ *
+ * Two jobs:
+ *  1. Keep the volatile part of a prompt small and stable. The contract lets a
+ *     host send 500 signals per category; a prompt cannot afford them, and the
+ *     long tail is noise anyway.
+ *  2. Give the deterministic path the same evidence the model gets, so a
+ *     degraded render is a weaker version of the same decision rather than an
+ *     unrelated one.
+ */
+
+export interface CategoryAffinity {
+  category: string;
+  /** Unnormalised. Only the ordering is meaningful — do not show this to anyone. */
+  score: number;
+}
+
+export interface ViewedProduct {
+  sku: string;
+  views: number;
+  dwellMs?: number;
+}
+
+export interface InteractionCount {
+  type: string;
+  count: number;
+}
+
+export interface SignalDigest {
+  userId: string;
+  segment?: string;
+  isReturning: boolean;
+
+  surface: string;
+  slot: string;
+  locale: string;
+  maxItems: number;
+  currentSku?: string;
+  currentCategory?: string;
+  searchQuery?: string;
+
+  likedSkus: string[];
+  dislikedSkus: string[];
+  purchasedSkus: string[];
+  cartSkus: string[];
+  topViewed: ViewedProduct[];
+  recentSearches: string[];
+  categoryAffinity: CategoryAffinity[];
+  interactionCounts: InteractionCount[];
+
+  /** True when there is no behavioural evidence to personalise on. */
+  isColdStart: boolean;
+}
+
+/**
+ * How much of each signal category survives into the digest. Chosen to keep the
+ * per-shopper part of a prompt in the low hundreds of tokens.
+ */
+export const DIGEST_LIMITS = {
+  liked: 12,
+  disliked: 12,
+  purchased: 8,
+  cart: 8,
+  viewed: 10,
+  searches: 5,
+  affinity: 6,
+  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.
+ */
+const SIGNAL_WEIGHTS = {
+  purchase: 5,
+  like: 4,
+  cart: 3,
+  view: 1,
+  dislike: -6,
+} as const;
+
+/**
+ * A signal that does not state a weight counts at full strength. This lives in
+ * one place on purpose: when the default was written out at each call site, the
+ * merge step defaulted to 0 while scoring defaulted to 1, and an unweighted view
+ * merged with a `weight: 0.2` view scored as though both were 0.2.
+ */
+const effectiveWeight = (signal: { weight?: number | undefined }): number => signal.weight ?? 1;
+
+/** Most recent first. A signal with no timestamp sorts last. */
+function byMostRecent(
+  left: { at?: number | undefined },
+  right: { at?: number | undefined },
+): number {
+  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>();
+
+  for (const signal of signals.toSorted(byMostRecent)) {
+    if (alreadySeen.has(signal.sku)) continue;
+    alreadySeen.add(signal.sku);
+    skus.push(signal.sku);
+    if (skus.length >= limit) break;
+  }
+
+  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>,
+): 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>();
+
+  const addScore = (category: string | undefined, score: number): void => {
+    if (!category) return;
+    scoreByCategory.set(category, (scoreByCategory.get(category) ?? 0) + score);
+  };
+
+  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));
+  }
+  // Merged first, deliberately — see `mergeViewsBySku`. Views are noisy and
+  // repeat cheaply, so the tenth view counts for far less than the second, and
+  // log scaling keeps a single obsessive session from drowning out a purchase.
+  for (const view of mergeViewsBySku(signals.mostViewed)) {
+    const scaledViews = Math.log2(1 + view.views);
+    addScore(categoryOf(view, candidatesBySku), SIGNAL_WEIGHTS.view * scaledViews * view.weight);
+  }
+  for (const dislike of signals.dislikes) {
+    addScore(
+      categoryOf(dislike, candidatesBySku),
+      SIGNAL_WEIGHTS.dislike * effectiveWeight(dislike),
+    );
+  }
+
+  // The category the shopper is standing in right now is itself evidence.
+  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)
+    .toSorted((left, right) => right.score - left.score)
+    .slice(0, DIGEST_LIMITS.affinity);
+}
+
+interface MergedView extends ViewedProduct {
+  category?: string;
+  /** Always resolved, so no consumer has to re-apply the default. */
+  weight: number;
+}
+
+/**
+ * Collapses every view record for one SKU into a single running total.
+ *
+ * This has to happen before any scoring. A host is free to emit one record per
+ * page view rather than a running count, and scoring each record separately
+ * would let thirty `views: 1` records outweigh one `views: 30` record six times
+ * 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>();
+
+  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));
+      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),
+    });
+  }
+
+  return [...totalsBySku.values()];
+}
+
+/** The most-viewed few, as the digest reports them. */
+function mostViewedProducts(views: ViewSignal[]): ViewedProduct[] {
+  return 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 } : {}),
+    }));
+}
+
+/** The open-vocabulary long tail, reduced to "which kinds, and how often". */
+function countByInteractionType(interactions: Interaction[]): InteractionCount[] {
+  const countByType = new Map<string, number>();
+
+  for (const interaction of interactions) {
+    countByType.set(interaction.type, (countByType.get(interaction.type) ?? 0) + 1);
+  }
+
+  return [...countByType.entries()]
+    .map(([type, count]) => ({ type, count }))
+    .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 cartSkus = recentUniqueSkus(signals.cart, DIGEST_LIMITS.cart);
+  const topViewed = mostViewedProducts(signals.mostViewed);
+
+  // Searches say what a shopper wants; they do not say they engaged with any
+  // product, so they do not lift a shopper out of cold start on their own.
+  const evidenceCount =
+    likedSkus.length +
+    dislikedSkus.length +
+    purchasedSkus.length +
+    cartSkus.length +
+    topViewed.length;
+
+  return {
+    userId: user.id,
+    ...(user.segment !== undefined ? { segment: user.segment } : {}),
+    isReturning: user.isReturning ?? purchasedSkus.length > 0,
+
+    surface: context.surface,
+    slot: context.slot,
+    locale: context.locale,
+    maxItems: context.maxItems,
+    ...(context.currentSku !== undefined ? { currentSku: context.currentSku } : {}),
+    ...(context.currentCategory !== undefined ? { currentCategory: context.currentCategory } : {}),
+    ...(context.searchQuery !== undefined ? { searchQuery: context.searchQuery } : {}),
+
+    likedSkus,
+    dislikedSkus,
+    purchasedSkus,
+    cartSkus,
+    topViewed,
+    recentSearches: signals.recentSearches.slice(0, DIGEST_LIMITS.searches),
+    categoryAffinity: computeCategoryAffinity(input, candidatesBySku),
+    interactionCounts: countByInteractionType(signals.interactions),
+
+    isColdStart: evidenceCount === 0,
+  };
+}
+
+// Everything the cohort key leaves out has to leave the prompt too, or the
+// first shopper's searches and history end up shaping copy that is cached and
+// served to everyone else in their cohort.
+export function toCohortDigest(digest: SignalDigest): SignalDigest {
+  const top = digest.categoryAffinity[0];
+
+  // Listed rather than spread, so what survives is the thing you read.
+  const cohort: SignalDigest = {
+    userId: 'cohort',
+    isReturning: false,
+    surface: digest.surface,
+    slot: digest.slot,
+    locale: digest.locale,
+    maxItems: digest.maxItems,
+    likedSkus: [],
+    dislikedSkus: [],
+    purchasedSkus: [],
+    cartSkus: [],
+    topViewed: [],
+    recentSearches: [],
+    categoryAffinity: top ? [{ category: top.category, score: 0 }] : [],
+    interactionCounts: [],
+    isColdStart: digest.isColdStart,
+  };
+
+  if (digest.segment !== undefined) cohort.segment = digest.segment;
+  if (digest.currentCategory !== undefined) cohort.currentCategory = digest.currentCategory;
+
+  return cohort;
+}

package/src/spec-cache.ts

@@ -0,0 +1,223 @@
+import { createHash } from 'node:crypto';
+import { SPEC_VERSION, type GeneratedSpec } from './component-spec.js';
+import type { SignalDigest } from './signal-digest.js';
+
+/**
+ * Where a generated component is kept between requests.
+ *
+ * A generation is stable for as long as the shopper's signals are, so asking a
+ * model again on the next page view buys nothing and costs a round trip on the
+ * render path — which is the latency this whole design exists to avoid.
+ *
+ * The store is a port rather than an implementation. A single process can use
+ * the in-memory one; anything running more than one instance needs a shared
+ * store, or each instance keeps its own copy and the hit rate divides by the
+ * 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.
+ *
+ * The timestamp travels with the spec because it cannot be recovered later: a
+ * component served from cache is not newly generated, and `generatedAt` is the
+ * only way anything downstream can tell how stale what it is showing has become.
+ */
+export interface CachedSpec {
+  spec: GeneratedSpec;
+  /** Epoch milliseconds at which the model produced this. */
+  generatedAt: number;
+}
+
+export interface SpecCache {
+  get(key: string): Promise<CachedSpec | undefined>;
+  set(key: string, cached: CachedSpec): Promise<void>;
+}
+
+export interface MemorySpecCacheOptions {
+  /** How long an entry stays valid. Defaults to 60 seconds. */
+  ttlMs?: number;
+  /** Hard ceiling on entries. Least recently read is evicted first. */
+  maxEntries?: number;
+  /** Injectable clock, so tests do not have to wait. */
+  now?: () => number;
+}
+
+function assertFiniteAtLeastZero(name: string, value: number): void {
+  if (Number.isFinite(value) && value >= 0) return;
+
+  const hint = Number.isNaN(value)
+    ? ' (a common cause is Number() on an environment variable that is not set)'
+    : '';
+  throw new RangeError(`${name} must be a finite number of at least 0, received ${value}${hint}`);
+}
+
+interface CacheEntry {
+  cached: CachedSpec;
+  expiresAt: number;
+}
+
+/**
+ * A bounded in-process cache.
+ *
+ * `maxEntries` is generous relative to the default TTL for a reason: a ceiling
+ * low enough to evict entries before they expire silently turns a longer TTL
+ * into a setting that does nothing, and the person who raised it has no way to
+ * tell.
+ */
+export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): SpecCache {
+  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.
+  assertFiniteAtLeastZero('ttlMs', ttlMs);
+  assertFiniteAtLeastZero('maxEntries', maxEntries);
+  if (!Number.isSafeInteger(maxEntries)) {
+    throw new RangeError(`maxEntries must be a whole number, received ${maxEntries}`);
+  }
+
+  const now = options.now ?? Date.now;
+  const entries = new Map<string, CacheEntry>();
+
+  return {
+    async get(key) {
+      const entry = entries.get(key);
+      if (!entry) return undefined;
+
+      if (entry.expiresAt <= now()) {
+        entries.delete(key);
+        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.
+      entries.delete(key);
+      entries.set(key, entry);
+      return entry.cached;
+    },
+
+    async set(key, cached) {
+      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);
+      }
+    },
+  };
+}
+
+/**
+ * A cache that stores nothing, so every request generates.
+ *
+ * This is not a stub. It is the control for any measurement of generation cost
+ * or latency: with a cache in front, a benchmark reports how often it hit, not
+ * what generating costs.
+ */
+export function createNullSpecCache(): SpecCache {
+  return {
+    async get() {
+      return undefined;
+    },
+    async set() {
+      // Deliberately nothing.
+    },
+  };
+}
+
+/** Stable JSON: object keys sorted, so key order in a digest cannot matter. */
+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(',')}}`;
+}
+
+/**
+ * Derives the cache key.
+ *
+ * The digest goes in **whole**, rather than as a hand-picked list of fields.
+ * That is the entire point of this function. The previous implementation listed
+ * the fields it thought mattered, and four of them drifted: they reached the
+ * model but not the key, so two shoppers with genuinely different histories
+ * collided and were served each other's component. Hashing the whole digest
+ * makes that class of bug unreachable — a field cannot be forgotten here,
+ * because nothing is named here.
+ *
+ * The cost is a lower hit rate than a hand-tuned key would give, since every
+ * signal now moves the key. That is the right way round: a key that is too
+ * specific wastes money, and a key that is too loose shows one shopper another
+ * shopper's page. Raising the hit rate means deliberately coarsening the digest
+ * itself, which is a decision to make against measurements rather than by
+ * guessing here.
+ *
+ * Candidates enter as SKUs only. Their titles, prices and ratings reach the
+ * model too, but including them would churn the key on every price change for
+ * copy that would almost always come back the same. The consequence is bounded
+ * and worth stating: within one TTL, a price change does not refresh the
+ * generated copy. It cannot show a stale price — prices are read from the live
+ * catalog at render time, never from the model.
+ */
+export function specCacheKey(
+  digest: SignalDigest,
+  candidateSkus: readonly string[],
+  providerId: string,
+): 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.
+    specVersion: SPEC_VERSION,
+    provider: providerId,
+    digest,
+    candidates: candidateSkus.toSorted(),
+  });
+
+  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.
+export function cohortCacheKey(
+  digest: SignalDigest,
+  candidateSkus: readonly string[],
+  providerId: string,
+): string {
+  const material = canonicalise({
+    specVersion: SPEC_VERSION,
+    provider: providerId,
+    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.
+    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.
+    candidates: candidateSkus.toSorted(),
+  });
+
+  return createHash('sha256').update(material).digest('hex').slice(0, 32);
+}