@forgecart/cli 2.202610280649.0 → 2.202610280926.0

package/templates/storefront-blank/src/lib/content/resolve-page.ts

@@ -0,0 +1,143 @@
+import { isLocaleSegment } from '../locale/grammar';
+
+/**
+ * What a storefront page URL resolves to (#1934, epic launch#50) — the WHOLE
+ * decision behind `/pages/<route>`, as a value.
+ *
+ * PURE BY CONTRACT, for the reason `lib/seo/resolve-path.ts` is: this is the
+ * law that decides between a rendered page and a real 404, and
+ * `tool/storefront-template-spec` imports it directly by relative path from
+ * OUTSIDE the scaffold, so nothing reachable from here may need the template's
+ * Next toolchain. The route file is left as dispatch — it turns `notFound` into
+ * Next's `notFound()` and `ok` into markup, and decides nothing itself.
+ *
+ * The inputs are declared STRUCTURALLY rather than imported from the SDK for
+ * the same reason (`ResolvableProduct` precedent): the generated query types
+ * satisfy these shapes structurally, so the scaffold's own `tsc` proves the
+ * assignment while this module stays importable with no `paths`.
+ */
+
+/**
+ * The subset of a page definition this decision reads, declared AS THE SHOP
+ * API'S GENERATED TYPES CARRY IT.
+ *
+ * Every nullable selection reaches a scaffold OPTIONAL as well as nullable
+ * (`route?: Maybe<string>`), so a contract spelled `string | null` would refuse
+ * the very value the query produces — and, this module having no compiler of
+ * its own in this repository, the refusal would surface in the merchant's
+ * `next build` instead of here. Admitting the shape is therefore part of the
+ * contract, not a laxity: what each absence MEANS is decided in the table
+ * below, once, rather than guessed at by each caller.
+ */
+export interface RoutedPageGroup {
+  /**
+   * `'page'` for a storefront page; anything else — a data definition, or a
+   * selection from a pod whose SDK does not carry the field — is not one.
+   */
+  readonly kind?: string | null;
+  /**
+   * The route the definition is mounted at. Absent means mounted NOWHERE: the
+   * column is nullable because most definitions are data rather than pages.
+   */
+  readonly route?: string | null;
+}
+
+/**
+ * Why a page URL is a 404. Four distinct causes, kept apart because they answer
+ * different questions about a deployment — "the merchant has not published
+ * this yet" and "this URL was never a page" look identical to a visitor and are
+ * nothing alike to whoever is debugging.
+ */
+export type PageNotFoundReason =
+  /**
+   * The slug is a two-letter locale segment. No page may hold one (launch#54
+   * W1-7 — the server refuses to mint such a route rather than auto-suffixing
+   * it), so this URL can never carry content in any deployment. Judged first
+   * and without consulting the lookup, so the rule is stated where it is true
+   * rather than inferred from an empty result.
+   */
+  | 'reserved-locale-segment'
+  /**
+   * No page definition of this channel is mounted at this route: the lookup
+   * answered nothing, or what it answered carries no route of its own and is
+   * therefore mounted nowhere.
+   */
+  | 'unknown-route'
+  /** Something answered, but it is not a page definition. */
+  | 'not-a-page'
+  /**
+   * The page exists and has nothing a visitor may see: never given a record, or
+   * holding only records the publish fence hides — a DRAFT, or one SCHEDULED
+   * for a moment that has not arrived. The shop API already removed those rows
+   * (it fences every storefront read to published content), so this arm is the
+   * renderer HONOURING an empty result, never a second publish check.
+   */
+  | 'no-live-content';
+
+/**
+ * The answer for one page URL.
+ *
+ * The `ok` arm carries BOTH halves of what the route renders, narrowed to the
+ * caller's own types. That is why it is generic rather than a bare verdict: a
+ * caller that had to re-check `group !== null` after a resolution that already
+ * proved it would be asserting what the law just decided.
+ */
+export type PageResolution<TGroup, TEntry> =
+  | { kind: 'ok'; group: TGroup; entry: TEntry }
+  | { kind: 'notFound'; reason: PageNotFoundReason };
+
+export interface ResolvePageInput<TGroup, TEntry> {
+  /** The slug exactly as it appeared in the URL, locale prefix already stripped. */
+  requestedRoute: string;
+  /** What `pageByRoute` answered, or null when it answered nothing. */
+  group: TGroup | null;
+  /**
+   * The page's visible records, in the order the CALLER asked for. A page is
+   * one URL, so it serves one record: the first of these. Which record that is
+   * is the caller's decision and belongs at the query (see `getPageEntries`),
+   * not here.
+   */
+  entries: readonly TEntry[];
+}
+
+/**
+ * Decide the honest answer for a page URL.
+ *
+ * TOTAL over its input and ordered so each arm may assume the ones above it did
+ * not fire. Two of the four refusals are the feature's own contract — an
+ * unpublished or not-yet-live page answers 404 — and the other two are what
+ * make the function total.
+ */
+export function resolvePage<TGroup extends RoutedPageGroup, TEntry>({
+  requestedRoute,
+  group,
+  entries,
+}: ResolvePageInput<TGroup, TEntry>): PageResolution<TGroup, TEntry> {
+  if (isLocaleSegment(requestedRoute)) {
+    return { kind: 'notFound', reason: 'reserved-locale-segment' };
+  }
+
+  if (group === null) return { kind: 'notFound', reason: 'unknown-route' };
+
+  // A boundary check, not a redundant one: the shop query returns the general
+  // field-definition type and nothing in that TYPE says "page", so this is the
+  // template asserting that what it is about to render as a page is one — the
+  // same posture `parseScaffoldedRoute` takes toward a value another process
+  // wrote.
+  if (group.kind !== 'page') return { kind: 'notFound', reason: 'not-a-page' };
+
+  // Mounted-ness, read back off the answer itself, in the same posture as the
+  // kind check above: `pageByRoute` matched this group BY its route, so one
+  // that carries none contradicts the question it answered. Stating that as a
+  // 404 is what keeps the route from rendering a page no URL owns — and it is
+  // why the absence is resolved HERE rather than by a caller that would have
+  // to invent a meaning for it.
+  if (group.route === null || group.route === undefined) {
+    return { kind: 'notFound', reason: 'unknown-route' };
+  }
+
+  const entry = entries[0];
+  if (entry === undefined) return { kind: 'notFound', reason: 'no-live-content' };
+
+  return { kind: 'ok', group, entry };
+}

