@rudra-js/core 0.1.0 → 0.3.1

package/README.md

@@ -9,42 +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.
+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.
 
-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.
+## Options
 
-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
-never emits.
+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 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';
@@ -68,51 +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: 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.
+`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
 
@@ -131,34 +153,50 @@ 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.
+
 ### 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' });
 ```
 
+#### 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. 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 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                                                          |
 | -------------------- | ----- | ------------------------------------------------------------------- |
@@ -172,17 +210,212 @@ numbers rather than discovering them from a rejection.
 | `candidates`         | 200   | `candidates`                                                        |
 | `productsPerBundle`  | 5     | `bundles[].skus`, which also needs at least 2                       |
 | `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
+
+The two generation modes send different things. Cohort is the default.
+
+### Cohort mode
+
+- the surface and the slot
+- the locale
+- the segment, when you set one
+- the category being browsed (`context.currentCategory`)
+- 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
+
+### Per-shopper mode
+
+Everything above, and:
+
+- the SKU being looked at right now
+- the current search
+- whether this is a returning shopper
+- liked SKUs, and disliked SKUs
+- purchased SKUs, and what is in the basket
+- the most-viewed SKUs, each with its view count
+- recent searches
+- every category they lean towards, strongest first
+- the other kinds of interaction, each with a count
+
+### Left out of both
+
+- `user.id`
+- 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 happened and how often, and no more
+
+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 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 we replace before the page is served. Cohort is
+the default.
+
+| Decision                           | Cohort, the default                     | Per-shopper                            |
+| ---------------------------------- | --------------------------------------- | -------------------------------------- |
+| 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                              |
+| 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. 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
+
+A provider is three things:
+
+```ts
+export interface ComponentProvider {
+  /** Short identifier recorded on every generated spec, e.g. 'anthropic'. */
+  readonly name: string;
+  /** Concrete model identifier, e.g. 'claude-opus-5'. */
+  readonly model: string;
+  generate(request: ProviderRequest): Promise<ProviderResult>;
+}
+```
+
+`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 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. 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's the whole of it. No payload, no shopper, no prompt.
+
+The port is two methods, and an optional third:
+
+```ts
+export interface SpecCache {
+  get(key: string): Promise<CachedSpec | undefined>;
+  set(key: string, cached: CachedSpec): Promise<void>;
+  delete?(key: string): Promise<void>;
+}
+```
+
+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, 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 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'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` 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'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.
 
 ## 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';
 /**
@@ -50,6 +51,8 @@ export interface GenerationEvent {
     violations?: string[];
     usage?: TokenUsage;
     degradedReason?: DegradedReason;
+    error?: unknown;
+    cache?: 'hit' | 'miss' | 'error' | 'timeout';
 }
 export interface ComponentGeneratorOptions {
     /**
@@ -71,7 +74,21 @@ export interface ComponentGeneratorOptions {
      * hold the page open, which is exactly what this module exists to prevent.
      */
     cacheTimeoutMs?: number;
+    /**
+     * 'cohort' shares one generated component between shoppers who look alike and
+     * fills in each shopper's own products. 'per-shopper' generates for the
+     * individual, which is what the benchmark compares against. Defaults to
+     * '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;
 }
@@ -80,5 +97,8 @@ export interface ComponentGenerator {
     /** The deterministic component, without consulting a model or a cache. */
     generateDeterministic(input: TrackingInputDraft): ComponentSpec;
 }
+export declare class TimeoutError extends Error {
+    constructor(label: string, milliseconds: number);
+}
 export declare function createComponentGenerator(options?: ComponentGeneratorOptions): ComponentGenerator;
 //# sourceMappingURL=component-generator.d.ts.map

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;CACjC;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;IAIxB,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;AAiKD,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CA+OpB"}
+{"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

@@ -8,7 +8,7 @@ import { fitToShopper } from './fit-to-shopper.js';
 import { buildDigest, toCohortDigest } from './signal-digest.js';
 import { createMemorySpecCache, cohortCacheKey, specCacheKey, } from './spec-cache.js';
 import { parseTrackingInput, } from './tracking-input.js';
-class TimeoutError extends Error {
+export class TimeoutError extends Error {
     constructor(label, milliseconds) {
         super(`${label} exceeded ${milliseconds}ms`);
         this.name = 'TimeoutError';
@@ -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,
@@ -187,12 +188,12 @@ export function createComponentGenerator(options = {}) {
         try {
             const stored = await withinBudget('cache read', cacheTimeoutMs, () => cache.get(key));
             const parsed = cachedSpecSchema.safeParse(stored);
-            return parsed.success ? parsed.data : undefined;
+            return parsed.success ? { outcome: 'hit', entry: parsed.data } : { outcome: 'miss' };
         }
-        catch {
+        catch (error) {
             // A store that is down or slow degrades to generating, not to an error
             // page. Nothing here is worth failing a render over.
-            return undefined;
+            return { outcome: error instanceof TimeoutError ? 'timeout' : 'error' };
         }
     };
     /**
@@ -251,7 +252,8 @@ export function createComponentGenerator(options = {}) {
             const key = generation === 'cohort'
                 ? cohortCacheKey(digest, input.candidates.map((product) => product.sku), providerId)
                 : specCacheKey(digest, input.candidates.map((product) => product.sku), providerId);
-            const cached = await readCache(key);
+            const read = await readCache(key);
+            const cached = read.entry;
             let calledModel = false;
             let answer;
             // When the model produced this, not when it was served. A cached
@@ -276,11 +278,16 @@ export function createComponentGenerator(options = {}) {
                     // The request went out. Leaving `calledModel` to default here reported
                     // every failed call as no call at all, so the calls that cost money
                     // and produced nothing were the only ones missing from the count.
-                    return buildDeterministic(input, digest, startedAt, key, reason, { calledModel });
+                    return buildDeterministic(input, digest, startedAt, key, reason, {
+                        calledModel,
+                        cache: read.outcome,
+                        error,
+                    });
                 }
                 if (!call.spec) {
                     return buildDeterministic(input, digest, startedAt, key, 'invalid-generation', {
                         calledModel,
+                        cache: read.outcome,
                         ...(call.usage ? { usage: call.usage } : {}),
                     });
                 }
@@ -298,11 +305,17 @@ 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,
+                    cache: read.outcome,
                     violations: reconciled.violations,
                     ...(answer.usage ? { usage: answer.usage } : {}),
                 });
@@ -314,6 +327,7 @@ export function createComponentGenerator(options = {}) {
                 source,
                 elapsedMs: finishedAt - startedAt,
                 calledModel,
+                cache: read.outcome,
                 violations: reconciled.violations,
                 ...(answer.usage ? { usage: answer.usage } : {}),
             });