@rudra-js/core 0.2.0 → 0.3.1

package/README.md

@@ -9,55 +9,60 @@ component specification.
 npm install @rudra-js/core zod@^4
 ```
 
-`zod` is a peer dependency: the package's public API _is_ zod schemas, so your
-application and this package must resolve the same zod instance. **zod 4 is
-required** — the schemas use zod 4 APIs, and installing into a zod 3 app fails
-with `ERESOLVE` rather than anything more helpful.
+`zod` is a peer dependency. The public API of this package _is_ zod schemas, so
+your app and the package have to resolve the same copy of zod. **zod 4.5 or later is
+required**, which is what the peer range asks for. The schemas use zod 4 APIs,
+and installing into a zod 3 app fails with `ERESOLVE`, which isn't the most
+helpful error you'll ever read. The floor is 4.5 rather than 4.0 because 4.5
+changed how a nullable field is written into the tool schema we send the model.
 
 ## Running without a model
 
 `createComponentGenerator` takes a `provider`. Leave it out, or pass `null`, and
-nothing calls a model and nothing is billed:
+nothing calls a model and nothing gets billed:
 
 ```ts
 const generator = createComponentGenerator({ provider: null });
 const spec = await generator.generate(input);
 ```
 
-That is a supported configuration rather than a stub. It is the control arm of
-the benchmark, and the right setting for anyone who has not yet decided on a
-provider. `generate` returns a promise either way, so the shape of your code
-does not change when you add one.
-
-The deterministic component emits exactly one **grid** block — or nothing, when
-no candidate is in stock — with a headline from a fixed set of four. Every other
-block kind in the vocabulary (hero, carousel, banner, copy, bundle) only ever
-comes from a model. If you are wiring bundles and none appear, that is why, and
-not your catalog.
-
-To render a spec you wrote yourself, without a model, pass
-`createFixedSpecProvider(spec)` as the provider. It answers every request with
-that spec, which is how the tests exercise blocks the deterministic component
+This is a supported setting, not a stub. It's the control arm of the benchmark,
+and it's the right one until you've settled on a provider. `generate` returns a
+promise either way, so your code keeps its shape when you add one.
+
+The deterministic component emits exactly one **grid** block, with a headline
+from a fixed set of four, or no blocks at all when there's nothing left to show.
+That happens when no candidate is in stock, and equally when every one of them
+is ruled out for this shopper.
+Every other block kind in the vocabulary (hero, carousel, banner, copy, bundle)
+only ever comes from a model. So if you're wiring up bundles and none of them
+appear, that's why. It isn't your catalog.
+
+Want to render a spec you wrote yourself, still without a model? Pass
+`createFixedSpecProvider(spec)` as the provider and it answers every request with
+that spec. That's how our tests exercise the blocks the deterministic component
 never emits.
 
 ## Options
 
-Everything `createComponentGenerator` takes, and what it does without it.
+Everything `createComponentGenerator` takes, and what you get if you leave it
+out.
 
-| Option           | What it does                                                                                         | Default                   |
-| ---------------- | ---------------------------------------------------------------------------------------------------- | ------------------------- |
-| `provider`       | The model adapter. `null` runs without a model and bills nothing.                                    | `null`                    |
-| `cache`          | Where generated specs are kept between requests. Pass `createNullSpecCache()` to keep none.          | `createMemorySpecCache()` |
-| `generation`     | `'cohort'` shares one component between shoppers who look alike; `'per-shopper'` generates for each. | `'cohort'`                |
-| `modelTimeoutMs` | How long the model gets. Past this the request is aborted and the deterministic component renders.   | `1500`                    |
-| `cacheTimeoutMs` | How long a cache read gets. Past this the request generates as if the store had nothing.             | `50`                      |
-| `onEvent`        | Called once per `generate` with a `GenerationEvent`. A hook that throws is swallowed.                | none                      |
+| Option           | What it does                                                                                    | Default                   |
+| ---------------- | ----------------------------------------------------------------------------------------------- | ------------------------- |
+| `provider`       | The model adapter. `null` runs without a model and bills nothing.                               | `null`                    |
+| `cache`          | Where generated specs live between requests. Pass `createNullSpecCache()` to keep none.         | `createMemorySpecCache()` |
+| `generation`     | `'cohort'` shares one component between shoppers who look alike; `'per-shopper'` does each one. | `'cohort'`                |
+| `rank`           | `'signals'` orders products by the shopper's signals; `'given'` keeps the order you sent.       | `'signals'`               |
+| `modelTimeoutMs` | How long the model gets. Past that, we abort the request and render the deterministic one.      | `1500`                    |
+| `cacheTimeoutMs` | How long a cache read gets. Past that, the request generates as if the store had nothing.       | `50`                      |
+| `onEvent`        | Called once per `generate` with a `GenerationEvent`. If your hook throws, we swallow it.        | none                      |
 
 ## `tracking-input`
 
-The boundary between a host application and rudra-js. rudra-js collects,
-stores and aggregates nothing — the host owns its tracking pipeline and hands
-the framework one JSON object per render.
+The boundary between your application and rudra-js. We collect nothing, store
+nothing, aggregate nothing. You own your tracking pipeline and hand us one JSON
+object per render.
 
 ```ts
 import { parseTrackingInput } from '@rudra-js/core';
