@rudra-js/core 0.6.0 → 0.7.0

package/src/component-spec.ts

@@ -1,94 +1,38 @@
 import { z } from 'zod';
 
-/**
- * The component specification — the only thing a language model is ever allowed
- * to return.
- *
- * The model chooses layout, ordering, emphasis and copy. Which products to show
- * and why is its call only in per-shopper mode, apart from the product a hero
- * names. It never returns markup, code, URLs, prices, product titles, or
- * images. Every field is an enum, a bounded number, a SKU reference resolved
- * against the candidate set, or free text that is clamped and escaped before it
- * renders. That is what makes generated output safe to put in a server-rendered
- * response.
- *
- * Two constraints shape this file, and both are easy to undo by accident:
- *
- *  1. It doubles as a provider structured-output schema, so it avoids
- *     recursion, string length bounds, and numeric ranges. Providers reject
- *     schemas that use them in strict mode. Bounds are enforced afterwards, in
- *     reconciliation, where a violation can be repaired rather than fatal.
- *  2. Optionality is `.nullable()` rather than `.optional()`, because strict
- *     structured outputs require every declared property to be present. "No
- *     badge" has to be expressible as `null`, not as a missing key.
- *
- * A test asserts both by converting this schema to JSON Schema, so neither is
- * left to a comment nobody reads.
- *
- * Note the asymmetry with `tracking-input`, which rejects unknown fields: these
- * schemas strip them. The inputs differ in kind. An unrecognised key in a host
- * payload is a typo, and silently dropping it costs the shopper their history,
- * so it must be loud. An unrecognised key from a model is drift, and discarding
- * it is exactly right — rejecting the whole spec over one stray key would cost
- * the shopper the component. Either way the renderer only ever sees the fields
- * declared here, which is the property that matters.
- */
-
-/** Overall voice of the component. */
 export const TONES = ['neutral', 'enthusiastic', 'urgent', 'editorial'] as const;
 
-/** What a banner is claiming. */
 export const BANNER_TONES = ['info', 'promo', 'urgency', 'restock'] as const;
 
-/** How prominently a single product is placed. */
 export const EMPHASIS = ['normal', 'featured'] as const;
 
-/**
- * Why a product was chosen — the recommendation strategy behind the pick.
- *
- * This is a closed set rather than free text because every value here is a
- * factual claim about the shopper, and a claim the server can check. "Because
- * you viewed this" written as prose is unverifiable: nothing downstream can
- * tell whether the shopper viewed anything. Declared as `most_viewed`,
- * reconciliation can look it up in the digest and drop the claim if it is
- * false.
- *
- * Every value is deliberately checkable against data already in hand — the
- * signal digest or the host's own catalog. A basis that needs data the
- * framework never receives (`new_arrival`, `back_in_stock`, `trending_today`)
- * is not in this list, because it could only ever be taken on trust.
- */
 export const RECOMMENDATION_BASES = [
-  /** Same category as the product being viewed. */
   'similar_to_current',
-  /** The shopper has viewed this product. */
+
   'most_viewed',
-  /** Goes with something already in the cart. */
+
   'complements_cart',
-  /** Goes with something the shopper has bought. */
+
   'complements_purchase',
-  /** In a category the shopper's signals favour. */
+
   'liked_category',
-  /** No claim about this shopper at all — the safe default. */
+
   'popular',
 ] as const;
 
-/** A reference to one product from the candidate set, and why it was chosen. */
 export const productReferenceSchema = z.object({
-  /** Must be a SKU the host supplied in `TrackingInput.candidates`. */
   sku: z.string(),
-  /** Checked against the shopper's signals, so the model cannot assert a pick it did not earn. */
+
   basis: z.enum(RECOMMENDATION_BASES),
-  /** How the basis is phrased, e.g. "Pairs with the boots you bought". Null once unverifiable. */
+
   reason: z.string().nullable(),
-  /** Short accent label, e.g. "Worth a look". Null when nothing warrants one. */
+
   badge: z.string().nullable(),
   emphasis: z.enum(EMPHASIS),
 });
 export type ProductReference = z.infer<typeof productReferenceSchema>;
 export type RecommendationBasis = (typeof RECOMMENDATION_BASES)[number];
 
