@rudra-js/core 0.5.0 → 0.7.0

package/src/signal-digest.ts

@@ -1,28 +1,14 @@
 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;
 }
 
@@ -59,14 +45,9 @@ export interface SignalDigest {
   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,
@@ -78,11 +59,6 @@ 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.
- */
 const SIGNAL_WEIGHTS = {
   purchase: 5,
   like: 4,
@@ -91,15 +67,8 @@ const SIGNAL_WEIGHTS = {
   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 },
@@ -107,7 +76,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 +90,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>,
@@ -159,9 +122,7 @@ function computeCategoryAffinity(
   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);
@@ -173,37 +134,42 @@ function computeCategoryAffinity(
     );
   }
 
-  // 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)
+  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);
 }
 
+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;
 }
 
-/**
- * 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>();
 
@@ -228,22 +194,16 @@ 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)
     .slice(0, DIGEST_LIMITS.viewed);
 
-  const products: ViewedProduct[] = [];
-  for (const merged of top) {
-    const product: ViewedProduct = { sku: merged.sku, views: merged.views };
-    if (merged.dwellMs !== undefined) product.dwellMs = merged.dwellMs;
-    products.push(product);
-  }
-  return products;
+  return top.map(({ sku, views: count, dwellMs }) =>
+    dwellMs === undefined ? { sku, views: count } : { sku, views: count, dwellMs },
+  );
 }
 
-/** The open-vocabulary long tail, reduced to "which kinds, and how often". */
 function countByInteractionType(interactions: Interaction[]): InteractionCount[] {
   const countByType = new Map<string, number>();
 
@@ -251,28 +211,23 @@ 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);
 
-  // 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 +
@@ -306,13 +261,9 @@ export function buildDigest(input: TrackingInput): SignalDigest {
   };
 }
 
-// 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,

package/src/spec-cache.ts

@@ -3,37 +3,12 @@ import { SPEC_VERSION, type GeneratedSpec } from './component-spec.js';
 import { SYSTEM_PROMPT } from './model-prompt.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.
- */
-
-/**
- * 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;
 }
 
-/**
- * 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.
- */
 export interface SpecCache {
   get(key: string): Promise<CachedSpec | undefined>;
   set(key: string, cached: CachedSpec): Promise<void>;
@@ -41,11 +16,10 @@ export interface SpecCache {
 }
 
 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;
 }
 
@@ -63,24 +37,10 @@ interface CacheEntry {
   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)) {
@@ -100,8 +60,6 @@ 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.
       entries.delete(key);
       entries.set(key, entry);
       return entry.cached;
@@ -124,25 +82,15 @@ export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): Spe
   };
 }
 
-/**
- * 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.
-    },
+    async set() {},
   };
 }
 
-/** 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(',')}]`;
@@ -156,42 +104,15 @@ function canonicalise(value: unknown): string {
 
 const PROMPT_FINGERPRINT = createHash('sha256').update(SYSTEM_PROMPT).digest('hex').slice(0, 16);
 
-/**
- * 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,
+  provider: { name: string; model: 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,
     prompt: PROMPT_FINGERPRINT,
-    provider: providerId,
+    provider,
     digest,
     candidates: candidateSkus.toSorted(),
   });
@@ -199,33 +120,25 @@ 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.
 export function cohortCacheKey(
   digest: SignalDigest,
   candidateSkus: readonly string[],
-  providerId: string,
+  provider: { name: string; model: string },
 ): 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.
+
     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(),
   });
 

package/src/tracking-input.ts

@@ -1,36 +1,5 @@
 import { z } from 'zod';
 
-/**
- * The tracking-input contract — the boundary between the host application and
- * rudra-js.
- *
- * rudra-js does not collect, store, or aggregate anything. The host owns its
- * tracking pipeline (an event stream, a CDP, a warehouse) and hands the
- * framework one JSON object per render. This module is that contract: one
- * schema, validated at the edge, so a malformed payload fails loudly here
- * rather than quietly producing a bad prompt several layers later.
- *
- * Every fixed-shape object below is a `strictObject`, so an unrecognised field
- * is an error rather than being dropped. That matters more than it looks: with
- * a lenient object, a host that misspells `recentSearches` gets a shopper who
- * silently looks like a first-time visitor, and nothing anywhere reports it.
- * The only dynamic shape is `interaction.meta`, which is a record by design.
- */
-
-/**
- * Every free-text field and every array is length-capped.
- *
- * These caps are not cosmetic. Host-supplied strings end up inside the prompt
- * we send to a language model, and a model is billed per token — so an
- * unbounded string is an unbounded bill, and an unbounded array of candidates
- * is the same problem multiplied.
- *
- * What this buys is that no single field is unbounded. It is deliberately not
- * an aggregate budget: the caps multiply out to far more than any context
- * window, because rejecting a large-but-legitimate payload is the wrong
- * response to one. Fitting a payload into a prompt is `digest`'s job, and it
- * trims rather than throws.
- */
 export const FIELD_LIMITS = {
   identifier: 128,
   shortText: 200,
@@ -44,45 +13,34 @@ 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. */
 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);
 const optionalIdentifier = () => z.string().min(1).max(FIELD_LIMITS.identifier).optional();
 