@@ -81,52 +86,55 @@ const input = parseTrackingInput({
 });
 ```
 
-`parseTrackingInput` throws a `ZodError`; `safeParseTrackingInput` returns a
-`TrackingInputResult` instead, so a host can inspect `result.error.issues`
-without importing zod itself.
+`parseTrackingInput` throws a `ZodError`. If you'd rather not catch,
+`safeParseTrackingInput` hands you a `TrackingInputResult` instead, so you can
+read `result.error.issues` without importing zod yourself.
 
 ### Cold start is not an error
 
 A payload with no `signals` block is a first-time visitor, not a malformed
-request. Every category defaults to `[]`, so the host needs no special case.
+request. Every category defaults to `[]`, so you don't need a special case for
+it.
 
 ### What the host must supply
 
-`user.id`, `context.surface`, and at least one entry in `candidates`.
-`candidates` is the merchandising boundary. Every SKU the model writes is looked
-up in that list, and one that is not on it is dropped by reconciliation before
-anything renders — so a product you left out does not reach the page. SKUs must
+`user.id`, `context.surface`, and at least one entry in `candidates`. SKUs must
 be unique.
 
-`bundles` is optional: the sets the shop sells together, each with the shop's
-own price for the set, the currency that price is in, and, if you want one,
-your own name for it. Every product in a set must also be a candidate — that is
-what lets the same checks that pass a single product pass a whole set, and what
-lets the renderer look the members up in the catalog it already has. Ids must be
+`candidates` is the merchandising boundary. Every SKU the model writes gets
+looked up in that list, and one that isn't on it is dropped by reconciliation
+before anything renders. A product you left out doesn't reach the page.
+
+`bundles` is optional. These are the sets you sell together, each with your own
+price for the set, the currency that price is in, and, if you want one, your own
+name for it. Every product in a set has to be a candidate as well. That's what
+lets the same checks that pass a single product pass a whole set, and what lets
+the renderer look the members up in the catalog it already has. Ids must be
 unique, and one set must not name the same product twice.
 
-The model never picks a set and is never told a price. It only asks for a
-bundle block and writes the words around it; the framework picks which set when
-the page is served, from what the shopper has in their basket, has looked at,
-or is browsing now.
-
-Every word the model writes is read for claims: the headline, the subheadline,
-a hero, a banner, a block title, the copy block, the reason under a product,
-and the words around the set. Text you supplied is never read this way — a
-product title, a category and a bundle `label` are your words, not the model's.
-
-The framework drops text that makes a claim it cannot check. It looks for
-money, a customer score, a delivery date and a count of what is left, and it
-leaves a specification alone even when the specification has a number in it.
-Spotting one is not a guarantee, the way checking a price against your catalog
-is. A field that cannot be empty — a headline, a banner's text — is emptied
-instead of nulled, so the block drops the way any block with no text drops, and
+The model _never_ picks a set and is never told a price. All it does is ask for a
+bundle block and write the words around it. We pick which set when the page is
+served, going on what the shopper has in their basket, has looked at, or is
+browsing right now.
+
+Every word the model writes is read for claims: the headline, the subheadline, a
+hero, a banner, a block title, the copy block, the reason under a product, and
+the words around the set. Text you supplied is never read this way. A product
+title, a category and a bundle `label` are your words, not the model's.
+
+We drop text that makes a claim we can't check. The check looks for money, a
+customer score, a delivery date and a count of what's left, and it leaves a
+specification alone even when that specification has a number in it. Spotting one
+isn't a guarantee, not the way checking a price against your catalog is.
+
+Some fields can't be empty, like a headline or a banner's text. Those get emptied
+instead of nulled, so the block drops the way any block with no text drops. And
 an emptied page headline makes the whole generation unusable.
 
-For the set the prompt also tells the model to write about the offer, not the
-products in it, and never to say the set saves money or by how much. Pass a
-`label` on the bundle to put your own words on the set: a label is text you
-wrote, not text the model wrote, and it renders ahead of the model's words.
+For the set, the prompt also tells the model to write about the offer rather than
+the products in it, and never to say the set saves money or by how much. Pass a
+`label` on the bundle to put your own words on the set. A label is text you
+wrote, not text the model wrote, so it renders ahead of the model's words.
 
 ### Defaults
 
@@ -145,26 +153,26 @@ wrote, not text the model wrote, and it renders ahead of the model's words.
 | `mostViewed[].views`       | `1`                 |
 | `lastPurchased[].quantity` | `1`                 |
 
-`context.locale` has to be a single language tag, such as `en-US`. One tag, not
-a list and not an `Accept-Language` header.
+`context.locale` has to be a single language tag, such as `en-US`. One tag. Not a
+list, and not an `Accept-Language` header.
 
 ### Cohorts
 
-By default one generated component is shared between shoppers who look alike,
-and each shopper's own products are filled in per request. A cohort is the
-shopper's segment, the surface and slot, the locale, the item count, whether
-they are a first-time visitor, and the category they lean towards. Everything
-that makes a person an individual — who they are, what they liked, viewed or
-searched for — is left out, which is what lets many page views reuse one call.
+By default one generated component is shared between shoppers who look alike, and
+each shopper's own products are filled in per request. A cohort is the shopper's
+segment, the surface and slot, the locale, the item count, whether they're a
+first-time visitor, and the category they lean towards. Everything that makes a
+person an individual stays out of it: who they are, what they liked, viewed or
+searched for. That's what lets many page views reuse one call.
 
-The candidate list is part of the cohort too, because the model is shown those
+The candidate list is part of the cohort too, since the model is shown those
 products and writes about them. In most shops candidates come from the page, so
-everyone looking at it shares them. A shop that picks candidates per shopper
-gets smaller cohorts, which is the honest outcome: its prompt really is
+everyone looking at it shares them. If you pick candidates per shopper you'll get
+smaller cohorts. That's the honest outcome, because your prompt really is
 personal.
 
-Pass `generation: 'per-shopper'` to generate for the individual instead. Then
-the model chooses the products too, and every shopper pays for their own call.
+Pass `generation: 'per-shopper'` to generate for the individual instead. The
+model then chooses the products too, and every shopper pays for their own call.
 
 ```ts
 createComponentGenerator({ provider, generation: 'per-shopper' });