package/templates/storefront-blank/src/lib/error-messages.ts

@@ -0,0 +1,118 @@
+import type { ExtractedError } from '@forgecart/sdk/shop';
+
+/**
+ * Shopper-facing copy for the typed error codes a storefront call can meet.
+ *
+ * The shop API's error contract ships CODES, never prose — `message` on an
+ * extracted error is the code string itself, and resolving human copy is the
+ * frontend's job (error-handling contract). A raw enum leaking into the UI is
+ * a defect (the address step rendered SHIPPING_ADDRESS_PHONE_REQUIRED
+ * verbatim, 2026-08-09).
+ *
+ * Two families live here. The checkout's address codes, and every refusal a
+ * customer ACCOUNT call can meet (#1093): signing in and out, registering, a
+ * verification or reset link, a password or e-mail change. The account family
+ * is swept against the shop's own `ErrorCode` enum by
+ * `tool/storefront-template-spec` — every member of its `Auth - Self-Service`
+ * and `Auth - Service` blocks, plus the sign-in refusal, the anonymous
+ * socket's refusal and the taken address — so a refusal added to the platform
+ * reddens that sweep until it has copy here. Before #1093 this map held the
+ * three address codes alone, and every refused sign-in rendered as the
+ * generic line: indistinguishable from the platform faults it was masking.
+ *
+ * `SHOP_API_UNREACHABLE` is not a platform code but this template's own
+ * (`lib/action-result.ts`): the answer when the API could not be asked at all,
+ * which is the one failure the generic line's "check your details" is wrong
+ * about.
+ *
+ * A Map rather than an object literal: a lookup keyed by an API-supplied
+ * string must not be able to land on `Object.prototype` (`constructor`,
+ * `toString`) and render a function as copy.
+ */
+const SHOPPER_MESSAGES: ReadonlyMap<string, string> = new Map([
+  ['SHIPPING_ADDRESS_PHONE_REQUIRED', 'A phone number is required for delivery updates.'],
+  ['SHIPPING_ADDRESS_COUNTRY_REQUIRED', 'Please select a country.'],
+  ['SHIPPING_ADDRESS_COUNTRY_INVALID', 'We can’t ship to the selected country yet.'],
+  [
+    'INVALID_CREDENTIALS',
+    'That e-mail address and password do not match. Check both and try again.',
+  ],
+  ['UNAUTHORIZED', 'You are not signed in, or your session has ended. Please sign in again.'],
+  [
+    'EMAIL_ADDRESS_CONFLICT',
+    'That e-mail address already has an account. Sign in with it, or reset its password.',
+  ],
+  [
+    'IDENTIFIER_ALREADY_EXISTS',
+    'That e-mail address already has an account. Sign in with it, or reset its password.',
+  ],
+  [
+    'NOT_VERIFIED',
+    'This account is not confirmed yet. Open the link in the confirmation e-mail we sent you, then sign in.',
+  ],
+  [
+    'VERIFICATION_TOKEN_INVALID',
+    'This confirmation link is not valid — it may have been used already. Ask for a new confirmation e-mail.',
+  ],
+  [
+    'VERIFICATION_TOKEN_EXPIRED',
+    'This confirmation link has expired. Ask for a new confirmation e-mail and open the newest link.',
+  ],
+  [
+    'PASSWORD_RESET_TOKEN_INVALID',
+    'This password reset link is not valid — it may have been used already. Ask for a new one.',
+  ],
+  [
+    'PASSWORD_RESET_TOKEN_EXPIRED',
+    'This password reset link has expired. Ask for a new one and open the newest link.',
+  ],
+  [
+    'PASSWORD_VALIDATION_FAILED',
+    'That password does not meet the store’s requirements. Please choose a different one.',
+  ],
+  [
+    'PASSWORD_CHANGE_FAILED',
+    'Your password could not be changed. Check your current password and try again.',
+  ],
+  [
+    'IDENTIFIER_CHANGE_TOKEN_INVALID',
+    'This e-mail change link is not valid — it may have been used already. Ask for the change again.',
+  ],
+  [
+    'IDENTIFIER_CHANGE_TOKEN_EXPIRED',
+    'This e-mail change link has expired. Ask for the change again and open the newest link.',
+  ],
+  [
+    'CUSTOMER_NOT_FOUND',
+    'That account does not shop at this store. Sign in with the address you registered here.',
+  ],
+  ['SESSION_NOT_FOUND', 'Your session has ended. Please sign in again.'],
+  [
+    'SESSION_CACHE_READ_FAILED',
+    'We could not check your session just now. Please try again in a moment.',
+  ],
+  [
+    'SESSION_CACHE_WRITE_FAILED',
+    'We could not save your session just now. Please try again in a moment.',
+  ],
+  [
+    'SHOP_API_UNREACHABLE',
+    'We could not reach the store just now. Please check your connection and try again.',
+  ],
+]);
+
+const FALLBACK_MESSAGE = 'Something went wrong. Please check your details and try again.';
+
+/**
+ * Human copy for a typed error — never undefined.
+ *
+ * A code this map has no copy for renders the generic line WITH the code
+ * appended in parentheses: an unmodelled refusal must stay distinguishable
+ * from a platform fault, by the shopper who reports it and by the merchant —
+ * or their agent — who reads the report. Only an error carrying no code at all
+ * renders the generic line bare.
+ */
+export function shopperMessage(error: Pick<ExtractedError, 'code'> | null | undefined): string {
+  if (!error?.code) return FALLBACK_MESSAGE;
+  return SHOPPER_MESSAGES.get(error.code) ?? `${FALLBACK_MESSAGE} (${error.code})`;
+}