-/** One large featured statement, optionally anchored to a single product. */
 const heroBlockSchema = z.object({
   kind: z.literal('hero'),
   headline: z.string(),
@@ -97,7 +41,6 @@ const heroBlockSchema = z.object({
   ctaLabel: z.string().nullable(),
 });
 
-/** The general-purpose choice when several products are comparably relevant. */
 const gridBlockSchema = z.object({
   kind: z.literal('grid'),
   title: z.string().nullable(),
@@ -105,14 +48,12 @@ const gridBlockSchema = z.object({
   items: z.array(productReferenceSchema),
 });
 
-/** A horizontally scanned row, for when order implies a ranking. */
 const carouselBlockSchema = z.object({
   kind: z.literal('carousel'),
   title: z.string().nullable(),
   items: z.array(productReferenceSchema),
 });
 
-/** A single line of merchandising copy. */
 const bannerBlockSchema = z.object({
   kind: z.literal('banner'),
   tone: z.enum(BANNER_TONES),
@@ -120,24 +61,21 @@ const bannerBlockSchema = z.object({
   ctaLabel: z.string().nullable(),
 });
 
-/** Short editorial prose, for explaining the theme of a selection. */
 const copyBlockSchema = z.object({
   kind: z.literal('copy'),
   title: z.string().nullable(),
   body: z.string(),
 });
 
-/** A set the shop sells together. The shop picks which one; this only asks for it. */
 const bundleBlockSchema = z.object({
   kind: z.literal('bundle'),
   title: z.string().nullable(),
   body: z.string().nullable(),
   ctaLabel: z.string().nullable(),
-  // Filled in per request. Whatever the model puts here is thrown away.
+
   bundleId: z.string().nullable(),
 });
 
-/** Blocks do not nest. The vocabulary is closed on purpose. */
 export const blockSchema = z.discriminatedUnion('kind', [
   heroBlockSchema,
   gridBlockSchema,
@@ -156,75 +94,49 @@ export type BannerBlock = z.infer<typeof bannerBlockSchema>;
 export type CopyBlock = z.infer<typeof copyBlockSchema>;
 export type BundleBlock = z.infer<typeof bundleBlockSchema>;
 
-/**
- * Exactly what the model must return. Provenance — version, slot, latency, which
- * provider answered — is added by the server afterwards, and is deliberately not
- * part of the model's burden.
- */
 export const generatedSpecSchema = z.object({
   tone: z.enum(TONES),
   headline: z.string(),
   subheadline: z.string().nullable(),
   blocks: z.array(blockSchema),
-  /** One sentence for generation logs, not for shoppers. Not rendered by default. */
+
   rationale: z.string(),
 });
 export type GeneratedSpec = z.infer<typeof generatedSpecSchema>;
 export type GeneratedSpecResult = z.ZodSafeParseResult<GeneratedSpec>;
 
-/** How a spec came to exist. Surfaced for benchmarking and observability. */
 export type SpecSource = 'llm' | 'cache' | 'fallback';
 
-/**
- * Why a component is not what the model would have produced.
- *
- * A closed set, like `SpecSource`: it is rendered into pages as
- * `data-rudra-degraded` and counted in dashboards, so a host needs to know what
- * it can receive without reading the generator.
- */
 export type DegradedReason =
-  /** No provider was configured, so nothing was ever asked. */
   | 'no-provider'
-  /** The provider errored, or threw before it reached the vendor. */
   | 'provider-error'
-  /** The deadline fired before an answer arrived. */
   | 'timeout'
-  /** An answer came back that did not satisfy the schema. */
   | 'invalid-generation'
-  /** A usable answer reconciled down to nothing for this shopper. */
   | 'unusable-on-serve'
-  /** The caller asked for the deterministic component on purpose. */
   | 'requested';
 
 export const SPEC_VERSION = '1' as const;
 
-/** A generated spec plus the provenance the server owns. This is what renders. */
 export interface ComponentSpec extends GeneratedSpec {
   specVersion: typeof SPEC_VERSION;
   slot: string;
   source: SpecSource;
-  /** Epoch milliseconds at which the underlying generation completed. */
+
   generatedAt: number;
-  /** Wall-clock milliseconds spent producing it, including any cache lookup. */
+
   latencyMs: number;
-  /** Provider name, or null when no model was involved. */
+
   provider: string | null;
-  /** Model identifier, or null when no model was involved. */
+
   model: string | null;
-  /**
-   * Why the deterministic component is showing instead of a generated one.
-   * Present on every fallback, including the ones where no model was involved
-   * at all — no provider configured, or the caller asked for it directly.
-   */
+
   degradedReason?: DegradedReason;
 }
 
-/** Throws a `ZodError` if the value is not a well-formed generated spec. */
 export function parseGeneratedSpec(value: unknown): GeneratedSpec {
   return generatedSpecSchema.parse(value);
 }
 
-/** Non-throwing variant, for validating untrusted model output. */
 export function safeParseGeneratedSpec(value: unknown): GeneratedSpecResult {
   return generatedSpecSchema.safeParse(value);
 }

package/src/fallback-component.ts

@@ -3,7 +3,6 @@ import type { SignalDigest } from './signal-digest.js';
 import { selectProducts, type SelectOptions, type ProductPick } from './product-selection.js';
 import type { TrackingInput } from './tracking-input.js';
 
-/** A featured lead only reads as deliberate when something follows it. */
 const MIN_PICKS_FOR_A_FEATURED_LEAD = 3;
 
 function headlineFor(digest: SignalDigest): { headline: string; subheadline: string | null } {
@@ -20,7 +19,6 @@ function headlineFor(digest: SignalDigest): { headline: string; subheadline: str
   return { headline: 'You might also like', subheadline: null };
 }
 
-/** Wide enough to fill, never wider. */
 function columnsFor(itemCount: number): 2 | 3 | 4 {
   if (itemCount >= 4) return 4;
   if (itemCount === 3) return 3;
@@ -37,15 +35,6 @@ function toProductReference(pick: ProductPick, index: number, total: number): Pr
   };
 }
 
-/**
- * Builds a renderable spec from signals alone. Never throws. Returns a spec with
- * no blocks only when there is genuinely nothing in stock left to show, which
- * the renderer treats as "render nothing" — an empty recommendation region is
- * worse than none.
- *
- * Reads the same digest and selector the model path does, so a degraded render is
- * a weaker version of the same decision rather than an unrelated one.
- */
 export function buildFallbackSpec(
   input: TrackingInput,
   digest: SignalDigest,

package/src/fit-to-shopper.ts

@@ -6,38 +6,29 @@ export interface FittedSpec {
   ourReasons: Map<string, string>;
 }
 
-// The model picks the shape. Selection picks the grid and carousel products and
-// what may be said about them, so a shared component still fits one shopper.
 export function fitToShopper(
   spec: GeneratedSpec,
   picks: readonly ProductPick[],
   maxItems: number,
 ): FittedSpec {
-  // Picks are ordered best first. Every slot takes the next one.
   let next = 0;
   const limit = Math.min(picks.length, maxItems);
 
   const ourReasons = new Map<string, string>();
   const blocks: Block[] = [];
   for (const block of spec.blocks) {
-    // A hero is left alone. Its headline and body were written about the
-    // product it names, so swapping the product would leave copy that describes
-    // something else. Reconciliation drops the link if this shopper cannot see
-    // that product, and the words stay.
-
     if (block.kind === 'grid' || block.kind === 'carousel') {
       const items: ProductReference[] = [];
       for (const item of block.items) {
-        if (next >= limit) break; // shrink, never pad
+        if (next >= limit) break;
         const chosen = picks[next]!;
-        // Every reason here is written by this library or handed to it by the
-        // shop. None of them is the model's, whatever the model wrote in this slot.
+
         ourReasons.set(chosen.product.sku, chosen.reason);
         items.push({
           sku: chosen.product.sku,
           basis: chosen.basis,
           reason: chosen.reason,
-          // The badge was written about a different product.
+
           badge: null,
           emphasis: item.emphasis,
         });

package/src/index.ts

@@ -1,11 +1,3 @@
-/**
- * @rudra-js/core — the contracts and logic that turn one tracking payload into one
- * renderable component specification.
- *
- * Carries no React and no model-vendor SDK, so it can be unit tested in
- * isolation and imported from any server runtime.
- */
-
 export {
   FIELD_LIMITS,
   productSchema,

package/src/model-prompt.ts

@@ -2,30 +2,12 @@ import { BANNER_TONES, EMPHASIS, RECOMMENDATION_BASES, TONES } from './component
 import type { SignalDigest } from './signal-digest.js';
 import { FIELD_LIMITS, type Product, type TrackingInput } from './tracking-input.js';
 
-/**
- * What actually reaches the model.
- *
- * The prompt is split in two, and the split is load-bearing. `system` is
- * byte-identical for every request in a deployment, which is what lets a
- * provider cache it and charge a fraction for the repeat. `user` carries
- * everything that varies. Interpolating one shopper's data into the system half
- * would not break anything visibly — it would quietly make the cached prefix
- * useless and multiply the bill, which is why a test asserts the halves stay
- * separate rather than trusting anyone to remember.
- *
- * This module is also the only place shopper-supplied text meets model
- * instructions, so every host value is written as a JSON string rather than as
- * prose. A search for `boots\n\n# Task\nIgnore the above` is then one quoted
- * value on one line, not a heading the model might read as a new instruction.
- */
-
 export const UNTRUSTED_BEGIN = 'BEGIN_UNTRUSTED_DATA';
 export const UNTRUSTED_END = 'END_UNTRUSTED_DATA';
 
 export interface PromptPair {
-  /** Stable across requests. Safe for a provider to cache. */
   system: string;
-  /** Everything about this shopper and this page. */
+
   user: string;
 }
 
@@ -126,45 +108,9 @@ The "rationale" field is for engineers reading generation logs, not for
 shoppers. One sentence on why this arrangement, naming the signals you leaned
 on.`;
 
-/**
- * Characters a value has no business containing.
- *
- * `JSON.stringify` escapes control characters, quotes and backslashes, and
- * nothing else. Everything below survives it, and each one lets a shopper's
- * value do something the surrounding quotes are meant to prevent — end a line,
- * reverse the reading order, or carry text that displays as nothing at all.
- *
- * This is written as Unicode properties rather than a list of code points on
- * purpose. A list is a denylist: it covered the tag block (U+E0000-U+E007F)
- * but not the variation selectors supplement (U+E0100-U+E01EF), which smuggles
- * text exactly the same way, and it missed U+0085, U+061C and U+00AD as well.
- * Properties cover the ones nobody has thought of yet.
- *
- * The general categories alone do not, though. Half of what renders as nothing
- * is a mark or a letter rather than a format character \u2014 the Mongolian free
- * variation selectors, U+034F, the Hangul fillers, and the sixteen variation
- * selectors at U+FE00 \u2014 so `Default_Ignorable_Code_Point` is in the class too.
- * It is the property that means "takes up no room", which is the thing that
- * makes a character able to carry text nobody sees.
- *
- * Three are left out. The zero-width joiner is a format character, but it is
- * also how a family emoji is spelled, and U+FE0E and U+FE0F are what make a
- * character render as an emoji rather than as text. Escaping those mangles
- * ordinary product titles. The other thirteen selectors at U+FE00 spell
- * nothing and are escaped like the rest.
- */
 const UNPRINTABLE =
   /(?!\u{200D}|\u{FE0E}|\u{FE0F})[\p{Cc}\p{Cf}\p{Cn}\p{Co}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}]/gu;
 
-/**
- * How long one quoted value may be once escaped.
- *
- * The contract caps the string a host may send, and this caps what that string
- * turns into. They are not the same number: an escape writes up to eight
- * characters for one, so a field on its cap can still buy eight times the
- * prompt \u2014 and the bill \u2014 that the cap implies. Ordinary text escapes nothing
- * and never comes near this.
- */
 const MAX_QUOTED = FIELD_LIMITS.shortText * 2;
 
 const escapeUnprintable = (text: string) =>
@@ -173,12 +119,10 @@ const escapeUnprintable = (text: string) =>
     return `\\u{${codePoint.toString(16).toUpperCase()}}`;
   });
 
-/** Host-supplied text, written so it cannot introduce structure of its own. */
 const quote = (value: string) => {
   const escaped = escapeUnprintable(JSON.stringify(value));
   if (escaped.length <= MAX_QUOTED) return escaped;
 
-  // Cut whole characters, so the result cannot end inside an escape sequence.
   let length = 2;
   let kept = '';
   for (const character of value) {
@@ -237,29 +181,8 @@ function describeCandidate(product: Product): string {
   return `- ${parts.join(' | ')}`;
 }
 
-/**
- * How many candidates reach the prompt.
- *
- * The payload contract caps the candidate list at 200, and every field on a
- * product at its own length — which multiplies out to a prompt far larger than
- * is sensible to send or pay for. The contract deliberately does not impose an
- * aggregate budget, on the grounds that trimming to fit is this layer's job.
- * This is that trim. The host's ordering is its merchandising priority, so the
- * first ones through are the ones it put first.
- */
 const MAX_CANDIDATES = 60;
 
-/**
- * The candidates the model is actually shown.
- *
- * An out-of-stock product is dropped during reconciliation whatever the model
- * does with it, so offering one only costs the shopper a slot.
- *
- * Exported because reconciliation checks the numerals the model writes against
- * the strings on this list, and a candidate it was never shown cannot be where
- * one came from. Two copies of "what the model saw" would drift, and the pair
- * that drifted would be the prompt and the screen reading it back.
- */
 export function offeredCandidates(input: TrackingInput): Product[] {
   return input.candidates.filter((product) => product.isInStock).slice(0, MAX_CANDIDATES);
 }
@@ -267,10 +190,6 @@ export function offeredCandidates(input: TrackingInput): Product[] {
 export function buildPrompt(input: TrackingInput, digest: SignalDigest): PromptPair {
   const offered = offeredCandidates(input);
 
-  // The markers are OWASP's labelled-block recommendation. They are safe as
-  // boundaries because every value between them is quoted and stripped of
-  // anything that could end a line, so no shopper value can occupy a line by
-  // itself — which is the only way one could impersonate a marker.
   const user = `${UNTRUSTED_BEGIN}
 
 ## Shopper

package/src/product-selection.ts

@@ -3,35 +3,16 @@ import type { SignalDigest } from './signal-digest.js';
 import { neverRecommend } from './reconciliation.js';
 import type { Product, TrackingInput } from './tracking-input.js';
 
-/**
- * The deterministic selector — which products to show, in what order, and why.
- *
- * This is the half of the problem a language model is not needed for. Given the
- * same digest, it always returns the same picks, it cannot fail, and it costs
- * nothing. It exists for three reasons, in ascending order of importance:
- *
- *  1. It is what renders when the model is slow, erroring, or not configured.
- *  2. It supplies the candidate ordering the model is asked to work from.
- *  3. It is the control arm. If a generated component cannot be told apart from
- *     this, the model has not earned its place, and the evaluation has to be
- *     able to ask that question honestly.
- */
-
 export interface ProductPick {
   product: Product;
-  /** Why this product, stated so reconciliation can check it. */
+
   basis: RecommendationBasis;
-  /** How the basis reads to a shopper. The host's own sentence when it wrote one. */
+
   reason: string;
-  /** Unnormalised. Only the ordering is meaningful. */
+
   score: number;
 }
 
-/**
- * How much each factor moves a product up the list. Relative sizes are what
- * matter: category affinity dominates, a revisit is nearly as strong, and
- * rating only separates products the signals cannot.
- */
 const SCORE_WEIGHTS = {
   category: 3,
   revisit: 1.5,
@@ -39,7 +20,6 @@ const SCORE_WEIGHTS = {
   tagOverlap: 0.6,
 } as const;
 
-/** Beyond this many shared tags, more overlap says nothing new. */
 const MAX_TAG_OVERLAP = 3;
 
 const UNRATED = 3.5;
@@ -67,15 +47,6 @@ interface Evidence {
   hasCart: boolean;
 }
 
-/**
- * States why a product was picked, choosing the most specific claim the signals
- * actually support.
- *
- * Every branch has to be one reconciliation can verify — the selector is held to
- * the same standard as the model, and a basis it cannot support would be
- * downgraded there just the same. `popular` asserts nothing and is the honest
- * answer when nothing else holds.
- */
 function basisFor(
   product: Product,
   digest: SignalDigest,
@@ -96,16 +67,9 @@ function basisFor(
   return { basis: 'popular', reason: `Popular in ${product.category}` };
 }
 
-/** How the picks are ordered once the unplaceable ones are gone. */
 export type RankOrder = 'signals' | 'given';
 
 export interface SelectOptions {
-  /**
-   * `signals` scores each candidate and orders by that score. `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 every pick
-   * still carries a basis reconciliation can verify.
-   */
   rank?: RankOrder;
 }
 
@@ -117,8 +81,7 @@ export function selectProducts(
   const affinityByCategory = new Map(
     digest.categoryAffinity.map((affinity) => [affinity.category, affinity.score]),
   );
-  // Normalised against the strongest affinity so the weights below mean the
-  // same thing whether a shopper has two signals or two hundred.
+
   const strongestAffinity = Math.max(1, ...affinityByCategory.values());
   const tags = engagedTags(input, digest);
   const excluded = neverRecommend(input);
@@ -132,8 +95,7 @@ export function selectProducts(
     const categoryScore = (affinityByCategory.get(product.category) ?? 0) / strongestAffinity;
     const tagOverlap = product.tags.filter((tag) => tags.has(tag)).length;
     const ratingScore = (product.rating ?? UNRATED) / 5;
-    // Something viewed and not bought is a strong re-surface signal, but it
-    // saturates: the twentieth view means little more than the fifth.
+
     const revisitScore = Math.min(1, Math.log2(1 + (viewsBySku.get(product.sku) ?? 0)) / 3);
 
     const score =

package/src/provider.ts

@@ -1,16 +1,6 @@
 import type { z } from 'zod';
 import type { GeneratedSpec } from './component-spec.js';
 
-/**
- * The language-model port.
- *
- * `@rudra-js/core` depends on no vendor SDK. Adapters live in their own packages,
- * so a host installs exactly one and the rest never reach its dependency tree.
- * Anything satisfying this interface works — a hosted API, a self-hosted model,
- * an in-tenancy deployment, or a recorded fixture.
- */
-
-/** Reported by an adapter for cost accounting. Never used for control flow. */
 export interface TokenUsage {
   inputTokens?: number;
   outputTokens?: number;
@@ -19,21 +9,12 @@ export interface TokenUsage {
 }
 
 export interface ProviderRequest {
-  /**
-   * Stable across every request in a deployment. Adapters that support prompt
-   * caching should mark this as the cached prefix; interpolating anything
-   * per-shopper into it would silently destroy the cache hit rate.
-   */
   system: string;
-  /** Per-request content. Must not be merged into the cached prefix. */
+
   user: string;
-  /**
-   * The schema the response must satisfy. Adapters convert it with their own
-   * SDK helper, so there is no hand-maintained JSON Schema to drift out of
-   * sync with the one `component-spec` defines.
-   */
+
   schema: z.ZodType<GeneratedSpec>;
-  /** Fires when the caller's budget elapses. An adapter must stop work. */
+
   signal: AbortSignal;
 }
 
@@ -42,48 +23,18 @@ export interface ProviderResult {
   usage?: TokenUsage;
 }
 
-/**
- * What an adapter promises.
- *
- * Three obligations, none of which the caller can verify from the outside, so
- * they are stated here rather than assumed:
- *
- *  1. Return a parsed object, not a string. Turning model output into a
- *     `GeneratedSpec` is the adapter's job, because only it knows what its
- *     structured-output mode returns.
- *  2. Throw on failure — a refusal, a transport error, an unparseable
- *     response. Never return a partial or invented spec. The caller treats a
- *     throw as "use the deterministic component", which is always safe; a
- *     fabricated spec is not.
- *  3. Respect `signal`, in both directions: do not start work when it is
- *     already aborted, and stop when it aborts mid-flight. The caller races
- *     the call against its own timeout regardless, so ignoring it does not
- *     hold a page open — but it does leave work running and billing after
- *     nobody is waiting, and it answers a caller that has already given up.
- *
- *     `AbortSignal.throwIfAborted()` is the whole of the first half.
- *
- * The caller re-validates whatever comes back. An adapter that returns
- * something malformed is a bug, not a security hole.
- */
 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>;
 }
 
-/** A provider that returns a fixed spec and never touches the network. */
 export function createFixedSpecProvider(spec: GeneratedSpec): ComponentProvider {
   return {
     name: 'fixed',
     model: 'none',
     generate: async ({ signal }) => {
-      // Nothing here is slow enough to need cancelling, which is exactly why it
-      // is worth checking: the obligation is not "cancel your work", it is "do
-      // not answer a caller that has already given up". A reference
-      // implementation that skips the cheap half teaches the wrong lesson.
       signal.throwIfAborted();
       return { spec };
     },