@@ -173,23 +181,22 @@ createComponentGenerator({ provider, generation: 'per-shopper' });
 #### What you put in `segment`
 
 `segment` is sent to the model exactly as you wrote it, in both modes, and the
-contract takes any string up to 128 characters. Use plain merchandising labels —
-`lapsed`, `high-value`, `trial`, `wholesale`. Keep out anything that says
-something protected about a person: health, race, ethnic origin, religion or
+contract takes any string up to 128 characters. Stick to plain merchandising
+labels like `lapsed`, `high-value`, `trial`, `wholesale`. Keep out anything that
+says something protected about a person: health, race, ethnic origin, religion or
 belief, sex life or sexual orientation, politics, union membership, biometric or
 genetic data.
 
-The same applies to `recentSearches`, `context.searchQuery` and
-`interaction.type` in per-shopper mode. Those three are shopper text, and they
-are sent as written. What a shopper types is theirs; what you label them with is
-your choice.
+The same goes for `recentSearches`, `context.searchQuery` and `interaction.type`
+in per-shopper mode. Those three are shopper text and they're sent as written.
+What a shopper types is theirs. What you label them with is your choice.
 
 ### Limits
 
-Every free-text field and every array is capped, because host strings end up
+Every free-text field and every array is capped, because your strings end up
 inside a model prompt and a model is billed per token. The caps live in
