@rudra-js/core 0.8.3 → 0.9.1

package/README.md

@@ -15,12 +15,13 @@ You give this package one page view:
 - the page they're on
 - the products you're willing to show
 
-It gives back a spec: data that describes the recommendations on that page. Your
-model writes it, or core builds it without one. Either way, it's checked against
-those products. There's no React in this package. `@rudra-js/react` turns the
-spec into markup.
+You will get back a spec, which is just data to describe the recommendations on
+that page. This can be written by your model or can be built by core without a
+model. Either way, it's checked against those products. There's no React in this
+package: the job of `@rudra-js/react` is to turn the spec into markup.
 
-The guides and the API reference are at [rudrajs.com](https://rudrajs.com).
+You can find the guides and the API reference at
+[rudrajs.com](https://rudrajs.com).
 
 ## Install
 
@@ -28,75 +29,80 @@ The guides and the API reference are at [rudrajs.com](https://rudrajs.com).
 npm install @rudra-js/core@latest @rudra-js/attested@latest
 ```
 
-Run the same command in a new app, in an app that already uses rudra-js, and to
-upgrade.
+You can run this command in a new app or in an app that already uses rudra-js.
+It's also how to upgrade.
 
-If your app also has `@rudra-js/react` or `@rudra-js/anthropic`, add them to the
-command with `@latest`. Each one's peer range on core covers only its own minor
-release. Leave one behind and npm only warns, but the next `npm install` or
-`npm ci` fails with `ERESOLVE`.
+If your app also has `@rudra-js/react` or `@rudra-js/anthropic`, you need to add
+them to the command with `@latest`. For each of these packages, the peer range
+on core covers only its own minor release. If you leave one behind, npm will
+just warn you, but the next `npm install` or `npm ci` will fail with `ERESOLVE`.
 
-If your app has `@rudra-js/a2ui`, use the install line in that package's README
-instead. It also names the two A2UI packages.
+If your app has `@rudra-js/a2ui`, you need to use the install line in the README
+of that package instead. That line also names the two A2UI packages.
 
-Keep `@latest` on every name. For a bare name, npm stays inside the range your
-`package.json` already has, so an app on an older core never leaves the minor
-release it's on.
+Be sure to keep `@latest` on all the names. For a bare name, npm will stay
+inside the range your `package.json` already has. An app on an older core will
+then never leave the minor release it's on.
 
-`zod` is a dependency, so you don't need to install it yourself. The public API
-of this package _is_ zod schemas. An app on any zod 4 shares one copy of zod
-with it.
+You don't need to install `zod` yourself, because it's a dependency of this
+package. The public API of this package _is_ zod schemas. If your zod 4 fits
+this package's `zod` range, your app will share a single copy of zod with this
+package. If your app's zod is below that range, it will get a second copy.
 
-An app on zod 3 gets its own copy next to ours, and the two don't mix. Build on
-the exported schemas with their own methods (`productSchema.array()`), not with
-your zod's (`z.array(productSchema)`). Read `error.issues` instead of checking
+Apps on zod 3 will get their own copy next to ours, but the two copies don't
+mix. Build on the exported schemas with their own methods
+(`productSchema.array()`) instead of the methods of your zod
+(`z.array(productSchema)`). Read `error.issues` instead of checking
 `instanceof ZodError`.
 
 `@rudra-js/anthropic` uses its own zod to write the tool schema sent to the
-model, so the schema's wording shifts a little between zod releases. Before zod
-4.5, a nullable field is written as `anyOf` instead of a type array. Both mean
-the same thing.
-
-`@rudra-js/attested` is a peer dependency. None of its types appear in this
-package's public API, and you never have to import it. It's a peer so your app
-has exactly one copy of its phrase list. If your app pins its own version, npm
-stops with an `ERESOLVE` you can see and fix. If you pin nothing, npm installs
-one copy at the top of the tree. One tag publishes every `@rudra-js` package to
-npm at the same version, so these ranges always move together.
+model. Because of this, the wording of the schema will shift a little between
+zod releases. Before zod 4.5, a nullable field will be written as `anyOf`
+instead of a type array, but both of these mean the same thing.
+
+`@rudra-js/attested` is a peer dependency to make sure your app has exactly one
+copy of its phrase list. None of its types appear in the public API of this
+package and you never have to import it. If your app pins its own version, npm
+will stop with an `ERESOLVE` you can see and fix. If you pin nothing, npm will
+install a single copy at the top of the tree. All `@rudra-js` packages are
+published to npm by a single tag at the same version. That's why these ranges
+will always move together.
 
 ## Running without a model
 
-`createComponentGenerator` takes a `provider`. Leave it out, or pass `null`, and
-nothing calls a model and nothing gets billed:
+`createComponentGenerator` takes a `provider`. If you leave this out or pass
+`null`, no model will be called and nothing will be billed:
 
 ```ts
 const generator = createComponentGenerator({ provider: null });
 const spec = await generator.generate(input);
 ```
 
-This is a supported setting. The benchmark compares the models against it. It's
-the right setting until you've picked a provider. `generate` returns a promise
-either way, so your code keeps its shape when you add one.
+This is a supported setting. It's what the benchmark compares the models
+against. It's also the right setting to use until you've picked a provider.
+`generate` returns a promise either way, to let your code keep its shape when
+you add one.
 
-Without a model, core builds the spec itself. The rest of this README calls that
-spec the fallback. It has exactly one **grid** block, with a headline from a
-fixed set of four. It has no blocks at all when there's nothing left to show.
-That happens when no candidate is in stock, and also when every candidate is
-ruled out for this shopper.
+Without a model, core will build the spec itself. In the rest of this README
+that spec is called the fallback. It has exactly one **grid** block with a
+headline from a fixed set of four. If there's nothing left to show, it will have
+no blocks at all. This will happen if no candidate is in stock, and also if all
+of the candidates are ruled out for this shopper.
 
-The other block kinds (hero, carousel, banner, copy, bundle) only ever come from
-a model. So if you're wiring up bundles and none of them appear, that's why. It
-isn't your catalog.
+All the other block kinds (hero, carousel, banner, copy, bundle) only ever come
+from a model. If you're wiring up bundles and none of them appear, this is why.
+It isn't your catalog.
 
-To render a spec you wrote yourself, still without a model, pass
-`createFixedSpecProvider(spec)` as the provider. It answers every request with
-that spec. Your spec goes through the same checks as a model's, so it needs a
-headline that passes the [claim check](#what-the-host-must-supply) and at least
-one product on show. Otherwise you get the fallback.
+To render a spec you wrote yourself, still without a model, you can pass
+`createFixedSpecProvider(spec)` as the provider. This will answer all requests
+with that spec. Your spec will also go through the checks for a model's spec.
+This means it will need a headline that passes the
+[claim check](#what-the-host-must-supply) and also at least one product on show.
+Otherwise you will get the fallback.
 
 ## Options
 
-Everything `createComponentGenerator` takes, and what you get if you leave it
+All the options of `createComponentGenerator` and what you get if you leave them
 out.
 
 | Option           | What it does                                                                                            | Default                   |
@@ -112,8 +118,8 @@ out.
 ## `tracking-input`
 
 This is the boundary between your app and rudra-js. You own your tracking
-pipeline and pass one JSON object per render. rudra-js collects nothing and
-stores nothing. It doesn't aggregate anything either.
+pipeline and you just pass in a single JSON object per render. rudra-js collects
+nothing and stores nothing. It doesn't aggregate anything either.
 
 ```ts
 import { parseTrackingInput } from '@rudra-js/core';
@@ -137,33 +143,34 @@ const input = parseTrackingInput({
 });
 ```
 
-`parseTrackingInput` throws a `ZodError`. If you'd rather not catch,
-`safeParseTrackingInput` returns a `TrackingInputResult` instead. Then you can
-read `result.error.issues` without importing zod yourself.
+`parseTrackingInput` throws a `ZodError`. If you'd rather not catch it, you can
+use `safeParseTrackingInput` to get a `TrackingInputResult` instead. You will
+then be able to 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. Every signal list
-defaults to `[]`, so you don't need a special case for it.
+Any payload with no `signals` block is a first-time visitor. All of the signal
+lists will default to `[]`. You don't need a special case for it.
 
 ### What the host must supply
 
-Send `user.id`, `context.surface` and at least one entry in `candidates`. SKUs
-must be unique.
+You need to send `user.id`, `context.surface` and at least one entry in
+`candidates`. All SKUs must be unique.
 
-`candidates` sets which products can reach the page. Core looks up every SKU the
-model writes in that list. A SKU that isn't on it is dropped before anything
-renders.
+`candidates` sets which products can reach the page. Core looks up all the SKUs
+the model writes in that list. Any SKU that isn't in the list will be dropped
+before anything renders.
 
-`bundles` is optional. These are the sets you sell together. Each one has your
-own price for the set and the currency that price is in. It can also have your
-own name for the set, its `label`. Every product in a set has to be a candidate
-as well. Bundle ids must be unique, and one set must not name the same product
+`bundles` is optional. These are the sets you sell together. Each of these has
+your own price for the set and the currency of that price. It can also have your
+own name for the set in its `label`. All the products in a set have to be
+candidates as well. Bundle ids have to be unique and a set can't name a product
 twice.
 
-A set is placed whole, so one check works differently. A set may hold something
-the shopper already bought or has in the basket. A grid or a carousel would drop
-that product. The whole set is still blocked when any member is:
+Because a set is placed whole, one of the checks works differently. A set may
+hold something the shopper has already bought or has in the basket, even though
+a grid or a carousel would drop that product. But the whole set will be blocked
+if any member is:
 
 - disliked by the shopper
 - out of stock
@@ -171,23 +178,24 @@ that product. The whole set is still blocked when any member is:
 - the product being looked at right now
 
 That last rule has a cost. A "frequently bought together, including this item"
-set names the product whose page it sits on, so it's refused on exactly the page
-you wrote it for. Leave that item out and sell its companions as the set. That
-rejection goes away, and the other checks still apply.
+set will name the product of the page it sits on. It's then refused on exactly
+the page you wrote it for. To get around this, you can leave that item out and
+sell its companions as the set. That rejection will go away, but the other
+checks will still apply.
 
-When a bundle block is the only block the model asked for, refusing the set
-leaves nothing to render. Then the fallback takes over.
+If a bundle block is the only block the model asked for, refusing the set will
+leave nothing to render. Then the fallback will take over.
 
-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. Core picks which set when the page
-is served. It bases the choice on what the shopper has in their basket, has
-looked at, or is browsing right now.
+The model _never_ picks a set and is never told a price. All it can do is ask
+for a bundle block and write the words around it. Core picks which set to use as
+the page is served, based on the shopper's basket, the products they've looked
+at or what they're browsing right now.
 
-The prompt tells the model to write about the offer, not the products in it. It
-also tells the model never to say the set saves money, or by how much. Your
-`label`, when you pass one, renders ahead of the model's words.
+The prompt tells the model to write about the offer and not the products in it.
+It also tells the model never to say the set saves money, or by how much. If you
+pass a `label`, this will render ahead of the model's words.
 
-Core reads every word the model writes for claims:
+Core reads all of the words the model writes, to look for claims:
 
 - the headline and the subheadline
 - a hero
@@ -197,69 +205,74 @@ Core reads every word the model writes for claims:
 - the reason under a product
 - 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.
+Text you supplied is never read this way. All of these are your words: a product
+title, a category and a bundle `label`.
 
-Core drops text that makes a claim it can't check. This README calls that the
-claim check. It runs in three passes:
+Core drops any text that makes a claim it can't check. This README calls that
+the claim check. There are three passes to it:
 
-1. The first looks for money, a customer score, a delivery date and a count of
-   what's left.
-2. The second asks whether every numeral in the sentence is one you supplied.
-3. The third is `@rudra-js/attested`'s phrase list. It catches claims with no
-   number in them to check, like "top pick" and "customer favourite".
+1. In the first pass, core looks for money, a customer score, a delivery date
+   and a count of what's left.
+2. In the second pass, core asks whether all the numerals in the sentence are
+   ones you supplied.
+3. In the third pass, core uses the phrase list of `@rudra-js/attested`. This
+   catches claims with no number in them to check, like "top pick" and
+   "customer favourite".
 
-For example, the second pass keeps "a comfort rating of -5C" only when a `5`
-turns up in a `tag` or a `category` name you sent. The pass compares the number,
-not the string, so a tag reading `5-pocket` keeps it as surely as one reading
-`-5C comfort`.
+For example, the second pass will keep "a comfort rating of -5C" only if a `5`
+turns up in a `tag` or a `category` name you sent. This pass compares the number
+and not the string. A tag reading `5-pocket` will keep it just as surely as a
+tag reading `-5C comfort`.
 
-Tags and category names count because they're the strings core hands the model
-and lets it repeat. The model is also shown each product's `title` and `rating`.
-Neither one backs a number, because the prompt tells it never to restate either.
-Put your product's figures in `tags` and the model can quote them. Leave them
-out, and any figure the model writes about them is made up, so it's dropped.
+Tags and category names count because these are the strings core hands to the
+model and lets it repeat. The model is also shown the `title` and `rating` of
+each product, but neither of these can back a number, because the prompt tells
+the model never to restate either. If you put your product's figures in `tags`,
+these can be quoted by the model. If you leave these out, any figure the model
+writes about them is made up and will be dropped.
 
 Which strings count, exactly:
 
-- Only candidates the model was shown. A product that's out of stock, or past
-  the 60 core sends, is one the model never saw. Its tags back nothing.
-- Not the `currentCategory` on the request. It's a string from this request, not
-  a row of your catalog, and plenty of sites pass a URL segment straight into
-  it.
-- A `reason` or a `badge` sits under a named product, so it's read against that
-  product's own tags and category. Every other field is read against all the
-  candidates' tags and categories, pooled.
-
-Two things to know about the second pass. Pooled means pooled: one product's
-`40 litre` tag backs "take 40 off" written in a headline about another. And
-nothing in the pass knows which quantity a tag was about, so a tag holding a
-weight backs a price with the same digits in it. The pass proves the digits came
-from you. It doesn't prove the sentence is true.
-
-The first and third passes are word lists. A word list can miss a claim, so it
-isn't a guarantee the way checking a price against your catalog is. The second
-pass proves something narrower than it sounds: every digit was one of yours. A
-number written as a word isn't a number to it, so it can't see "four and a half
-stars" as a rating. A ½, or the K in "10K", is a numeral it can't read. It drops
-those instead of letting them through.
-
-The model isn't told any of this. The prompt bans prices, ratings, discounts,
-delivery dates and stock levels. It says nothing about digits. So the model
-can't tell `3-season`, a tag you sent and fine to use, from `2 litres`, which
-isn't. However much good text the check drops on your catalog, nothing in the
-prompt brings that down.
-
-Some fields can't be null, like a headline or a banner's text. When the check
-drops text from one of those, it empties the field instead. The block then
-drops, as any block with no text does. An empty page headline makes the whole
-generation unusable.
-
-That's the costly case. Say the model writes "Our 3 favourites for wet weather"
-and no candidate carries a 3. The headline empties, so the generation is
-unusable and the fallback renders. You paid for a model call and threw it away.
-In cohort mode the spec is cached before it's checked, so every cache hit runs
-the same check and gets the same fallback until the entry expires.
+- Only candidates the model was shown. Any product that's out of stock or past
+  the 60 core sends is a product the model never saw. Its tags back nothing.
+- Not the `currentCategory` on the request. That's a string from this request
+  and not a row of your catalog. There are also plenty of sites that pass a URL
+  segment straight into it.
+- A `reason` or a `badge` will sit under a named product. It's read against the
+  tags and category of that product. All other fields are read against the tags
+  and categories of all the candidates, pooled.
+
+There are two things to know about the second pass. Pooled means pooled: a
+`40 litre` tag on a product will back "take 40 off" in a headline about another
+product. And nothing in this pass can know which quantity a tag was about.
+That's why a tag holding a weight will back a price that has those digits in it.
+This pass will prove the digits came from you, but it won't prove the sentence
+is true.
+
+In the first and third passes, core uses word lists. Word lists can miss a
+claim. They aren't a guarantee in the way that checking a price against your
+catalog is. For the second pass, the proof is narrower than it sounds: all of
+the digits were yours. To this pass, a number written as a word isn't a number.
+It can't see "four and a half stars" as a rating. It also can't read some
+numerals, like a ½ or the K in "10K". Those will be dropped, not let through.
+
+None of this is told to the model. In the prompt there's a ban on prices,
+ratings, discounts, delivery dates and stock levels, but nothing about digits.
+The model has no way to tell `3-season` (a tag you sent and fine to use) from
+`2 litres` (which isn't). However much good text the check drops on your
+catalog, nothing in the prompt can bring that down.
+
+Some fields can't be null, like a headline or the text of a banner. If the check
+drops text from one of these, it will empty the field instead. Banner and copy
+blocks will then be dropped. For a hero, this will only happen if it has no
+product either. An empty page headline makes the whole generation unusable.
+
+That's the costly case. For example, the model might write
+"Our 3 favourites for wet weather" when no candidate carries a 3. This headline
+will be emptied. That makes the generation unusable and the fallback will
+render. You will have paid for a model call just to throw it away. In cohort
+mode the spec is cached before it's checked. This means all cache hits will
+repeat the check and get the same fallback until the entry expires.
 
 ### Defaults
 
@@ -278,14 +291,14 @@ the same check and gets the same fallback until the entry expires.
 | `mostViewed[].views`       | `1`                 |
 | `lastPurchased[].quantity` | `1`                 |
 
-`context.locale` has to be one language tag, such as `en-US`. Not a list, and
-not an `Accept-Language` header.
+`context.locale` has to be a single language tag, such as `en-US`. It can't be a
+list or an `Accept-Language` header.
 
 ### Cohorts
 
-By default, shoppers who look alike share one generated spec. Each shopper's own
-products are filled in per request. A group of look-alike shoppers is a cohort.
-A cohort is set by:
+By default, shoppers who look alike will share a single generated spec and the
+products for each shopper are filled in per request. A group of look-alike
+shoppers is called a cohort. It's set by:
 
 - the shopper's segment
 - the surface and the slot
@@ -295,53 +308,57 @@ A cohort is set by:
 - the category being browsed
 - the category they lean towards
 
-Only two of these come from the shopper's own data: whether they have any
-history, and the category they lean towards. Who they are, what they searched
-for and the products they liked or viewed stay out. That's what lets many page
-views reuse one model call.
-
-The candidate list is part of the cohort too, because 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. If you pick candidates per shopper, you'll
-get smaller cohorts, because each prompt really is personal.
-
-The cache key for a cohort holds the _set_ of candidate SKUs. It ignores the
-order you sent them in, which ones were in stock, and where the 60-product cut
-fell. So two requests with the same SKUs in a different order share one spec,
-and both get the one generated first. If your ranking is personal and you order
-your candidates per shopper, the products the copy talks about won't be the ones
-you put at the top.
-
-Prices, titles and stock are always read from your catalog at render time, so a
-stale one never shows. A product that sold out is dropped as the page is served.
-Any sentence the model wrote about it stays.
+Only two of these come from the shopper's data: whether they have any history
+and the category they lean towards. Who they are, their searches and the
+products they liked or viewed are all left out. This lets many page views reuse
+a single model call.
+
+Candidate lists are also part of the cohort, because the model is shown those
+products and writes about them. In most shops the candidates come from the page
+and will be shared by all the people looking at it. If you pick candidates per
+shopper, you'll get smaller cohorts, because each prompt really is personal.
+
+For a cohort, the cache key holds the _set_ of candidate SKUs. This key will
+ignore the order they were sent in, which of them were in stock and where the
+60-product cut fell. Two requests with the same SKUs in a different order are
+going to share a spec. Both of them will get the first spec to be generated. If
+your ranking is personal and you order your candidates per shopper, the products
+the copy talks about won't be the ones you put at the top.
+
+Prices, titles and stock will always be read from your catalog at render time.
+This is to make sure a stale value never shows in those fields. If a product
+sold out, it's dropped as the page is served, but any sentence the model wrote
+about it will stay. You can also end up with copy written from an old title,
+rating or tag, because the cache key holds SKUs and none of those fields.
 
 #### Who can create a cohort
 
-Every cohort field above is one you supply, and each distinct value makes a
-cohort of its own. That's a fresh model call, and a slot in the cache. If a
-visitor can choose one of these values, a visitor can choose how many calls you
-pay for. These are the three that go wrong:
+You supply all of the cohort fields above and each distinct value will make a
+cohort of its own. This will cost you a fresh model call and also a slot in the
+cache. If a visitor can choose any of these values, they can choose how many
+calls you pay for. These are the three that go wrong:
 
 - a `locale` copied straight out of `Accept-Language`
 - a `currentCategory` read off a URL slug
 - a `segment` built from a query parameter
 
-The built-in cache holds 10,000 entries, so once it's full, made-up values push
-out the cohorts your real shoppers were being served from.
+There's room for 10,000 entries in the built-in cache. Once it's full, made-up
+values will push out the cohorts your real shoppers were being served from.
 
-Draw those fields from sets you control:
+You need to draw those fields from sets you control:
 
 - your own locale list
 - your own category ids
 - your own segment labels
 
-Nothing leaks either way, because a cohort prompt carries no shopper text at
-all. The cost is the bill, plus a model round trip on a page that was being
-served from cache.
+A cohort prompt leaves out the shopper's searches and signal lists, but those
+three fields go in as written. If a visitor can set one, what they send reaches
+your provider. The other cost will be the bill, plus a model round trip on a
+page that was being served from cache.
 
-Pass `generation: 'per-shopper'` to generate for each shopper instead. The model
-then picks the products too, and every shopper costs their own call.
+To generate for each shopper instead, you can pass `generation: 'per-shopper'`.
+The model will then pick the products too and each shopper will cost a call of
+their own.
 
 ```ts
 createComponentGenerator({ provider, generation: 'per-shopper' });
@@ -349,9 +366,9 @@ createComponentGenerator({ provider, generation: 'per-shopper' });
 
 #### What you put in `segment`
 
-`segment` goes to the model exactly as you wrote it, in both modes. The schema
-takes any string up to 128 characters. Stick to plain merchandising labels like
-`lapsed`, `high-value`, `trial` or `wholesale`. Keep out anything that says
+In both modes, `segment` goes to the model exactly as you wrote it. The schema
+takes any string of up to 128 characters. Stick to plain merchandising labels
+like `lapsed`, `high-value`, `trial` or `wholesale`. Keep out anything that says
 something protected about a person:
 
 - health
@@ -363,14 +380,15 @@ something protected about a person:
 - 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 belongs to them. The label you give them is your choice.
+This also applies to `recentSearches`, `context.searchQuery` and
+`interaction.type` in per-shopper mode. These three are shopper text and will be
+sent as written. Anything a shopper types belongs to them, but the label you
+give them is your choice.
 
 ### Limits
 
-Every free-text field and every array has a cap, because your strings end up
-inside a model prompt and you pay for a model per token. The caps live in
+All free-text fields and all arrays have a cap, because your strings end up
+inside a model prompt and you pay for a model per token. These caps are in
 `FIELD_LIMITS`, which is exported. Validate against the same numbers instead of
 finding them out from a rejection.
 
@@ -390,28 +408,32 @@ finding them out from a rejection.
 | `maxItems`           | 12    | `context.maxItems`, which also needs at least 1                     |
 | `reason`             | 120   | `candidates[].reason`, your own phrase for a product                |
 
-Each cap bounds one field on its own. Together they aren't a budget for the
-whole prompt. Fitting a payload into a context window is the digest's job. The
-digest is core's short summary of the shopper and the page, which goes into the
-prompt. It trims instead of throwing.
+Each cap bounds a single field on its own. Together they aren't a budget for the
+whole prompt. Core doesn't count tokens either. The digest, the short summary of
+the shopper and the page, trims signals instead of throwing. The prompt will
+also be limited to 60 in-stock candidates. With long titles and tag lists, those
+60 products can still be too much for a small model.
 
 ### Unknown fields are rejected
 
-Every fixed-shape object is a `strictObject`. Misspell `recentSearches` and you
-get an error, instead of a shopper who quietly looks like a first-time visitor.
-`interaction.meta` is the one open shape. It takes any key, except the keys that
-would change a prototype instead of the object.
+Any fixed-shape object is a `strictObject`. If you misspell `recentSearches`,
+you'll get an error instead of a shopper who looks like a first-time visitor
+with no sign of why. `interaction.meta` is the only open shape. It takes any
+key, except the keys that would change a prototype instead of the object.
 
 ## Bringing your own ranking
 
-By default core orders the products for you. It scores each candidate against
-the shopper's signals. You might already have a recommender you trust:
+By default core orders the products for you in cohort mode and in the fallback,
+by scoring each candidate against the shopper's signals. You might already have
+a recommender you trust:
 
 - bought-together data
-- an engine trained on your own orders
+- an engine trained on your orders
 - a merchandiser's hand-picked row
 
-Pass `rank: 'given'` and the order you sent is the order that renders.
+If you pass `rank: 'given'`, the order you sent will be kept for grids and
+carousels in cohort mode and in the fallback. The hero's product will still be
+picked by the model. In per-shopper mode the model will pick the order too.
 
 ```ts
 const generator = createComponentGenerator({ provider, rank: 'given' });
@@ -424,30 +446,30 @@ shouldn't be shown:
 - already bought
 - in the basket
 - disliked
-- the product they're looking at right now
+- being looked at right now
 
-Core reads these from the payload you sent, not from the shorter history the
-model was shown. So a shopper with a long order history is covered too. Every
-product still carries a basis, a code like `most_viewed` that says why it's
-shown, and core checks it against the shopper's real signals. Everything the
-model writes still goes through the claim check.
+These checks use the payload you sent and not a trimmed copy of it. This means
+a shopper with a long order history is covered too. Each product will still have
+a basis: this is a code like `most_viewed` to say why
+it's shown. Core checks this basis against the shopper's real signals. All of
+the model's text will still be read by the claim check.
 
-There are six bases, and two of them prove less than their names suggest:
+There are six bases, but two of them prove less than their names suggest:
 
 - `most_viewed` is checked against the SKUs they viewed.
 - `similar_to_current` is checked against the category being browsed.
-- `liked_category` is checked against the categories they bought, liked, carted
-  or viewed in. Standing on a category page isn't one of those.
+- `liked_category` is checked against the categories of products they've bought,
+  liked, carted or viewed. Just standing on a category page doesn't count.
 - `popular` claims nothing.
 - `complements_cart` checks only that the basket isn't empty.
 - `complements_purchase` checks only that the order history isn't empty.
 
-The two `complements_` bases are the weak ones, because nothing here can know
-that one product goes with another. A basis that fails takes the sentence and
-the badge stating it with it.
+Of these, the two `complements_` bases are the weak ones, because nothing here
+can know that a product goes with another. If a basis fails, the sentence and
+the badge stating it are dropped too.
 
-Each candidate can carry its own `reason`, the phrase shown under the product.
-Use it when your ranking knows something the signals don't:
+Candidates can also carry a `reason` (the phrase shown under the product). You
+can use this if your ranking knows something the signals don't:
 
 ```ts
 candidates: [
@@ -461,69 +483,73 @@ candidates: [
 ];
 ```
 
-A reason you supply is your own words, like the title, so it renders as written
-and skips the claim check. 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. Every one of them goes through the claim check, even one
-that reads the same as yours.
+Any reason you supply is in your own words, like the title. It renders as
+written and skips the claim check. But that only applies where this request
+actually used it (the default `cohort` mode). In `per-shopper` mode the model
+writes the reasons itself. All of these will be read by the claim check, even if
+a reason reads the same as yours.
 
-Without a reason of your own, core states the basis for you from the shopper's
-signals, like "More in Backpacks" or "Goes with what is in your cart". Those are
-core's words, not the model's, so in `cohort` mode they skip the claim check
-too.
+You don't have to supply a reason: core will state the basis for you from the
+shopper's signals, like "More in Backpacks" or "Goes with what is in your cart".
+These are core's words and not the model's. In `cohort` mode they also skip the
+claim check.
 
 ## What the model sees
 
-The two generation modes send different things. Cohort is the default.
+There are two generation modes and they send different things. Cohort is the
+default.
 
 ### Cohort mode
 
 - the surface and the slot
 - the locale
-- the segment, when you set one
+- the segment, if set
 - the category being browsed (`context.currentCategory`)
-- the name of the category the shopper leans towards most, without its score
-- whether this shopper has no history at all, meaning no likes, dislikes,
-  purchases, basket items or views. Searches and other interactions don't count
-- how many products the spec may place (`context.maxItems`)
-- the candidate list: one line per product, with its SKU, title, category,
-  rating and tags
+- the name of the category the shopper leans towards most, but not its score
+- whether this shopper has no history at all (no likes, dislikes, purchases,
+  basket items or views). Searches and other interactions don't count
+- how many products the spec can place (`context.maxItems`)
+- the candidate list: a line per product with its SKU, title, category, rating
+  and tags
 
 ### Per-shopper mode
 
-Everything above, and:
+All of the above and also:
 
 - 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
+- purchased SKUs and what is in the basket
+- most-viewed SKUs, each with its view count
 - recent searches
 - up to six categories they lean towards, strongest first
-- the other kinds of interaction, each with a count
+- other kinds of interaction, each with a count
 
 ### Left out of both
 
 - `user.id`
-- every timestamp (`at`). Core uses them to sort signals, then drops them
+- all timestamps (`at`). Core uses these to sort signals and then they're
+  dropped
 - dwell time (`dwellMs`). It's 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
+  interaction happened and how often, but no more
 
-The candidate list is trimmed before it's sent. Out-of-stock products are
-dropped, and at most 60 products go, in the order you supplied them.
+The candidate list will be trimmed before it's sent. Out-of-stock products will
+be dropped and no more than 60 products will go, in the order you supplied.
 
-`spec-cache.test.ts` walks every field of the digest. It checks that each one is
-either in the cache key or removed from the cohort prompt. A field the key
-leaves out that still changes the prompt fails that test. A new field added to
-the digest fails it too, until someone says which side the field is on.
+`spec-cache.test.ts` walks all the fields of the digest, to check that each
+field is either in the cache key or removed from the cohort prompt. If a field
+is left out of the key but still changes the prompt, that test will fail. It
+will also fail for a new field added to the digest, until someone says which
+side the field is on.
 
 ## What the model decides, by mode
 
-What the model wrote, and what core replaces before the page is served.
+Here you can see what the model wrote and what will be replaced by core before
+the page is served.
 
 | Decision                           | Cohort, the default                     | Per-shopper                            |
 | ---------------------------------- | --------------------------------------- | -------------------------------------- |
@@ -535,21 +561,21 @@ What the model wrote, and what core replaces before the page is served.
 | 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 spec written for one shopper still fits the next.
+In cohort mode the grid and carousel items are filled in per request (best pick
+first). That way, a spec written for one shopper will also fit the next.
 
-The hero is the exception. It keeps the product the model named, because its
-headline and body were written about that product. When that product can't be
-placed, core drops the link and keeps the words. It can't be placed when:
+But the hero is the exception. It keeps the product the model named, because its
+headline and body were written about that product. If this product can't be
+placed, core will drop the link and keep the words. It can't be placed if:
 
 - this shopper can't see it: it's out of stock, not a candidate, disliked,
-  already bought, in the basket, or the one being looked at
+  already bought, in the basket or being looked at
 - an earlier block already placed it
-- the item budget ran out before the hero was reached
+- the item budget had run out by the time the hero was reached
 
 ## Any provider
 
-A provider is three things:
+There are three things to a provider:
 
 ```ts
 export interface ComponentProvider {
@@ -561,36 +587,36 @@ export interface ComponentProvider {
 }
 ```
 
-`createComponentGenerator({ provider })` takes any object of that shape. That
-can be 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, and you don't need it.
+`createComponentGenerator({ provider })` takes any object of that shape. This
+might be a hosted API, a model you run yourself, a deployment inside your
+tenancy or a recorded fixture. `@rudra-js/core` depends on no vendor SDK.
+`@rudra-js/anthropic` is just one adapter and you don't have to use it.
 
-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. No package
-here reads the environment.
+An adapter takes its API key as an option. You can then choose where the key
+comes from. `ANTHROPIC_API_KEY` is just the name the example shop uses. No
+package here reads the environment.
 
 ## The cache
 
 By default `cache` is an in-process store. `createMemorySpecCache()` keeps an
-entry for `ttlMs`, which defaults to 60,000 milliseconds, so one minute. It
-holds up to `maxEntries`, which defaults to 10,000. Once it's full, the entry
-read longest ago is the first to go.
+entry for `ttlMs`. This defaults to 60,000 milliseconds (one minute). This store
+will hold up to `maxEntries`, which defaults to 10,000. Once it's full, the
+entry read longest ago will be the first to go.
 
 An entry holds the generated spec, as the model returned it before any checks.
-It also holds `generatedAt`, the epoch milliseconds when the model produced it.
-It holds no payload and no prompt.
+It also holds `generatedAt` (the epoch milliseconds of when the model produced
+the spec). It doesn't hold a payload or a prompt.
 
-In cohort mode an entry holds no shopper id, and everyone in the cohort shares
-it. The exception is an entry whose segment or candidates were picked for one
-shopper. In per-shopper mode the model wrote the entry from that shopper's
-signals. So its text can repeat them, a search term for instance, and the entry
-is personal data until it's gone.
+In cohort mode an entry holds no shopper id and it's shared by all the shoppers
+in the cohort. But there's an exception if the segment or candidates were picked
+for one shopper. In per-shopper mode the model wrote the entry from the signals
+of that shopper. Its text can then repeat them (a search term, for instance)
+and the entry will be personal data until it's gone.
 
-Expiry is checked when an entry is read, so an expired entry stays in memory
-until it's read again or pushed out by a newer one.
+Expiry is checked when an entry is read. An expired entry will stay in memory
+until it's read again or pushed out by a newer entry.
 
-The cache interface is two methods, and an optional third:
+The cache interface is two methods and an optional third:
 
 ```ts
 export interface SpecCache {
@@ -600,111 +626,118 @@ export interface SpecCache {
 }
 ```
 
-Pass your own store, whether that's Redis, Memcached or 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. This package doesn't set it. Pass
-`createNullSpecCache()` to store nothing at all.
+You can also pass a store of your own (Redis, Memcached or whatever you already
+run) and it will keep entries on its own terms. It's up to you to declare to
+your users what that store holds and for how long. That's not set by this
+package. To store nothing at all, you can pass `createNullSpecCache()`.
 
 ### When a generation is wrong
 
-- Pass `provider: null` and nothing new is generated, so every page renders the
-  fallback.
-- Shorten `ttlMs` and a bad entry ends sooner.
-- If your store has `delete`, drop one entry by the `key` on its
-  `GenerationEvent`. The next request generates again.
+- If you pass `provider: null`, nothing new will be generated and all pages will
+  render the fallback.
+- If you shorten `ttlMs`, a bad entry will end sooner.
+- If your store has `delete`, you can drop an entry by the `key` on its
+  `GenerationEvent`. The next request will then generate again.
 
-Per-shopper entries only end when they expire, because nothing maps a shopper to
-their keys.
+Core can't drop all the entries of a shopper for you, because nothing maps a
+shopper to their keys. Per-shopper entries will end when they expire or when
+newer entries push them out. You can also delete an entry by a `key` you kept.
 
 ## Watching it in production
 
-The generator never fails a render, so a provider that's been down for a week
-only shows up as plainer pages. Watch `onEvent` to find out. Every call to
-`generate` that gets past input validation reports exactly one
-`GenerationEvent`. A payload that fails `parseTrackingInput` throws instead, and
-reports nothing.
+The generator never fails a render. If a provider has been down for a week, this
+will only show up as plainer pages. To find out, you need to watch `onEvent`.
+Each call to `generate` that gets past input validation reports exactly one
+`GenerationEvent`. If a payload fails `parseTrackingInput`, it will throw
+instead and report nothing.
 
-Keep these numbers:
+These are the numbers to keep:
 
-- **Fallback share.** The share of events with `source: 'fallback'`. Alert when
-  it climbs. `degradedReason` tells you which way the call failed. When the
-  reason is `'provider-error'` or `'timeout'`, `error` carries what was thrown.
+- **Fallback share.** This is the share of events with `source: 'fallback'`. Be
+  sure to alert if it climbs. `degradedReason` will tell you which way the call
+  failed. If the reason is `'provider-error'` or `'timeout'`, `error` has the
+  value that was thrown.
 - **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'`. So a broken store shows up here, not only as a rising
-  bill.
-- **Spend.** Sum `usage` over the events where `calledModel` is true. Requests
-  that joined a generation already in flight carry the same `usage`, so summing
-  over every event counts one call many times. Some calls the model answered are
-  turned down by the adapter: a `max_tokens` stop, a refusal, no tool call, or a
-  reply that doesn't fit the schema. Those were billed too. They arrive as a
-  `'provider-error'` with no `usage`, so this sum is lower than your bill.
+  A store that's down will show as `cache: 'error'` and a slow store as
+  `cache: 'timeout'`. A broken store will then show up here and not just as a
+  rising bill.
+- **Spend.** This is the sum of `usage` over the events where `calledModel` is
+  true. Any requests that joined a generation already in flight will carry the
+  `usage` of that generation too. If you sum over all the events, this will
+  count a call many times. Some of the calls the model answered are turned down
+  by the adapter: a `max_tokens` stop, a refusal, no tool call or a reply that
+  doesn't fit the schema. These were billed too, but they arrive as a
+  `'provider-error'` with no `usage`. That's why your bill will be more than
+  this sum.
 
 ## Running it in a regulated shop
 
-This isn't legal advice, and which rules apply depends on where you sell. It
-describes what the package does, so you can answer what a privacy or
-consumer-law review will ask.
-
-**What leaves your server.** Nothing, unless you pass a `provider`, or a `cache`
-whose store lives somewhere else. With a provider, cohort mode sends the page
-and locale, the category, the segment you set, the shopper's strongest category,
-whether they have any history, and the candidate products. That has no shopper
-id, but it can still be personal data. The strongest category and the history
-flag come from that shopper's data. The segment goes exactly as you wrote it.
-The candidate list is about them too if you pick or order it per shopper.
-Per-shopper mode adds the shopper's own signals. Both lists are under
+This isn't legal advice. Which rules apply will depend on where you sell. To
+help you answer the questions in a privacy or consumer-law review, this section
+describes what the package does.
+
+**What leaves your server.** Nothing, unless you pass a `provider` or a `cache`
+that has its store somewhere else. With a provider, cohort mode will send the
+page and locale, the category, the segment you set, the shopper's strongest
+category, whether they have any history and the candidate products. That has no
+shopper id, but it can still be personal data. Both the strongest category and
+the history flag are taken from the shopper's data. Any segment will go to the
+provider exactly as you wrote it. If you pick or order the candidate list per
+shopper, this list is also about the shopper. Per-shopper mode will also send
+the shopper's signals. You can see these lists under
 [What the model sees](#what-the-model-sees). `user.id` is never sent in either
-mode. The provider should be your processor, under a contract that says so. For
-Anthropic, see the `@rudra-js/anthropic` README.
+mode. The provider should be your processor, under a contract that says this.
+For Anthropic, see the `@rudra-js/anthropic` README.
 
 **A shopper who objects to profiling.** Leave `signals` and `user.segment` out
-of their payload. In per-shopper mode, leave out `context.searchQuery` and
-`user.isReturning` too. They get what a first-time visitor gets, built from the
-page and the catalog, not from them. With those left out,
-`generateDeterministic(input)` gives the same kind of spec without calling the
-model or the cache. Called with signals, it still personalises.
-
-**Deleting a shopper's data.** The package keeps nothing about a shopper except
-the cache. In cohort mode an entry holds no shopper id and everyone in the
-cohort shares it, so usually there's no one shopper's entry to delete. The
-exception is a cohort entry whose segment or candidate list was picked for one
-shopper. Like every per-shopper entry, it's about that shopper. Nothing maps a
-shopper to their entries, so keep `ttlMs` short or pass `createNullSpecCache()`.
-`onEvent` sends no shopper id. But in per-shopper mode its `key` is derived from
-one, and `violations` can name SKUs from a shopper's basket or purchases. So
-treat logs of it as personal data.
-
-**Caching pages.** A personalised page says things like "Goes with your cart"
-and "You looked at this recently" in its HTML. Serve those pages with
-`Cache-Control: private` or `no-store`, so a shared cache never hands one
-shopper's page to another.
-
-**Telling shoppers a model wrote the copy.** The wrapper's `data-rudra-source`
-says `llm` or `cache` when a model wrote the copy, and `fallback` when it
-didn't. That makes it a machine-readable marker you can build on, for example
-to show a note. Whether you must label AI-written copy, and how, depends on
+of their payload. In per-shopper mode, you also need to leave out
+`context.searchQuery` and `user.isReturning`. They will be treated like a
+first-time visitor, with a spec built just from the page and the catalog. With
+those left out, `generateDeterministic(input)` can be used to get the same kind
+of spec without calling the model or the cache. But if you call it with signals,
+it will personalise.
+
+**Deleting a shopper's data.** This package keeps nothing about a shopper except
+the cache. In cohort mode an entry holds no shopper id and it's shared by all
+the shoppers in the cohort. There's usually no single shopper's entry to delete.
+But there's an exception if a cohort entry has a segment or candidate list
+picked for one shopper. Like all per-shopper entries, it's about that shopper.
+Nothing maps a shopper to their entries. That's why you need to keep `ttlMs`
+short or pass `createNullSpecCache()`. `onEvent` sends no shopper id. But in
+per-shopper mode its `key` is derived from a shopper id. `violations` can also
+name SKUs from a shopper's basket or purchases. Treat logs of `onEvent` as
+personal data.
+
+**Caching pages.** In its HTML, a personalised page will say things like
+"Goes with your cart" and "You looked at this recently". Serve those pages with
+`Cache-Control: private` or `no-store`, to be sure a shared cache never hands
+one shopper's page to another.
+
+**Telling shoppers a model wrote the copy.** In the wrapper, `data-rudra-source`
+says `llm` or `cache` if a model wrote the copy but `fallback` if it didn't.
+This makes it a machine-readable marker you can build on, for example to show a
+note. Whether you must label AI-written copy and how you do it will depend on
 where you sell. In the EU, Article 50 of the AI Act is the rule to ask about.
 
-**Claims.** The copy on your page is your own advertising, whoever wrote it. The
+**Claims.** All the copy on your page is your advertising, whoever wrote it. The
 claim check catches prices, discounts, stock, ratings, delivery, urgency and
-generic environmental claims. But it's a list, and rewordings get through.
-SECURITY.md explains why, and the tests list the known ones. Anything it misses
-is still yours to stand behind.
+generic environmental claims. But it's just a list and rewordings get through.
+You can read why in SECURITY.md and see the known ones in the tests. Any claim
+it misses is still yours to stand behind.
 
 **Children.** In the UK, the ICO's Children's Code covers any shop that
-under-18s are more likely than not to use, not only one aimed at them. Its
-standard 12 asks for profiling to be off by default unless you can show a
+under-18s are more likely than not to use, not only a shop aimed at under-18s.
+Its standard 12 asks for profiling to be off by default unless you can show a
 compelling reason, judged by the child's best interests. It also asks for
 safeguards when profiling is on. For a shop like that, don't use per-shopper
-mode. For a shopper under 18, leave `signals` and `user.segment` out of their
-payload unless they've switched personalisation on, as for a shopper who objects
-to profiling. If you can't tell a shopper's age with confidence that fits the
-risk, treat every shopper as under 18. Cohort mode alone doesn't turn profiling
-off. The default `rank: 'signals'` still orders products by the shopper's
-signals in cohort mode and in the fallback, even with no provider. And cohort
-mode still sends their strongest category, whether they have any history, and
-any segment to the model.
+mode. For a shopper under 18, be sure to leave `signals` and `user.segment` out
+of their payload unless they've switched personalisation on, as for a shopper
+who objects to profiling. If you can't tell a shopper's age with confidence that
+fits the risk, treat all shoppers as under 18. Just using cohort mode doesn't
+turn profiling off. By default `rank: 'signals'` will still order products by
+the shopper's signals in cohort mode and in the fallback, even with no provider.
+Cohort mode will also still send their strongest category, whether they have any
+history and any segment to the model.
 
 **Marketplaces.** If other sellers list products on your site, EU platform rules
 (Article 27 of the Digital Services Act) ask you to set out in your terms:
@@ -717,26 +750,27 @@ This doesn't apply if you're a micro or small business. If shoppers can pick
 between options, such as switching personalisation off, the control has to sit
 where the products are shown.
 
-Which parameters apply depends on your mode and your `rank` setting:
+Which parameters apply will depend on your mode and your `rank` setting:
 
-- `rank` sets the order in cohort mode and in the fallback. With `rank: 'given'`
-  that's the order you sent, so describe your own ranking.
+- In cohort mode and in the fallback, `rank` sets the order. With
+  `rank: 'given'` that's the order you sent. This means you will have to
+  describe your own ranking.
 - With `rank: 'signals'` the order comes from the shopper's category interest
   (the category they're browsing counts too), how often they've viewed a
-  product, its rating, and tags it shares with products they've engaged with.
-  Category weighs most.
+  product, its rating and any tags it shares with products they've engaged with.
+  Of these, category weighs most.
 - In per-shopper mode the model picks which candidates to show and in what
   order, from what's under [What the model sees](#what-the-model-sees).
-- In cohort mode the model picks the hero's product, from the cohort list in
-  that section.
-- In every mode, anything out of stock, disliked or being looked at right now is
-  left out. So is anything bought or in the basket, except as part of a bundle.
-- A bundle is picked by what's in the basket, then what they viewed, then the
-  category being browsed.
-
-**Accessibility.** Every card is one link with a readable name, and headings
-only render when they have text. Contrast, focus styles and layout come from
-your stylesheet, so those are yours to check.
+- In cohort mode the model picks the hero's product from the cohort list there.
+- In all modes, anything out of stock, disliked or being looked at right now
+  will be left out. This is also true of anything bought or in the basket,
+  except as part of a bundle.
+- A bundle will be picked by what's in the basket, then what they viewed, then
+  the category being browsed.
+
+**Accessibility.** Each of the cards is a single link with a readable name.
+Headings will only render if they have text. You will have to check contrast,
+focus styles and layout yourself, because these come from your stylesheet.
 
 ## Licence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudra-js/core",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "Core of rudra-js, a TypeScript library for LLM-designed product recommendations: turns one page view into a recommendation spec checked against your catalog",
   "keywords": [
     "rudra-js",
@@ -60,10 +60,10 @@
     "zod": "^4.6.7"
   },
   "peerDependencies": {
-    "@rudra-js/attested": "^0.8.3"
+    "@rudra-js/attested": "^0.9.1"
   },
   "devDependencies": {
-    "@rudra-js/attested": "0.8.3",
+    "@rudra-js/attested": "0.9.1",
     "@types/node": "^26.4.1"
   }
 }