package/templates/storefront-blank/src/lib/experiments.ts

@@ -0,0 +1,333 @@
+import {
+  deriveExposureEventId,
+  resolveExperimentAssignment,
+  type AssignmentResult,
+  type AssignmentSource,
+  type ExperimentAssignmentConfig,
+} from '@forgecart/sdk';
+import { cookies, headers } from 'next/headers';
+import { after } from 'next/server';
+import { cache } from 'react';
+import { uuidv7 } from 'uuidv7';
+
+import { SESSION_COOKIE } from './session-cookies';
+import { forwardTrackEvent, getUpstreamConfig, isObviousBot } from './track-forward';
+import type { TrackEventInput, UpstreamConfig } from './track-forward';
+
+/**
+ * Server-side A/B variant resolution (design doc Wave F-B).
+ *
+ * `getVariant(experimentKey)` is the ONE storefront API for experiments:
+ * Server Components call it and branch on the returned `variantKey` (variant
+ * payloads are code branches first, `payload` JSON second). Resolution is
+ * LOCAL — the SDK's deterministic assignment engine over a TTL-cached config
+ * — so variants render with zero flicker and zero added request round-trips.
+ *
+ * How the pieces fit:
+ *  - Config: the public `activeExperiments` shop query, fetched over raw
+ *    HTTP GraphQL with the hand-rolled `forgecart-token` header (the
+ *    `track-forward.ts` pattern — the template's pinned published SDK has no
+ *    plain-HTTP query path) and cached module-scope for
+ *    {@link CONFIG_TTL_MS} keyed by channel token. A fetch failure resolves
+ *    to "no experiments" (every caller renders the default branch) and is
+ *    cached for the same TTL, so a dead backend costs one failed fetch per
+ *    minute — never one per request.
+ *  - Subject: the `forgecart-visitor` cookie (S6). When absent, an id is
+ *    minted IN-REQUEST via a request-scoped `cache()` — never relying on
+ *    middleware→RSC cookie propagation (S6 doc rule; the middleware persists
+ *    the durable cookie, this module only needs a consistent value for the
+ *    current render). Same UUIDv7 value shape as the middleware mint.
+ *  - Forced entry: the `forgecart-exp-force` cookie the middleware merges
+ *    from `?fc-exp=` campaign URLs. The engine honors it only when the
+ *    experiment allows forced entry and the variant exists
+ *    (`assignmentSource: 'forced'`).
+ *  - Exposure: when the engine says `exposed` (hashed or forced), ONE
+ *    `experiment_exposure` marketing event is emitted per request inside
+ *    `next/server` `after()` — after the response, off the critical path —
+ *    through the shared `forwardTrackEvent` (never an HTTP self-call to the
+ *    relay, never the SDK's identity-pinning WebSocket). The event id is the
+ *    SDK's deterministic UUIDv5 over `salt:subjectKey:utcDay`, so re-renders
+ *    and multi-page sessions dedupe server-side to one exposure per subject
+ *    per UTC day.
+ *
+ * `currencyCode` is deliberately ABSENT from the exposure input: §A wants the
+ * session market's currency on exposures, but pre-cart the template server
+ * has no side-effect-free source for it — the shop API surfaces currency only
+ * via `activeOrder` (whose read AUTO-CREATES an order for a session, see
+ * `cart-actions.ts#getCart`) and the geo-seeded market lives in a session
+ * that a first-touch page view does not yet have. Inventing a source here
+ * (e.g. the channel default off a product read) would mislabel the segment;
+ * the field stays unset until the ingest side can stamp the session market
+ * server-side.
+ */
+
+const VISITOR_COOKIE = 'forgecart-visitor';
+const FORCED_ENTRY_COOKIE = 'forgecart-exp-force';
+
+/** Delivery-config cache TTL — the design doc's 60s config-plane freshness. */
+const CONFIG_TTL_MS = 60_000;
+
+/** Canonical textual UUID — the only visitor-cookie shape trusted as subject. */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Backend slug grammar (`ExperimentService`) — gates keys read from cookies. */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/**
+ * The SDK's own `ShopActiveExperiments` document, inlined — same rationale as
+ * `track-forward.ts`: the generated client is WebSocket-only, so the config
+ * read speaks plain HTTP GraphQL with the identical selection.
+ */
+const ACTIVE_EXPERIMENTS_QUERY = `query ShopActiveExperiments {
+  activeExperiments {
+    experimentKey
+    subjectType
+    version
+    salt
+    lifecycle
+    trafficBps
+    allowForcedEntry
+    variants {
+      key
+      weight
+      payload
+    }
+    winnerVariantKey
+  }
+}`;
+
+/** One variant as the `activeExperiments` shop query delivers it. */
+interface ActiveExperimentVariant {
+  key: string;
+  weight: number;
+  payload: Record<string, unknown> | null;
+}
+
+/** The public delivery projection of one experiment (FB2b contract). */
+interface ActiveExperiment {
+  experimentKey: string;
+  subjectType: 'visitor' | 'customer';
+  version: number;
+  salt: string;
+  lifecycle: 'running' | 'paused' | 'completed';
+  trafficBps: number;
+  allowForcedEntry: boolean;
+  variants: ActiveExperimentVariant[];
+  winnerVariantKey: string | null;
+}
+
+/** What a Server Component branches on. */
+export interface ExperimentVariantResult {
+  /**
+   * The assigned variant key, or `null` when the experiment is unknown /
+   * undelivered / malformed — callers treat `null` as "render the default
+   * branch", which keeps every page correct with zero experiments configured.
+   */
+  variantKey: string | null;
+  /**
+   * How the variant was decided: `'hashed'` (randomized cohort), `'forced'`
+   * (campaign entry — excluded from the randomized comparison), `'lifecycle'`
+   * (paused → control / completed → winner), or `null` (non-participant
+   * control or no experiment).
+   */
+  assignmentSource: AssignmentSource | null;
+  /** The variant's optional delivery payload (design doc Q5), if any. */
+  payload: Record<string, unknown> | null;
+}
+
+interface GraphQLActiveExperimentsResponse {
+  data?: { activeExperiments?: unknown } | null;
+  errors?: unknown[];
+}
+
+/** Module-scope 60s TTL cache — one config fetch per server per minute. */
+let configCache: {
+  channelToken: string;
+  expiresAt: number;
+  load: Promise<ActiveExperiment[]>;
+} | null = null;
+
+async function fetchActiveExperiments(upstream: UpstreamConfig): Promise<ActiveExperiment[]> {
+  try {
+    const response = await fetch(upstream.shopApiUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'forgecart-token': upstream.channelToken,
+      },
+      body: JSON.stringify({ query: ACTIVE_EXPERIMENTS_QUERY }),
+    });
+    if (!response.ok) return [];
+    const payload = (await response.json()) as GraphQLActiveExperimentsResponse;
+    const list = payload.data?.activeExperiments;
+    return Array.isArray(list) ? (list as ActiveExperiment[]) : [];
+  } catch {
+    // Experiments must never break the storefront: no config → every caller
+    // renders its default branch until the next TTL window retries.
+    return [];
+  }
+}
+
+function getActiveExperiments(): Promise<ActiveExperiment[]> {
+  const upstream = getUpstreamConfig();
+  // Inert before `forgecart init` writes `.env` (image-prewarm contract).
+  if (!upstream) return Promise.resolve([]);
+  const now = Date.now();
+  if (
+    configCache &&
+    configCache.channelToken === upstream.channelToken &&
+    now < configCache.expiresAt
+  ) {
+    return configCache.load;
+  }
+  configCache = {
+    channelToken: upstream.channelToken,
+    expiresAt: now + CONFIG_TTL_MS,
+    load: fetchActiveExperiments(upstream),
+  };
+  return configCache.load;
+}
+
+/**
+ * The assignment subject for this request: the S6 visitor cookie when it
+ * rode in, else ONE in-request UUIDv7 shared by every `getVariant` call of
+ * the render (request-scoped `cache()`). A cookie-less first page view thus
+ * gets a consistent assignment within its own render; the middleware's
+ * Set-Cookie makes the durable id authoritative from the next request on.
+ */
+const getRequestVisitorId = cache(async (): Promise<string> => {
+  const store = await cookies();
+  const existing = store.get(VISITOR_COOKIE)?.value;
+  if (existing && UUID_PATTERN.test(existing)) return existing;
+  return uuidv7();
+});
+
+/** The forced-entry map from the middleware-merged cookie, slug-validated. */
+const getForcedVariantMap = cache(async (): Promise<Record<string, string>> => {
+  const store = await cookies();
+  const raw = store.get(FORCED_ENTRY_COOKIE)?.value;
+  if (!raw) return {};
+  let parsed: unknown;
+  try {
+    // `cookies()` already percent-decodes — `raw` is the JSON text.
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return {};
+  const map: Record<string, string> = {};
+  for (const [experimentKey, variantKey] of Object.entries(parsed)) {
+    if (typeof variantKey !== 'string') continue;
+    if (!SLUG_REGEX.test(experimentKey) || !SLUG_REGEX.test(variantKey)) continue;
+    map[experimentKey] = variantKey;
+  }
+  return map;
+});
+
+function toAssignmentConfig(experiment: ActiveExperiment): ExperimentAssignmentConfig {
+  return {
+    salt: experiment.salt,
+    lifecycle: experiment.lifecycle,
+    trafficBps: experiment.trafficBps,
+    allowForcedEntry: experiment.allowForcedEntry,
+    variants: experiment.variants.map(({ key, weight }) => ({ key, weight })),
+    winnerVariantKey: experiment.winnerVariantKey,
+  };
+}
+
+/**
+ * Emit the `experiment_exposure` marketing event inside `after()`. Request
+ * data (UA, client IP, session) is captured HERE, during render — `after()`
+ * callbacks run once the response is done and must not touch request APIs.
+ * The response is already sent when a session-less exposure reaches the shop
+ * API, so a token minted for it cannot be persisted — accepted: the relay's
+ * first client batch establishes the durable shopper session.
+ */
+async function scheduleExposure(
+  experiment: ActiveExperiment,
+  result: AssignmentResult,
+  visitorId: string,
+): Promise<void> {
+  const requestHeaders = await headers();
+  const userAgent = requestHeaders.get('user-agent') ?? '';
+  // Same bot policy as the relay: unambiguous crawlers emit nothing.
+  if (isObviousBot(userAgent)) return;
+  const forwardedFor = requestHeaders.get('x-forwarded-for');
+  const store = await cookies();
+  const sessionToken = store.get(SESSION_COOKIE)?.value ?? null;
+
+  const occurredAt = new Date();
+  const input: TrackEventInput = {
+    eventType: 'experiment_exposure',
+    // Deterministic UUIDv5 over salt:subjectKey:utcDay — every re-render of
+    // this subject today resubmits the SAME id and the backend dedupes.
+    eventId: deriveExposureEventId(experiment.salt, visitorId, occurredAt),
+    occurredAt: occurredAt.toISOString(),
+    properties: {
+      experimentKey: experiment.experimentKey,
+      variantKey: result.variantKey,
+      version: experiment.version,
+      subjectType: experiment.subjectType,
+      assignmentSource: result.assignmentSource,
+      visitorId,
+    },
+  };
+
+  after(async () => {
+    await forwardTrackEvent(input, { sessionToken, userAgent, forwardedFor });
+  });
+}
+
+/**
+ * Resolve the variant for one experiment. Request-scoped `cache()` keeps the
+ * whole render consistent — layout and page asking for the same key get one
+ * resolution and at most ONE exposure emission per request.
+ */
+export const getVariant = cache(async (experimentKey: string): Promise<ExperimentVariantResult> => {
+  const inert: ExperimentVariantResult = {
+    variantKey: null,
+    assignmentSource: null,
+    payload: null,
+  };
+  if (!SLUG_REGEX.test(experimentKey)) return inert;
+
+  const experiments = await getActiveExperiments();
+  const experiment = experiments.find((entry) => entry.experimentKey === experimentKey);
+  if (!experiment) return inert;
+
+  if (experiment.subjectType === 'customer') {
+    // The storefront server has no verified customer id (auth lives behind
+    // the shop API session) — a customer-scoped experiment renders as
+    // non-participant control here, with no exposure. Customer-subject
+    // resolution belongs to clients that KNOW the customer id.
+    const control = experiment.variants[0];
+    if (!control) return inert;
+    return { variantKey: control.key, assignmentSource: null, payload: control.payload ?? null };
+  }
+
+  const visitorId = await getRequestVisitorId();
+  const forcedVariantKey = (await getForcedVariantMap())[experimentKey] ?? null;
+
+  let result: AssignmentResult;
+  try {
+    result = resolveExperimentAssignment(toAssignmentConfig(experiment), {
+      subjectKey: visitorId,
+      forcedVariantKey,
+    });
+  } catch {
+    // A malformed delivery (out-of-bounds weight, empty variants) must
+    // never break rendering — the caller falls back to its default branch.
+    return inert;
+  }
+
+  if (result.exposed && result.variantKey !== null) {
+    await scheduleExposure(experiment, result, visitorId);
+  }
+
+  const variant = experiment.variants.find((entry) => entry.key === result.variantKey);
+  return {
+    variantKey: result.variantKey,
+    assignmentSource: result.assignmentSource,
+    payload: variant?.payload ?? null,
+  };
+});