-`FIELD_LIMITS` and are exported, so a host can validate against the same
-numbers rather than discovering them from a rejection.
+`FIELD_LIMITS` and we export them, so you can validate against the same numbers
+instead of finding them out from a rejection.
 
 | Limit                | Value | Applies to                                                          |
 | -------------------- | ----- | ------------------------------------------------------------------- |
@@ -205,17 +212,59 @@ numbers rather than discovering them from a rejection.
 | `bundles`            | 20    | `bundles`                                                           |
 | `localeTag`          | 35    | `context.locale`, which also has to be one language tag             |
 | `maxItems`           | 12    | `context.maxItems`, which also needs at least 1                     |
+| `reason`             | 120   | `candidates[].reason`, your own phrase for a product                |
 
-These bound each field individually; they are not an aggregate prompt budget.
+These bound each field on its own. They aren't an aggregate prompt budget.
 Fitting a payload into a context window is `digest`'s job, and it trims rather
 than throws.
 
 ### Unknown fields are rejected
 
-Every fixed-shape object is a `strictObject`. A host that misspells
-`recentSearches` gets an error, not a shopper who silently looks like a
-first-time visitor. `interaction.meta` is the one dynamic shape — an open
-record, minus the keys that would mutate a prototype instead of the object.
+Every fixed-shape object is a `strictObject`. Misspell `recentSearches` and
+you'll get an error, not a shopper who quietly looks like a first-time visitor.
+`interaction.meta` is the one dynamic shape: an open record, minus the keys that
+would mutate a prototype instead of the object.
+
+## Bringing your own ranking
+
+By default we order the products for you, scoring each candidate against the
+shopper's signals. But you might already have a recommender you trust: bought
+together, an engine trained on your own orders, or a merchandiser's hand-picked
+row. Pass `rank: 'given'` and the order you sent is the order that renders.
+
+```ts
+const generator = createComponentGenerator({ provider, rank: 'given' });
+```
+
+You keep the rest either way. We still drop anything the shopper shouldn't be
+shown, whether it's out of stock, already bought, in the basket, disliked, or
+the product they're looking at right now. Every product still carries a basis
+we check against their real signals, and everything the model writes is still
+screened.
+
+Each candidate can carry its own `reason`, the phrase shown under the product.
+Reach for it when your ranking knows something the signals don't:
+
+```ts
+candidates: [
+  {
+    sku: 'A-2',
+    title: 'Enamel dutch oven',
+    category: 'Cookware',
+    price: 89,
+    reason: 'Bought together with your skillet',
+  },
+];
+```
+
+A reason you supply is your own words, like the title, so it is rendered as
+written and not screened. That only applies where this request actually used it,
+which is the default `cohort` mode. In `per-shopper` mode the model writes the
+reasons itself, so every one of them is screened, including one that happens to
+read the same as yours.
+
+Without a reason of your own, the basis is stated for you from the shopper's
+signals.
 
 ## What the model sees
 
@@ -227,12 +276,12 @@ The two generation modes send different things. Cohort is the default.
 - the locale
 - the segment, when you set one
 - the category being browsed (`context.currentCategory`)
-- the name of the category the shopper leans towards most — the name only, the
+- the name of the category the shopper leans towards most. Just the name, the
   score stays behind
 - whether this shopper has no history at all
 - how many products the component may place (`context.maxItems`)
-- the candidate list: one line per product, with its SKU, title, category,
-  rating and tags
+- the candidate list: one line per product, with its SKU, title, category, rating
+  and tags
 
 ### Per-shopper mode
 
@@ -251,24 +300,24 @@ Everything above, and:
 ### Left out of both
 
 - `user.id`
-- every timestamp (`at`) — used to sort signals, then dropped
-- dwell time (`dwellMs`) — added up in the digest, left out of the prompt
+- every timestamp (`at`), which we use to sort signals and then drop
+- dwell time (`dwellMs`), added up in the digest and left out of the prompt
 - every price, and every currency
 - `imageUrl`
