@rudra-js/core 0.6.0 → 0.7.1

package/src/reconciliation.ts

@@ -9,13 +9,6 @@ import type {
 import { engagedCategories, type SignalDigest } from './signal-digest.js';
 import type { Bundle, Product, TrackingInput } from './tracking-input.js';
 
-/**
- * Nothing here trusts the model. Repair, not rejection, is the default: text is
- * truncated and unverifiable claims are downgraded, and only an empty result
- * fails outright.
- */
-
-/** Truncation ceilings. Not in the schema — a provider's strict mode rejects length bounds. See `component-spec.ts`. */
 const CLAMP = {
   headline: 90,
   subheadline: 140,
@@ -26,23 +19,21 @@ const CLAMP = {
   bannerText: 160,
   copyBody: 420,
   rationale: 300,
-  // Not rendered anywhere — this is the SKU as it reads back in a violation.
+
   violationSku: 32,
 } as const;
 
-/** More than this and the component stops being a component. */
 export const MAX_BLOCKS = 4;
 
-/** The fill pass calls this too: one past the cap never renders, so nothing is worth reserving for it. */
 export function capBlocks(blocks: Block[]): Block[] {
   return blocks.slice(0, MAX_BLOCKS);
 }
 
 export interface ReconcileResult {
   spec: GeneratedSpec;
-  /** True when something survived that is worth rendering. */
+
   isUsable: boolean;
-  /** Machine-readable notes on what was removed or changed, for evaluation. */
+
   violations: string[];
 }
 
@@ -50,35 +41,19 @@ function clamp(value: string, limit: number): string {
   const collapsed = value.trim().replace(/\s+/g, ' ');
   if (collapsed.length <= limit) return collapsed;
 
-  // The ellipsis counts against the limit, so leave room for it.
   const cut = collapsed.slice(0, limit - 1);
   const lastSpace = cut.lastIndexOf(' ');
   const base = lastSpace > limit * 0.6 ? cut.slice(0, lastSpace) : cut;
   return `${base.replace(/[.,;:!?-]+$/, '')}…`;
 }
 
-function clampNullable(value: string | null, limit: number): string | null {
-  if (value === null) return null;
-  const clamped = clamp(value, limit);
-  return clamped.length === 0 ? null : clamped;
-}
-
 interface Allowlist {
   allowed: Set<string>;
   blocked: Set<string>;
-  /** A bundle is placed whole, so it checks this narrower set. See `refusedEverywhere`. */
+
   blockedInBundle: Set<string>;
 }
 
-/**
- * A thumbs-down, and the product on the screen right now. No block may hold one
- * of these, a bundle included.
- *
- * Read from the payload rather than the digest on purpose. `DIGEST_LIMITS`
- * trims each history to what fits in a prompt, and a shopper with thirteen
- * dislikes would otherwise be shown the thirteenth. The cap exists to bound
- * what the model is told, not what the shopper may be shown.
- */
 function refusedEverywhere(input: TrackingInput): Set<string> {
   const refused = new Set<string>();
   for (const signal of input.signals.dislikes) refused.add(signal.sku);
@@ -87,17 +62,6 @@ function refusedEverywhere(input: TrackingInput): Set<string> {
   return refused;
 }
 
-/**
- * SKUs that must never be recommended, whatever chose them.
- *
- * Everything above plus what the shopper already has, read from the payload for
- * the same reason: a shopper with nine purchases must not be sold the ninth back.
- *
- * Exported because the deterministic selector applies the same rule when it
- * picks. Two copies of "never recommend these" would drift, and the pair that
- * drifted would be the model path and the fallback path — the two whose
- * comparability the whole evaluation depends on.
- */
 export function neverRecommend(input: TrackingInput): Set<string> {
   const { signals } = input;
 
@@ -136,9 +100,6 @@ function verifyBasis(
     case 'complements_purchase':
       return digest.purchasedSkus.length > 0;
     case 'liked_category':
-      // Affinity alone is not enough: it scores the category the shopper is
-      // standing in, and standing somewhere is not liking it. That claim is
-      // `similar_to_current`, which says so honestly.
       return (
         engaged.has(product.category) &&
         digest.categoryAffinity.some((affinity) => affinity.category === product.category)
@@ -146,17 +107,14 @@ function verifyBasis(
     case 'similar_to_current':
       return digest.currentCategory === product.category;
     case 'popular':
-      // Makes no claim about this shopper, so there is nothing to check.
       return true;
   }
 }
 
-/** Anything attested reads as a numeral — ½ ² Ⅲ included, which it reports rather than ignores. */
 const NUMERAL = /[\p{Nd}\p{No}\p{Nl}]/u;
 
 const NO_FACTS: readonly string[] = [];
 
-/** The budget and the de-duplication set are global to a spec, not to a block. */
 function createPlacementTracker(maxItems: number, facts: HostFacts) {
   const placedSkus = new Set<string>();
   const violations: string[] = [];
@@ -182,14 +140,6 @@ function createPlacementTracker(maxItems: number, facts: HostFacts) {
 
 type PlacementTracker = ReturnType<typeof createPlacementTracker>;
 
-/**
- * Clamps, then screens. The cap has to happen here: clamping first can cut the word that
- * makes a claim a claim, so "Ridge picks, only 2 left!" renders past the stock pattern.
- *
- * Three passes, most specific first. Core's patterns name one of the five kinds; `quantity`
- * is the only proof in the stack, every numeral having to be one the shop supplied; `wording`
- * is a second denylist and the weakest, so it answers last.
- */
 function screenClaim(
   value: string | null,
   limit: number,
@@ -202,15 +152,12 @@ function screenClaim(
   const clamped = clamp(value, limit);
   if (clamped.length === 0) return null;
 
-  // Both ways round: clamping collapses whitespace, so "in  stock" only reads as a claim after.
   const kind = claimIn(value) ?? claimIn(clamped);
   if (kind !== null) {
     tracker.record(`unverifiable-claim:${kind}:${field}`);
     return null;
   }
 
-  // Nothing for the quantity layer to weigh without a numeral, whatever the facts say,
-  // and reading the fact list to prove that again per field is most of what this costs.
   const weighed = NUMERAL.test(clamped) ? facts : NO_FACTS;
 
   const result = verify(clamped, { values: weighed, allowedPhrases: ALLOWED_PHRASES });
@@ -226,11 +173,6 @@ function screenClaim(
   return clamped;
 }
 
-/**
- * Emptying a field that cannot be null hands it to the rule that already drops a block,
- * or a whole generation, whose text clamps to nothing — so a banner reading "20% off"
- * disappears rather than rendering blank.
- */
 function screenRequired(
   value: string,
   limit: number,
@@ -240,18 +182,9 @@ function screenRequired(
   return screenClaim(value, limit, field, tracker) ?? '';
 }
 
-/**
- * Does not consume budget — the caller does that once it commits.
- *
- * Order matters. The budget is checked last because it is the least specific cause:
- * these strings are the evaluation signal, and reporting a hallucinated SKU as
- * `budget:dropped` would understate how often the model invents products.
- */
 function rejectionFor(sku: string, allowlist: Allowlist, tracker: PlacementTracker): string | null {
-  // A rejected SKU is whatever the model wrote, and the schema cannot bound it.
   const named = clamp(sku, CLAMP.violationSku);
 
-  // Either hallucinated or out of stock. Either way it cannot render.
   if (!allowlist.allowed.has(sku)) return `unknown-sku:${named}`;
   if (allowlist.blocked.has(sku)) return `blocked-sku:${named}`;
   if (tracker.hasPlaced(sku)) return `duplicate-sku:${named}`;
@@ -278,7 +211,7 @@ function reconcileItems(
     }
 
     const product = candidatesBySku.get(item.sku);
-    // rejectionFor already proved the SKU is an in-stock candidate.
+
     if (!product) continue;
 
     tracker.place(item.sku);
@@ -286,22 +219,17 @@ function reconcileItems(
     const hasSupportedBasis = verifyBasis(item.basis, product, digest, engaged);
     if (!hasSupportedBasis) tracker.record(`unsupported-basis:${item.basis}:${item.sku}`);
 
-    // Our sentence, not the model's. It has to match, so a lookalike is still screened.
     const isOurs = item.reason !== null && ourReasons.get(item.sku) === item.reason;
 
     const own = tracker.factsFor(item.sku);
-    const clampedReason = clampNullable(item.reason, CLAMP.reason);
 
-    // The prose exists to state the basis. If the basis did not hold, the prose
-    // is untrue — and the badge is prose too. "You viewed this" beside a
-    // downgraded pick says the same thing the dropped sentence did.
     let reason: string | null = null;
     let badge: string | null = null;
     if (hasSupportedBasis) {
       reason = isOurs
-        ? clampedReason
+        ? clamp(item.reason ?? '', CLAMP.reason) || null
         : screenClaim(item.reason, CLAMP.reason, `reason:${item.sku}`, tracker, own);
-      // The schema's own example badge was "Back in stock" — a stock claim, and it renders.
+
       badge = screenClaim(item.badge, CLAMP.badge, `badge:${item.sku}`, tracker, own);
     }
 
@@ -317,7 +245,6 @@ function reconcileItems(
   return kept;
 }
 
-// Cart beats views beats category however the counts compare, so they can't be summed.
 interface BundleFit {
   cartHits: number;
   viewedHits: number;
@@ -378,17 +305,6 @@ function chooseBundle(
   return best;
 }
 
-/**
- * The set this shopper should get, decided before anything is placed.
- *
- * The generator needs the answer early, so it can keep the set's products out
- * of the grid and keep room for them. `chooseBundle` stays private: this hands
- * out the choice, not the machinery behind it.
- *
- * `spokenFor` is what the blocks above the bundle block will have placed by the
- * time it is reached. Placing it here first is what makes the two choices agree:
- * a set is only pre-chosen if reconciliation could still reach for it.
- */
 export function bundleForShopper(
   input: TrackingInput,
   digest: SignalDigest,
@@ -403,14 +319,6 @@ export function bundleForShopper(
   return chooseBundle(input.bundles, allowlist, digest, candidatesBySku, tracker);
 }
 
-/**
- * The hero products these blocks will really place.
- *
- * A hero keeps the product the model named — its headline was written about
- * that product — so it spends a slot of the item budget the grid cannot have.
- * One this shopper cannot see is dropped below and spends nothing, so it is not
- * counted here either.
- */
 export function placeableHeroSkus(blocks: readonly Block[], input: TrackingInput): string[] {
   const allowlist = buildAllowlist(input);
 
@@ -443,13 +351,13 @@ function reconcileBlock(
         const rejection = rejectionFor(sku, allowlist, tracker);
         if (rejection) {
           tracker.record(rejection);
-          // A hero without its product is still a legitimate headline.
+
           sku = null;
         } else {
           tracker.place(sku);
         }
       }
-      // A hero with no headline and no product is the empty region every other kind drops for.
+
       const headline = screenRequired(block.headline, CLAMP.headline, 'hero-headline', tracker);
       if (headline.length === 0 && sku === null) {
         tracker.record('empty-block:hero');
@@ -481,7 +389,7 @@ function reconcileBlock(
       return {
         kind: 'grid',
         title: screenClaim(block.title, CLAMP.blockTitle, 'grid-title', tracker),
-        // Never leave a grid wider than it has items to fill.
+
         columns: Math.min(block.columns, Math.max(2, items.length)) as 2 | 3 | 4,
         items,
       };
@@ -549,7 +457,7 @@ function reconcileBlock(
         title: screenClaim(block.title, CLAMP.blockTitle, 'bundle-title', tracker),
         body: screenClaim(block.body, CLAMP.subheadline, 'bundle-body', tracker),
         ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'bundle-cta', tracker),
-        // The model's bundleId is ignored on purpose.
+
         bundleId: chosen.id,
       };
     }
@@ -570,14 +478,7 @@ export function reconcileSpec(
   generated: GeneratedSpec,
   input: TrackingInput,
   digest: SignalDigest,
-  /**
-   * The reason this request wrote itself, by SKU: the host's own `reason` on a
-   * candidate, or the sentence the selector wrote when there was none. Neither is the
-   * model's words, and the deterministic component renders the same sentence unscreened.
-   *
-   * Only `fitToShopper` fills it, so in `per-shopper` mode it is empty and every
-   * reason is the model's, including one that happens to read the same.
-   */
+
   ourReasons: ReadonlyMap<string, string> = new Map(),
 ): ReconcileResult {
   const allowlist = buildAllowlist(input);
@@ -612,7 +513,6 @@ export function reconcileSpec(
     rationale: screenRequired(generated.rationale, CLAMP.rationale, 'rationale', tracker),
   };
 
-  // Recorded separately: no products and no headline are different failures.
   if (!showsAnyProduct(blocks)) tracker.record('unusable:no-products');
   if (spec.headline.length === 0) tracker.record('unusable:no-headline');
   const isUsable = showsAnyProduct(blocks) && spec.headline.length > 0;

package/src/signal-digest.ts

@@ -6,22 +6,9 @@ import type {
   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;
 }
 
@@ -58,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,
@@ -77,7 +59,6 @@ export const DIGEST_LIMITS = {
   interactionTypes: 8,
 } as const;
 
-/** How much intent each kind of signal implies. */
 const SIGNAL_WEIGHTS = {
   purchase: 5,
   like: 4,
@@ -86,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 },
@@ -148,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);
@@ -162,8 +134,6 @@ function computeCategoryAffinity(
     );
   }
 
-  // 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);
 
   const affinities: CategoryAffinity[] = [];
@@ -177,15 +147,6 @@ function computeCategoryAffinity(
     .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;
@@ -209,16 +170,6 @@ interface MergedView extends ViewedProduct {
   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.
- */
 function mergeViewsBySku(views: ViewSignal[]): MergedView[] {
   const totalsBySku = new Map<string, MergedView>();
 
@@ -248,13 +199,9 @@ function mostViewedProducts(views: ViewSignal[]): ViewedProduct[] {
     .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 },
+  );
 }
 
 function countByInteractionType(interactions: Interaction[]): InteractionCount[] {
@@ -281,8 +228,6 @@ export function buildDigest(input: TrackingInput): SignalDigest {
   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 +
@@ -316,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,20 +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;
 
-  // 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)) {
@@ -96,8 +60,6 @@ export function createMemorySpecCache(options: MemorySpecCacheOptions = {}): Spe
         return undefined;
       }
 
-      // 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;
@@ -120,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(',')}]`;
@@ -152,52 +104,12 @@ 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.
- *
- * 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[],
-  provider: ProviderIdentity,
+  provider: { name: string; model: string },
 ): string {
   const material = canonicalise({
-    // 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,
@@ -208,11 +120,10 @@ export function specCacheKey(
   return createHash('sha256').update(material).digest('hex').slice(0, 32);
 }
 
-// Leaves out the personal fields: who the shopper is, what they liked, viewed or searched.
 export function cohortCacheKey(
   digest: SignalDigest,
   candidateSkus: readonly string[],
-  provider: ProviderIdentity,
+  provider: { name: string; model: string },
 ): string {
   const material = canonicalise({
     specVersion: SPEC_VERSION,
@@ -224,11 +135,10 @@ export function cohortCacheKey(
     locale: digest.locale,
     maxItems: digest.maxItems,
     isColdStart: digest.isColdStart,
-    // 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 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(),
   });