-/**
- * Epoch milliseconds, used only for recency ordering. Bounded because a
- * negative or year-3000 timestamp does not fail anywhere downstream — it just
- * sorts to one end and silently reorders the shopper's history.
- */
 const epochMs = () => z.number().int().min(0).max(MAX_EPOCH_MS).optional();
 
-/**
- * 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`
- * — is rejected before it can reach an `<img src>`.
- */
+const isRootRelative = (value: string) => {
+  const asParsed = value.replace(/[\t\n\r]/g, '');
+  return value.startsWith('/') && /^\/(?![/\\])/.test(asParsed);
+};
+
 const imageReference = () =>
   z
     .string()
     .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' },
     );
 
-/** A product the generated component is permitted to place. */
 export const productSchema = z.strictObject({
   sku: identifier(),
   title: z.string().min(1).max(FIELD_LIMITS.shortText),
@@ -92,15 +50,10 @@ export const productSchema = z.strictObject({
     .string()
     .regex(/^[A-Z]{3}$/, 'expected a three-letter ISO 4217 code')
     .default('USD'),
-  // This lands in an `<img src>` the host did not write, so the scheme matters:
-  // a bare capped string would accept '' and 'javascript:'. Root-relative paths
-  // are allowed because most catalogs store images that way, and they carry no
-  // 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
@@ -110,12 +63,11 @@ export const productSchema = z.strictObject({
 });
 export type Product = z.infer<typeof productSchema>;
 
-/** Base shape for any signal that points at a single SKU. */
 export const skuSignalSchema = z.strictObject({
   sku: identifier(),
   category: optionalIdentifier(),
   at: epochMs(),
-  /** Caller-supplied strength, 0..1. Defaults to 1 when absent. */
+
   weight: z.number().min(0).max(1).optional(),
 });
 export type SkuSignal = z.infer<typeof skuSignalSchema>;
@@ -132,27 +84,12 @@ export const purchaseSignalSchema = skuSignalSchema.extend({
 });
 export type PurchaseSignal = z.infer<typeof purchaseSignalSchema>;
 
-/**
- * `meta` is the one dynamic shape in the contract, so its key is checked before
- * the record is parsed rather than after. Zod builds its result by assigning
- * 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) =>
     typeof value === 'object' && value !== null && !Object.hasOwn(value, RESERVED_META_KEY),
   { message: `meta may not use the reserved key ${RESERVED_META_KEY}` },
 );
 
-// `z.record` bounds key and value shape but not how many entries a record may
-// carry, so the count is checked separately.
 const metaSchema = metaKeysAreSafe.pipe(
   z
     .record(
@@ -164,11 +101,6 @@ const metaSchema = metaKeysAreSafe.pipe(
     }),
 );
 
-/**
- * Catch-all for everything else the shopper did. `type` is an open vocabulary
- * on purpose — 'scroll_depth', 'wishlist', 'filter_applied', whatever the host
- * already emits — so hosts do not have to map their events onto ours.
- */
 export const interactionSchema = z.strictObject({
   type: identifier(),
   sku: optionalIdentifier(),
@@ -179,23 +111,20 @@ export const interactionSchema = z.strictObject({
 });
 export type Interaction = z.infer<typeof interactionSchema>;
 
-/** Where on the site this component is being rendered. */
 export const renderContextSchema = z.strictObject({
-  /** 'pdp', 'home', 'cart', 'search', or any host-defined surface. */
   surface: identifier(),
-  /** Named placement, e.g. 'below-fold-recommendations'. */
+
   slot: z.string().min(1).max(FIELD_LIMITS.identifier).default('recommendations'),
   currentSku: optionalIdentifier(),
   currentCategory: optionalIdentifier(),
   searchQuery: z.string().max(FIELD_LIMITS.searchQuery).optional(),
-  // One language tag, not the Accept-Language header it is often copied from:
-  // the locale is part of the cohort cache key, so a list makes its own cohort.
+
   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'),
-  /** Upper bound on products across the whole generated component. */
+
   maxItems: z.number().int().min(1).max(FIELD_LIMITS.maxItems).default(4),
 });
 export type RenderContext = z.infer<typeof renderContextSchema>;
@@ -214,7 +143,6 @@ export const trackingSignalsSchema = z.strictObject({
 });
 export type TrackingSignals = z.infer<typeof trackingSignalsSchema>;
 
-/** A set the shop sells together. The model never picks or invents one. */
 export const bundleSchema = z.strictObject({
   id: identifier(),
   skus: z
@@ -224,8 +152,7 @@ export const bundleSchema = z.strictObject({
     .refine((skus) => new Set(skus).size === skus.length, {
       message: 'a bundle must not list the same product twice',
     }),
-  // The shop's price for the set — not derived from the parts, so the set says
-  // which money it is in rather than borrowing it from a member.
+
   price: z.number().nonnegative(),
   currency: z
     .string()
@@ -244,19 +171,9 @@ 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.
+
     signals: trackingSignalsSchema.prefault({}),
-    /**
-     * The only products the generated component may place. Merchandising rules
-     * belong here: whatever the host leaves out cannot be recommended, which is
-     * what makes it impossible to surface a product that does not exist or is not
-     * merchandised for this shopper.
-     *
-     * SKUs must be unique — a duplicate is a host bug that spends prompt budget
-     * twice and invites the same product in two slots.
-     */
+
     candidates: z
       .array(productSchema)
       .min(1)
@@ -267,8 +184,7 @@ export const trackingInputSchema = z
           message: 'candidates must have unique SKUs',
         },
       ),
-    // Ids must be unique — the renderer looks a bundle up by id alone, so a
-    // duplicate would let it draw the wrong set at the wrong price.
+
     bundles: z
       .array(bundleSchema)
       .max(FIELD_LIMITS.bundles)
@@ -292,24 +208,14 @@ export const trackingInputSchema = z
 
 export type TrackingInput = z.infer<typeof trackingInputSchema>;
 
-/** The shape a caller passes in, before defaults are applied. */
 export type TrackingInputDraft = z.input<typeof trackingInputSchema>;
 
-/**
- * The result of a non-throwing parse. Exported so a consumer can type a
- * validation failure without depending on zod directly.
- */
 export type TrackingInputResult = z.ZodSafeParseResult<TrackingInput>;
 
-/**
- * Validates a payload, throwing a `ZodError` if it does not satisfy the
- * contract. An invalid payload is a caller bug, and it should be loud.
- */
 export function parseTrackingInput(value: unknown): TrackingInput {
   return trackingInputSchema.parse(value);
 }
 
-/** Non-throwing variant, for callers that want to inspect the failure. */
 export function safeParseTrackingInput(value: unknown): TrackingInputResult {
   return trackingInputSchema.safeParse(value);
 }