-- `interaction.value` and `interaction.meta` — the model is told which kinds of
+- `interaction.value` and `interaction.meta`. The model is told which kinds of
   interaction happened and how often, and no more
 
-The candidate list is trimmed on the way out: an out-of-stock product is dropped,
+The candidate list is trimmed on the way out. An out-of-stock product is dropped,
 and at most 60 products go, in the order you supplied them.
 
-`spec-cache.test.ts` walks every field of the digest and checks each one is
+`spec-cache.test.ts` walks every field of the digest and checks that each one is
 either in the cohort key or scrubbed from the cohort prompt. A field the key
 leaves out that still changes the prompt fails that test. Adding a field to the
 digest fails it too, until someone says which side the field is on.
 
 ## What the model decides, by mode
 
-What the model wrote and what is replaced before the page is served. Cohort is
+What the model wrote, and what we replace before the page is served. Cohort is
 the default.
 
 | Decision                           | Cohort, the default                     | Per-shopper                            |
@@ -276,19 +325,21 @@ the default.
 | Layout and block order             | The model                               | The model                              |
 | Headline, subheadline, copy        | The model                               | The model                              |
 | Emphasis per item                  | The model                               | The model                              |
-| Badge text                         | Dropped — written for another product   | The model                              |
+| Badge text                         | Dropped, written for another product    | The model                              |
 | Which products, and in what order  | Filled in per request, not by the model | The model, from your candidates        |
 | The reason and basis per product   | Filled in per request, not by the model | The model, checked against the signals |
 | Which bundle, of the ones you pass | Chosen per request, not by the model    | Chosen per request, not by the model   |
 
 In cohort mode the grid and carousel items are filled in per request, best pick
-first, so a component written for one shopper still fits the next. The hero is
-the exception: it keeps the product the model named, because its headline and
-body were written about that product and swapping it would leave copy about
-something else. Reconciliation drops the link and keeps the words if the product cannot be
-placed: this shopper cannot see it — out of stock, not a candidate, disliked,
-already bought, in the basket, or the one being looked at — or an earlier block
-already placed it, or the item budget ran out before the hero was reached.
+first, so a component written for one shopper still fits the next.
+
+The hero is the exception. It keeps the product the model named, because its
+headline and body were written about that product, and swapping it would leave
+copy about something else. When that product can't be placed, reconciliation
+drops the link and keeps the words. It can't be placed if this
+shopper can't see it (out of stock, not a candidate, disliked, already bought, in
+the basket, or the one being looked at), an earlier block already placed it, or
+the item budget ran out before the hero was reached.
 
 ## Any provider
 
@@ -304,26 +355,25 @@ export interface ComponentProvider {
 }
 ```
 
-`createComponentGenerator({ provider })` takes any object of that shape — a
-hosted API, a model you run yourself, a deployment inside your own tenancy, or a
+`createComponentGenerator({ provider })` takes any object of that shape: a hosted
+API, a model you run yourself, a deployment inside your own tenancy, or a
 recorded fixture. `@rudra-js/core` depends on no vendor SDK.
 `@rudra-js/anthropic` is one adapter, not a requirement, and `provider: null` is
 the default that costs nothing.
 
 An adapter takes its API key as an option, so you choose where the key comes
-from. `ANTHROPIC_API_KEY` is the name the example shop uses for its own
+from. `ANTHROPIC_API_KEY` is just the name the example shop uses for its own
 convenience. No package here reads the environment.
 
 ## The cache
 
 `cache` defaults to an in-process store. `createMemorySpecCache()` keeps an entry
-for `ttlMs` — 60,000 milliseconds by default, so one minute — and holds up to
-`maxEntries`, 10,000 by default. Once it is full, the entry read longest ago goes
-first.
+for `ttlMs`, 60,000 milliseconds by default, so one minute. It holds up to
+`maxEntries`, 10,000 by default. Once it's full, the entry read longest ago is
+the first to go.
 
 An entry holds the generated spec and `generatedAt`, the epoch milliseconds when
-the model produced it. That is the whole of it — no payload, no shopper, no
-prompt.
+the model produced it. That's the whole of it. No payload, no shopper, no prompt.
 
 The port is two methods, and an optional third:
 
@@ -335,36 +385,37 @@ export interface SpecCache {
 }
 ```
 
-Pass your own store — Redis, Memcached, whatever you already run — and it keeps
-entries on its own terms. What that store holds, and for how long, is yours to
-declare to your users, because this package does not set it. Pass
-`createNullSpecCache()` to store nothing at all.
+Pass your own store, whether that's Redis, Memcached or whatever you already run,
+and it keeps entries on its own terms. Just keep in mind that what that store
+holds, and for how long, is yours to declare to your users. This package doesn't
+set it. Pass `createNullSpecCache()` to store nothing at all.
 
 ### When a generation is wrong
 
-Pass `provider: null` and nothing new is generated; every page renders the
+Pass `provider: null` and nothing new is generated, so every page renders the
 deterministic component. Shorten `ttlMs` and a bad entry ends sooner. A store
 with `delete` can drop one entry by the `key` on its `GenerationEvent`, and the
-next request generates again. Per-shopper entries end only by TTL, because
+next request generates again. Per-shopper entries only end by TTL, because
 nothing maps a shopper to their keys.
 
 ## Watching it in production
 
-The generator never fails a render, so a provider that has been down for a
-week only shows as plainer pages. The way to know is `onEvent`: every call to
-`generate` that gets past input validation reports exactly one
-`GenerationEvent`, and these are the numbers to keep from it. A payload that
-fails `parseTrackingInput` throws instead, and reports nothing.
+The generator never fails a render, so a provider that's been down for a week
+only shows as plainer pages. The way to know is `onEvent`: every call to
+`generate` that gets past input validation reports exactly one `GenerationEvent`.
+A payload that fails `parseTrackingInput` throws instead, and reports nothing.
+
+These are the numbers worth keeping:
 
-- **Fallback share** — the share of events with `source: 'fallback'`. Alert
-  when it climbs. `degradedReason` says which way the call failed, and `error`
+- **Fallback share** — the share of events with `source: 'fallback'`. Alert when
+  it climbs. `degradedReason` tells you which way the call failed, and `error`
   carries what was thrown when the reason is `'provider-error'` or `'timeout'`.
-- **Cache hit rate** — `cache: 'hit'` over the events that have a `cache`
-  field. A store that is down now shows as `cache: 'error'`, and a slow one as
+- **Cache hit rate** — `cache: 'hit'` over the events that have a `cache` field.
+  A store that's down shows as `cache: 'error'`, and a slow one as
   `cache: 'timeout'`, rather than as a rising bill.
-- **Spend** — sum `usage` over the events where `calledModel` is true.
-  Requests that joined an in-flight generation carry the same `usage`, so
-  summing over every event counts one call many times.
+- **Spend** — sum `usage` over the events where `calledModel` is true. Requests
+  that joined an in-flight generation carry the same `usage`, so summing over
+  every event counts one call many times.
 
 ## Licence
 

package/dist/component-generator.d.ts

@@ -1,5 +1,6 @@
 import { type ComponentSpec, type DegradedReason, type SpecSource } from './component-spec.js';
 import type { ComponentProvider, TokenUsage } from './provider.js';
+import { type RankOrder } from './product-selection.js';
 import { type SpecCache } from './spec-cache.js';
 import { type TrackingInputDraft } from './tracking-input.js';
 /**
@@ -80,6 +81,14 @@ export interface ComponentGeneratorOptions {
      * 'cohort'.
      */
     generation?: 'cohort' | 'per-shopper';
+    /**
+     * How the products are ordered. 'signals' scores each candidate from this
+     * shopper's signals. 'given' keeps the order you sent, for a shop whose own
+     * ranking is better than four weights. Either way the exclusions and the
+     * stock check still apply, and each product still carries a basis
+     * reconciliation can verify. Defaults to 'signals'.
+     */
+    rank?: RankOrder;
     /** Observability. Never allowed to break a render. */
     onEvent?: (event: GenerationEvent) => void;
 }

package/dist/component-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-generator.d.ts","sourceRoot":"","sources":["../src/component-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAUnE,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACtC,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAAC;CACjE;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAG9C;CACF;AA8JD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CAuPpB"}
+{"version":3,"file":"component-generator.d.ts","sourceRoot":"","sources":["../src/component-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAOnE,OAAO,EAAkB,KAAK,SAAS,EAAoB,MAAM,wBAAwB,CAAC;AAG1F,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACtC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAAC;CACjE;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAG9C;CACF;AAgKD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CA6PpB"}

package/dist/component-generator.js

@@ -91,8 +91,8 @@ const cachedSpecSchema = z.object({
  * reaches the same set this did — it can only ever have more placed than the
  * pre-choice assumed, and never one of the set's own products.
  */
-function fitCohortSpec(spec, input, digest) {
-    const picks = selectProducts(input, digest);
+function fitCohortSpec(spec, input, digest, rank, hostReasonSkus) {
+    const picks = selectProducts(input, digest, { rank });
     // Blocks past the cap never render, so a set is not worth reserving for one.
     const blocks = spec.blocks.slice(0, MAX_BLOCKS);
     let hasBundleBlock = false;
@@ -105,25 +105,25 @@ function fitCohortSpec(spec, input, digest) {
         aboveBundle.push(block);
     }
     if (!hasBundleBlock)
-        return fitToShopper(spec, picks, digest.maxItems);
+        return fitToShopper(spec, picks, digest.maxItems, hostReasonSkus);
     // Only the heroes above the bundle block are placed when it is reached, so
     // they are all the choice may account for.
     const chosen = bundleForShopper(input, digest, placeableHeroSkus(aboveBundle, input, digest));
     if (!chosen)
-        return fitToShopper(spec, picks, digest.maxItems);
+        return fitToShopper(spec, picks, digest.maxItems, hostReasonSkus);
     const spokenFor = new Set(chosen.skus);
     for (const sku of placeableHeroSkus(blocks, input, digest))
         spokenFor.add(sku);
     const roomLeft = digest.maxItems - spokenFor.size;
     // A set is worth showing, but not at the cost of an empty grid.
     if (roomLeft <= 0)
-        return fitToShopper(spec, picks, digest.maxItems);
+        return fitToShopper(spec, picks, digest.maxItems, hostReasonSkus);
     const forGrid = [];
     for (const pick of picks) {
         if (!spokenFor.has(pick.product.sku))
             forGrid.push(pick);
     }
-    return fitToShopper(spec, forGrid, roomLeft);
+    return fitToShopper(spec, forGrid, roomLeft, hostReasonSkus);
 }
 /** Attaches the provenance the server owns. The model never supplies any of it. */
 function withProvenance(spec, provenance) {
@@ -133,6 +133,7 @@ export function createComponentGenerator(options = {}) {
     const provider = options.provider ?? null;
     const cache = options.cache ?? createMemorySpecCache();
     const generation = options.generation ?? 'cohort';
+    const rank = options.rank ?? 'signals';
     const modelTimeoutMs = options.modelTimeoutMs ?? 1_500;
     const cacheTimeoutMs = options.cacheTimeoutMs ?? 50;
     const singleFlight = createSingleFlight();
@@ -164,7 +165,7 @@ export function createComponentGenerator(options = {}) {
             ...modelCall,
             degradedReason,
         });
-        return withProvenance(buildFallbackSpec(input, digest), {
+        return withProvenance(buildFallbackSpec(input, digest, { rank }), {
             slot: digest.slot,
             source: 'fallback',
             generatedAt: finishedAt,
@@ -304,8 +305,13 @@ export function createComponentGenerator(options = {}) {
             // One place where anything is served, whichever side of the cache it came
             // from, and always against the facts of the shopper asking now.
             // A cohort spec names products chosen for whoever asked first.
-            const served = generation === 'cohort' ? fitCohortSpec(answer.spec, input, digest) : answer.spec;
-            const reconciled = reconcileSpec(served, input, digest);
+            // Only the cohort path writes a host reason into a spec, so in
+            // per-shopper mode this stays empty and every reason is screened.
+            const hostReasonSkus = new Set();
+            const served = generation === 'cohort'
+                ? fitCohortSpec(answer.spec, input, digest, rank, hostReasonSkus)
+                : answer.spec;
+            const reconciled = reconcileSpec(served, input, digest, hostReasonSkus);
             if (!reconciled.isUsable) {
                 return buildDeterministic(input, digest, startedAt, key, 'unusable-on-serve', {
                     calledModel,