@revturbine/sdk 0.11.13 → 0.11.17

package/CHANGELOG.md

@@ -47,6 +47,687 @@ also require a changelog entry.
 
 ---
 
+## 0.11.17
+
+### Checkout metadata helper, `checkout_started`, and decision context on interactions (plan 282 TASK-9, BL-0432)
+
+**What changed.** Three additive changes to the browser SDK (`@revturbine/sdk`);
+no existing signature narrows.
+
+- **`checkoutMetadata(outputId)`** (new, `@public`) returns the Stripe Checkout
+  `revturbine_*` metadata bag for an output this SDK decided — user, account,
+  placement, decision, output, rule and target plan — plus
+  `client_reference_id` (the user id). Pass `metadata` as both the session's
+  `metadata` and `subscription_data.metadata`; the mirror is what reaches each
+  invoice's `parent.subscription_details.metadata`. A key the SDK does not hold
+  is absent, never empty; `null` for an output this SDK did not decide. New
+  types `RevTurbineCheckoutMetadata` and `RevTurbineCheckoutMetadataBag`.
+- **`checkout_started`** (taxonomy v6, `@revt-eng/schema` 0.1.381) is emitted on
+  a `cta_clicked` whose CTA opens a plan picker or pricing page
+  (`CHECKOUT_STARTED_CTA_ACTION_TYPES`: `navigate_to_plans`, `view_plans`) with
+  `{ placement_id, payload_id, decision_id, plan_handle, rule_handle }`. Never
+  for `open_checkout_modal` — that CTA opens checkout directly ("on click"), so
+  its started count is its clicked count.
+- **`trackTreatmentInteraction`** accepts optional `decisionId`,
+  `segmentHandles` and `segmentIds` (`RevTurbineTreatmentInteractionDecisionContext`;
+  the parameter type is now `RevTurbineTreatmentInteractionRequest`, a
+  superset of the previous `RevTurbineTreatmentInteractionInput`) and sends
+  them as `decision_id` / `segment_handles` / `segment_ids`. Segments are
+  handles: `segment_handles` is the effective set scaffold's `evaluateSegments`
+  built plus any hosted-resolved slugs — the analytics join key — and
+  `segment_ids` carries only the minted ids a hosted context supplied
+  (telemetry; omitted entirely in local mode). When not given, they are filled
+  from the output this SDK indexed for `payloadId`; a caller that gives none
+  and names no indexed output sends exactly the row it sent before. The React
+  controller's clicks and the output-addressed `convert()` / `dismiss()` /
+  `snooze()` carry them.
+
+**Landed in** 0.11.17. **Fail-closed in** n/a — additive. The headless ports
+(Python, Rust, `server-node`) carry only the re-vendored generated types for
+the 0.1.381 pin; the cross-language parity corpus is untouched.
+
+**Docs.** `guides/billing.mdx` "Where checkout fits" now documents the bag, the
+`subscription_data.metadata` mirror, `client_reference_id`, and that Customer
+metadata cannot be set from Checkout.
+
+**Proving tests.** `web-sdk/checkout-metadata.test.ts`,
+`web-sdk/checkout-started-emit.test.ts`,
+`web-sdk/interaction-decision-context.test.ts`.
+
+### `update({ usage })` now reaches usage and credit threshold placements and their usage tokens (BL-0402, BL-0409)
+
+**What changed.** A behaviour fix in the browser SDK (`@revturbine/sdk`); no
+signature changes. `update({ usage })` / `updateUsage()` wrote only the SDK's
+private usage balances. `can()` and `getUsage()` read those balances, but the
+placement resolver built its usage state from the user context's `usage`
+entries alone, and took each entry's `limit` only from a per-entry field
+(default `0`). The shared threshold gate fails closed on a missing or zero
+limit. So `usage_threshold` and `credit_threshold` placements (the 80% usage
+banner, the low-credits warning) never fired for app-reported usage, and
+`{{usage_current}}` / `{{usage_limit}}` / `{{usage_remaining}}` /
+`{{usage_percent}}` stayed stale or unresolved, while the gate and the meter
+moved.
+
+Placements now read one usage view, the same one `getUsage()` reports:
+
+- **Used**: the balance the app reported through `update({ usage })` /
+  `updateUsage()` / `identify(…, { usage })` wins (the most recent write),
+  else the context entry's `amount`.
+- **Limit**: the context entry's own `limit` wins, else the Playbook
+  allowance for the user's **current plan** (the plan-scoped `usage_limit`
+  rule's `limit_value` or `credits` rule's `allowance_value`, which is the
+  `limit` `getUsage()` already returned). An `unlimited` or absent allowance
+  means no threshold: the placement does not fire.
+- **Tokens**: the SDK now fills the usage token family in decision content
+  from the same view. It fills `{{usage_current}}` whenever usage is known.
+  It fills `{{usage_limit}}`, `{{usage_remaining}}` and `{{usage_percent}}`
+  only when a positive limit is known, so an unlimited allowance leaves
+  those tokens untouched instead of rendering `0`. The `<unit>_usage_*`
+  forms and the aliases (`current_usage`, `current_limit`,
+  `remaining_usage`) are filled too. A registered entitlements provider
+  still supplies its own usage state, as before.
+
+`can()` and `getUsage()` are unchanged. The headless server ports (Python,
+Rust, `server-node`) take usage counters from the caller and are unaffected;
+the cross-language parity corpus is untouched.
+
+**Docs.** `tutorials/usage-quota-meter.mdx` and
+`tutorials/low-credits-warning.mdx` now use the canonical flat Playbook rule
+shape (`kind` + `limit_value` / `allowance_value`, handle-valued ids). The
+old nested `type_fields` shape resolved no allowance, so neither tutorial's
+banner could fire. The expected-behaviour table now matches what the SDK
+does: the banner shows from 80%, and at 100% `can('api_calls')` denies.
+
+**Proving test.** `web-sdk/usage-reaches-placements.test.ts`.
+
+### App-supplied trial context now reaches trial placements, trial tokens and reverse-trial grants (BL-0403)
+
+**What changed.** A behaviour fix in the browser SDK (`@revturbine/sdk`); no
+signature changes. `user.trial` at init, `update({ trial })`,
+`setUserContext({ trial })` and a server action's `userContext` result all
+merged into the user context's `trial`, but neither trial reader looked there.
+The placement resolver's plan state (which gates `trial_started`,
+`trial_progress`, `trial_ending`, `trial_ended` and `trial_converted`
+placements) and the reverse-trial entitlement grants read only the SDK's own
+trial status, written by `localRuntime.initialData.trialStatus`, `hydrate()`,
+`getTrialStatus()` and `setTrialInstances()`. So an app that supplied its
+trial saw no trial placement fire, no reverse-trial grant apply, and
+`{{trial_days_remaining}}` stay raw.
+
+Both readers now use one trial view:
+
+- **Sources.** The user context's `trial` (what the app supplies, plus the
+  authenticated client-context delivery, which merges its trial into the same
+  field) and the SDK trial status (`initialData.trialStatus`, `hydrate()`,
+  `getTrialStatus()`, `setTrialInstances()`).
+- **Precedence: the most recent change wins**, the same rule the usage view
+  applies to reported balances (BL-0402). A server-delivered or hydrated
+  status wins when it arrives after the app's trial (an
+  `initialData.trialStatus` passed alongside init `user.trial` counts as
+  later). An app `update({ trial })` made after it wins over it. Re-sending
+  an unchanged trial is not a newer write, so passing the same trial on every
+  render never displaces a fresher server status. A source that was never
+  supplied does not compete.
+- **Tokens.** The SDK now fills `{{trial_days_remaining}}` and
+  `{{trial_days_total}}` in decision content from the same plan state the
+  trial gate read. A token whose value is unknown is left untouched.
+- **`getTrialStatus()`** in `local_only` mode with no `getTrialStatus`
+  resolver returns this trial view, the app-supplied trial included.
+
+**React.** `<RevTurbineProvider>` no longer reports `trial`, `tiers`,
+`payment_failed`, `payment_at_risk`, `instances`, `experiments`, `email_type`,
+`derived_config_version`, `context_hash` or `derived_computed_at` in
+`options.user` as "dropped unrecognized user-context key(s)" on mount. The SDK
+constructor already merges them from `options.user`; the provider now forwards
+only the identity fields `identify()` merges. Unknown keys and server-assigned
+keys are still reported.
+
+The headless server ports (Python, Rust, `server-node`) take an
+already-derived trial status and are unaffected; the cross-language parity
+corpus is untouched.
+
+**Proving tests.** `web-sdk/trial-reaches-placements.test.ts`,
+`web-sdk/react/RevTurbineProvider.identify-context.test.tsx`.
+
+### Trial state no longer leaks across users; app-supplied trials fire lifecycle triggers; `getUserContext()` reports trial and billing fields (BL-0417)
+
+**What changed.** Behaviour fixes in the browser SDK (`@revturbine/sdk`)
+that follow up BL-0403. No signature changes.
+
+- **Reset and user switch.** `resetIdentity()` / `resetUserContext()`
+  cleared the user context but kept the SDK trial status (from
+  `initialData.trialStatus`, `hydrate()`, `getTrialStatus()` or
+  `setTrialInstances()`). They also kept which trial source was newest and
+  the last lifecycle stage. So the next user saw the previous user's trial
+  placements, reverse-trial grants and `{{trial_days_*}}` tokens, and a
+  trial-less next user could emit `trial_expired`. A reset now clears all of
+  that, and the next user starts with no trial. Identifying a **different**
+  user without a reset (`identify()`, `setUserContext({ id })`, or a
+  `hydrate()` payload for another user) now drops the previous user's trial
+  (both sources) and usage (reported balances and context `usage`) before
+  merging the new user's values. The new user's own values still apply. Going
+  from anonymous to identified, or re-identifying the same user, keeps what
+  is held. Reported usage was already cleared on reset; only the
+  switch-without-reset path leaked it.
+- **Lifecycle triggers.** `trial_midpoint`, `trial_expiring` and
+  `trial_expired` fired only from `getTrialStatus()` and
+  `setTrialInstances()`. The SDK now also runs the lifecycle evaluation
+  against the resolved trial view after every change that can move it:
+  `user.trial` at init, `update({ trial })`, `setUserContext`, a server
+  action's context, the client-context delivery, `hydrate()`, a reset, and a
+  Playbook load that turns the triggers on. The dedupe has not changed: a
+  stage fires only when it differs from the last stage seen. So an unchanged
+  trial, or both sources reporting the same threshold, fires once.
+  `enableTrialAutoTriggers: false` still silences them.
+- **`getUserContext()`** now includes `trial` (the resolved trial view, the
+  one placements and grants decide with), `tiers`, `payment_failed`,
+  `payment_at_risk` and `instances` when they are held. The snapshot is a
+  copy, so changing it does not change SDK state.
+
+The headless server ports are unaffected, and the cross-language parity
+corpus is untouched.
+
+**Proving test.** `web-sdk/trial-reset-lifecycle.test.ts`.
+
+## 0.11.16
+
+### Build fix, part two: the npm declaration build resolves `openapi-fetch` too (no API change)
+
+**What changed.** 0.11.15 fixed the bundle step, but the public npm publish
+then failed one command later, in the declaration emit
+(`tsc -p tsconfig.build.json`). It reported
+`../server-node/client.ts(29,43): error TS2307: Cannot find module 'openapi-fetch'`,
+for the same reason as before: TypeScript resolves the bare import by walking
+up from `server-node/`, and the public repo installs the package only under
+`web-sdk/`. `web-sdk/tsconfig.build.json` now maps `openapi-fetch` to
+`./node_modules/openapi-fetch`.
+
+**npm users:** the 0.11.14 changes first reach npm in 0.11.16. Neither 0.11.14
+nor 0.11.15 was published to npm (both are on GitHub Packages, PyPI and
+crates.io). There is no behavior change across 0.11.14 through 0.11.16.
+
+**Landed in:** 0.11.16.
+**Fail-closed in:** n/a (build only).
+**Proving test:** the public repo's `release-npm.yml` build step for
+`v0.11.16`. It was reproduced locally by hiding the root `openapi-fetch` link
+to match the public layout: the declaration emit failed with the same TS2307
+before this change, and tsup, the declaration emit and rollup dts all pass
+after it.
+
+## 0.11.15
+
+### Build fix: the npm package publishes again (no API change)
+
+**What changed.** 0.11.14 was published to GitHub Packages, PyPI and
+crates.io, but the public npm publish of `@revturbine/sdk` failed at the bundle
+step: `Could not resolve "openapi-fetch"` from `server-node/client.ts`, which
+the `headless` entry re-exports. `openapi-fetch` has been bundled since BL-0354
+(0.11.14 was the first release to carry it). A bare import resolves by walking
+up from the importing file, so from `server-node/` it never reached
+`web-sdk/node_modules`, which is the only place the public repo installs it.
+`web-sdk/tsup.config.ts` now gives esbuild `web-sdk/node_modules` as a fallback
+`nodePaths` entry, so every file the SDK bundles resolves the SDK's own
+dependencies.
+
+**npm users:** everything listed under 0.11.14 below first reaches npm in
+0.11.15. There is no behavior change between 0.11.14 and 0.11.15. PyPI and
+crates.io get 0.11.15 in lockstep, with no change.
+
+**Landed in:** 0.11.15.
+**Fail-closed in:** n/a (build only).
+**Proving test:** the public repo's `release-npm.yml` bundle step (tsup +
+declarations) for `v0.11.15`. Locally, `web-sdk/tsup.config.ts` builds the
+bundle, and an esbuild probe confirms `nodePaths` resolves a bare import from a
+sibling directory that has no `node_modules` of its own.
+
+## 0.11.14
+
+This release carries the BL-0335 change below plus every entry that main held
+under "Unreleased" since 0.11.13 (BL-0381, BL-0382, BL-0366, BL-0375, BL-0369,
+BL-0352, BL-0354 and BL-0351).
+
+### `tenantId` is optional on a browser init with a `publicKey`; the key is the sole arbiter of the tenant (BL-0335, D-49)
+
+**What changed.** Before, a browser init needed both a `tenantId` and a
+`publicKey`. The public key is bound to exactly one tenant, and the control
+plane already resolved the tenant from the key alone, so the id was redundant
+configuration, and a wrong one was silently ignored. Now:
+
+- `RevTurbineInitOptions.tenantId` is **optional**. The minimal hosted init is
+  `{ publicKey, endpoint }`.
+- A key-only integration sends **no** `x-tenant-id`. It reads the tenant from
+  the key-authenticated Playbook delivery: the signed manifest's `tenant_id`
+  and the Playbook's own `tenant_id`. Until the first Playbook loads, the
+  tenant is unknown, so `getUserContext().tenant_id` and the event envelope's
+  `tenant_id` read `''` and the `/api/track` row omits `tenant_id`. The
+  control plane stamps the key's tenant regardless.
+- A **configured** `tenantId` that matches the key's tenant behaves exactly as
+  before: it is still sent, and every locally persisted key (anonymous id,
+  decision cache, caps, interaction state) is unchanged.
+- A **configured** `tenantId` that does **not** match the key's tenant is no
+  longer silently ignored, and it is not refused either (D-49). When the
+  key-authenticated delivery names another tenant, the SDK logs one warning
+  per init and adopts the key's tenant:
+
+  ```
+  [RevTurbine] tenantId <configured> does not match the key's tenant <key tenant>; using <key tenant>
+  ```
+
+  The signed manifest is activated (before, a manifest whose tenant differed
+  from the configured one was refused and the SDK fell back to the legacy
+  config fetch). After adoption, `getUserContext().tenant_id`, event envelopes
+  and the `x-tenant-id` the SDK still sends all carry the key's tenant. Local
+  storage keys stay namespaced by the configured id, so nothing persisted is
+  lost.
+- A key-only integration keys local state by a short hash of the public key
+  (`revturbine:pk-…:`), so rotating the key starts a fresh local namespace,
+  just as changing `tenantId` always did.
+- The theme loader (`fetchThemeOverride`) no longer sends the `'local'`
+  placeholder as a tenant header. `ThemeLoaderOptions.tenantId` is optional,
+  and the new `storageScope` option keeps the persisted-theme key.
+- `ConfigTargetDefaults.tenantId` is optional. Without it, the artifact's own
+  `tenant_id` is used.
+- Init now fails loudly when no tenant can be identified. It throws when
+  neither `publicKey` nor `tenantId` is present, and when a `local_only` init
+  has no `tenantId` and no `localRuntime.playbook`. With a local Playbook,
+  `local_only` still defaults the tenant to `'local'`, and a local Playbook's
+  `tenant_id` stays a guard behind the init option (plan 233 REQ-2): there is
+  no key there to arbitrate.
+
+**Server side (web #927).** The control plane uses the key's tenant
+unconditionally on every public-key lane. A tenant id that IS sent, whether as
+a header or as `tenant_id` in an event or interaction body, is diagnostic only:
+a mismatch is logged server-side and ignored. No request is refused for it.
+
+**Landed in:** 0.11.14 (`web-sdk` only; `server-python`/`server-rust` bumped
+in lockstep with no behavior change: the server ports authenticate with the
+server key and build a per-request context with a `tenant_id`, and they have
+no browser `publicKey` init option to relax).
+**Fail-closed in:** 0.11.14. An init with no identifiable tenant throws;
+before, it was a type error only, and JS callers got `undefined`. A mismatching
+configured tenant warns from 0.11.14; before, it was silent.
+**Proving test:**
+- `web-sdk/customer-side-tenant-optional.test.ts`: key-only init on both
+  delivery lanes (no tenant header; tenant adopted from the manifest and
+  Playbook), configured matching tenant unchanged (header sent, storage keys
+  byte-identical), a mismatching configured tenant warned once and the key's
+  tenant adopted on both lanes, the key-hash namespace, the init guards, and
+  the theme loader.
+- `web-sdk/init-options-exactness.test-d.ts`: a key-only init compiles.
+
+### server-node `setBuiltinDimensions()` — your backend sets built-in dimension values, with an `override` flag (BL-0382, rulings D-46 / D-47)
+
+**What changed.** Additive. The customer's backend can now SET built-in
+segment dimension values for a user, not just read the control plane's
+(D-46: "the customer's backend calling revturbine to set the dimension").
+
+- **server-node** — `RevTurbineServer.setBuiltinDimensions(userId, dimensions,
+  { override })` calls the widened `upsertServerUserContext`
+  (`POST /api/sdk/user-contexts`) with `{ user_id, builtin_dimensions,
+  override }` and the server key. Settable: `subscription_state`,
+  `trial_type`, `billing_health`, `activity_level`, `buyer_role`,
+  `email_type`, `region`, `device_type` (typed as
+  `ServerBuiltinDimensionsWrite`, each a closed vocabulary; `null` clears a
+  dimension). `seat_type` stays `assignSeatType`. It resolves to the stored
+  state — `seat_type_handle`, the customer-set `builtin_dimensions`, the
+  pinned `overrides`, `updated_at`. A refusal throws the new
+  `RevTurbineDimensionWriteError` (`status`, `requestId`, machine `code`,
+  typed `reason`: `invalid_request` / `unauthorized` / `forbidden` /
+  `unknown_dimension_value` / `request_failed`); it never carries the key.
+- **`override` (D-47).** `false` (default) is an UPDATE: the value is delivered
+  until a newer RevTurbine enrichment change supersedes it (last writer wins,
+  enrichment included), and writing a pinned dimension without the flag
+  unpins it. `true` is an OVERRIDE: the dimension is pinned and enrichment
+  never replaces it until you write it again without the flag or clear it.
+  The control plane applies this before delivery, so the browser SDK's client
+  context and `getBuiltinDimensions()` both return the result; the SDK
+  delivery rule and the parity goldens are unchanged.
+- **`assignSeatType(userId, handle, { builtinDimensions, override })`** can
+  write dimension values in the same upsert. Its `SeatAssignmentErrorReason`
+  gains `unknown_dimension_value` (a 422 with code `UNKNOWN_DIMENSION_VALUE`).
+  Its response now also carries `builtin_dimensions` and `overrides`.
+- **Python and Rust get no HTTP client** (unchanged: neither port has a
+  server-key transport). A backend on those stacks calls the endpoint itself.
+- Browser input types are untouched: `builtin_dimensions` is never a browser
+  write path.
+
+The `@revt-eng/*` pins move to `0.1.374`, which widens the operation
+(scaffold #431).
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** n/a (additive).
+**Proving test:** `tests/server-node-set-builtin-dimensions.test.ts`,
+`tests/server-node-assign-seat-type.test.ts`.
+
+### Behaviour change: the browser SDK ignores app-set `builtin_dimensions` (BL-0381, ruling D-46)
+
+**What changed.** Trust in a built-in dimension value is decided by *party*
+(Kent, D-46): the browser client never asserts one, the customer's server may,
+and RevTurbine's own enrichment is optional. `builtin_dimensions` therefore
+joins `seat_type_handle`, `activity_score` and `activity_score_computed_at`
+as a server-assigned key in the browser SDK.
+
+- **Types.** `builtin_dimensions` is omitted from `RevTurbineUserContext`,
+  `RevTurbineUpdateInput` and `IdentifyContextInput`, so
+  `update({ builtin_dimensions })`, `setUserContext({ builtin_dimensions })`,
+  `identify(id, { builtin_dimensions })` and `user: { builtin_dimensions }`
+  no longer compile.
+- **Runtime.** Every browser entry point drops the key and warns with the
+  server-assigned diagnostic (`update()`, `identify()`, `setUserContext()`,
+  the `user` init option). A persisted `local_only` state blob that carries it
+  is purged on restore, and a server-action result that echoes it is stripped
+  silently. Before this change, 0.11.12 and 0.11.13 merged an app-set value
+  through `setUserContext()` and the `user` option. An app could then claim
+  any built-in segment (for example `rt.subscription_state.paid`) from the
+  browser.
+- **The one browser source** is the authenticated
+  `GET /api/sdk/client-context` delivery (`fetchClientContext`, or a
+  `clientSession` minter). Its values overlay per leaf exactly as before.
+  `getUserContext()` still returns the held value.
+- **`local_only`.** Built-in segment *definitions* are still synthesized for
+  a local Playbook (BL-0365), so chips and rules naming `rt.*` segments stay
+  valid. Their *values* no longer come from the app: **a browser `local_only`
+  app can no longer target built-ins unless a server-provided context
+  delivers them.** With no delivery every `rt_*` trait is absent and the
+  built-in segments fail closed (PD-4). `rt.registration_state.*` still
+  resolves from the identified id alone.
+- **Unchanged: server SDKs.** They are the customer's server. Their overlay
+  inputs stay: server-node's `createStaticProviders({ userContext:
+  { builtin_dimensions }, serverBuiltinDimensions })`, Python's
+  `builtin_dimensions` / `server_builtin_dimensions` and Rust's
+  `builtin_dimensions` / `server_builtin_dimensions`. Parity goldens are
+  unchanged.
+
+This supersedes the part of BL-0352 (below) that made `update()` apply
+`builtin_dimensions`. That change never shipped.
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** the same release. The compile-time omission and the
+runtime drop ship together.
+**Proving test:**
+- `web-sdk/update-keys-exhaustiveness.test-d.ts` (`pnpm check:types:exact`):
+  `builtin_dimensions` is in the server-assigned set.
+- `web-sdk/identify-guardrails.test.ts`: describe block
+  `builtin_dimensions never enters the browser context from the app`.
+- `web-sdk/local-builtin-segments.test.ts`: `chip … with app-set … fails
+  closed` (and the delivered cases still match).
+- `web-sdk/customer-side-rt-entitlement-gate.test.ts`: `denies when the app
+  sets builtin_dimensions itself via update()`.
+- `web-sdk/customer-side-client-context.test.ts`: `holds exactly the
+  delivered value; an app-set value never reaches the context`.
+
+### Server SDKs get the control plane's built-in dimensions: `getBuiltinDimensions()` + a server overlay (BL-0366, plan 279 PD-3)
+
+**What changed.** Additive. Before this, a server-side decision never saw the
+control plane's Subscription State, Trial Type, Activity State, Seat Type or
+Buyer Role. The Python and Rust ports stamped `rt_*` traits only from the
+app-supplied `builtin_dimensions`, and the fetch that delivers the server's
+values existed only in the browser SDK's client-context lane.
+
+- **server-node** — `RevTurbineServer.getBuiltinDimensions(userId)` calls
+  `getServerUserBuiltinDimensions`
+  (`GET /api/sdk/user-contexts/{userId}/builtin-dimensions`) through the
+  generated typed client with the server key the client already holds. It
+  resolves to `{ tenant_id, user_id, builtin_dimensions, resolved_at }`
+  (re-exported as `ServerUserBuiltinDimensions`). The tenant comes from the
+  key: it is not a parameter, and no tenant header is sent. A refusal throws
+  the new `RevTurbineBuiltinDimensionsError` (`status`, `requestId`, machine
+  `code`, typed `reason`: `invalid_request` / `unauthorized` / `forbidden` /
+  `request_failed`). It never carries the key.
+- **The overlay (all three ports).** `createStaticProviders` takes
+  `serverBuiltinDimensions` (from `@revt-eng/core`, re-exported by server-node
+  together with `applyServerBuiltinDimensions`). Python's
+  `create_static_providers(server_builtin_dimensions=…)` and the
+  `RevTurbineCustomerSdk` user context key `server_builtin_dimensions` take
+  the same object. So do Rust's `StaticProviderOptions::server_builtin_dimensions`
+  and `sdk::UserContext::server_builtin_dimensions`, plus the
+  `apply_server_builtin_dimensions` helper in both ports. The object is
+  overlaid per key on the app-set `builtin_dimensions` before segment
+  membership is evaluated. A delivered leaf wins over the app's value (PD-3),
+  and an app-set leaf the server did not deliver is kept. This is the overlay
+  the browser SDK already applies to a client-context delivery. Without a user
+  context it is ignored, because nothing is evaluated then.
+- **Python and Rust get no HTTP client.** Neither port has a transport or a
+  server-key client (BL-0354), and this change does not add one. The app's
+  backend reads the endpoint itself (or through server-node) and passes the
+  response's `builtin_dimensions` in.
+
+Rust callers that build `StaticProviderOptions` or `sdk::UserContext` as a
+full struct literal without `..Default::default()` must add the new field.
+
+The `@revt-eng/*` pins move to `0.1.373`, which adds the operation and the
+core overlay (scaffold #430).
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** n/a (additive).
+**Proving test:** `tests/server-node-get-builtin-dimensions.test.ts`,
+`server-python/tests/adapters/test_static.py`,
+`server-rust/tests/static_providers.rs`, and the parity fixtures
+`segment_membership_server_overlay_wins` / `segment_membership_server_overlay_demotes`.
+
+### `RevTurbineProvider` disposes the previous SDK instance on an `options` change (BL-0375)
+
+**What changed.** `RevTurbineProvider`'s init effect creates a new SDK instance
+whenever the `options` prop (or `bootstrapPlacements`) changes identity, but its
+cleanup previously only flipped an internal `mounted` flag — it never called
+`dispose()` on the instance it was replacing. A host that rebuilds `options` on
+every render (an unmemoized `options={{ ... }}` literal, or an object built in
+an un-annotated `useMemo` with an unstable dependency — the shape web's dogfood
+provider had until web #944) therefore re-initialized on every render and
+leaked every earlier instance's flush-interval timer, `pagehide` /
+`visibilitychange` listeners, and any buffered telemetry.
+
+The cleanup now calls the previous instance's existing `dispose()` (flushes
+pending telemetry, detaches its listeners and timer) before the next render's
+instance is constructed. The re-init contract is unchanged: a new `options`
+object identity — even one with identical content — still creates a new SDK
+instance; that documented behavior was never the bug, the leak was. When a new
+`options` object is recreated with the same content as the previous one, the
+provider now also logs a one-time (per mounted provider lifetime) development
+warning pointing integrators at memoizing `options`, in addition to the
+existing every-time identity-change warning.
+
+**Landed in:** no release — no signature changed; `dispose()` on
+`RevTurbineCustomerSdk` already existed (documented for manual SPA-unmount
+teardown) and is now also called automatically by the provider.
+**Fail-closed in:** n/a — purely a leak fix; no customer-visible API changed.
+**Proving test:**
+`web-sdk/react/RevTurbineProvider.dispose-on-options-change.test.tsx`.
+
+### Behaviour fix: server SDKs stop serving segment-chipped payloads to every user (BL-0369)
+
+**What changed.** On the server lanes, every configured Playbook segment
+counted as a segment the user was in. That covered the Python and Rust
+`RevTurbineCustomerSdk`, `LocalRuntime`, and server-node's
+`LocalEvaluationServer` fed by `createStaticProviders`. So a payload chipped
+to any segment was shown to every user, and an entitlement rule targeted at
+any segment granted to every user on the plan. This included the generated
+built-in segments (`rt.<dimension>.<value>`, e.g.
+`rt.subscription_state.paid`) that hosted Playbooks now export. The browser
+SDK was not affected.
+
+A user is now in a segment only when one of these is true, the same rule the
+browser SDK applies:
+
+- your app passed its handle in `segment_ids` (Python / Rust) or
+  `segmentIds` (`createStaticProviders`), or
+- its predicates match the user's targeting traits. Those traits are built
+  from `custom`, the plan, and the reserved `rt_<dimension>` traits.
+  `rt_<dimension>` traits come **only** from `builtin_dimensions`, which the
+  server sets (plan 279 PD-3). For experiment segments, the user's
+  `experiments` assignments decide enrollment.
+
+Anything else fails closed. An unset dimension, a trait the user doesn't
+carry, or a chip that names an unknown segment serves nothing (PD-4).
+
+New inputs (all additive): `custom`, `builtin_dimensions` and `experiments`
+on the Python `UserContext` and the Rust `UserContext` struct. `segment_ids`
+now also drives chips and rules, not just the catalog helpers.
+`createStaticProviders` gets `segmentIds` and `userContext` from
+`@revt-eng/core`. A side fix: the Python and Rust rules providers now carry
+`segment_dimensions` and the Playbook's `format_version`, like TypeScript.
+Without `segment_dimensions`, a rule targeted at segments in two dimensions
+would have matched on either one once membership became real.
+
+**Impact on existing integrations.** This is a correctness fix, but you may
+notice it. If a server-side integration shows segment-chipped payloads or
+grants segment-targeted entitlements, and it passes none of the inputs
+above, those payloads now **stop showing** and those rules **stop
+granting**. They were being over-served before. To keep serving users who
+really are in the segment, pass `segment_ids` for segments your app
+resolves, and `builtin_dimensions` / `custom` for predicate and built-in
+segments. The Rust `UserContext` struct gains three fields. A struct literal
+that does not end in `..Default::default()` needs them added.
+
+The `@revt-eng/*` pins move to `0.1.372`: scaffold #429 is the BL-0369 core
+fix, and it carries scaffold #428 (0.1.371: the `billing_health`
+built-in dimension leaf, BL-0317, and `seat_type_handle` becoming
+required-nullable on `ServerUserContextUpsert`, BL-0367). The vendored port
+types follow: in Python, `ServerUserContextUpsert.seat_type_handle` loses its
+default; in Rust, `ClientContextBuiltinDimensionsBillingHealth` is added.
+
+**Landed in:** 0.11.14 (`@revt-eng/core` 0.1.372 carries
+the scaffold BL-0369 fix).
+**Fail-closed in:** the same release.
+**Proving test:**
+- `tests/parity/fixtures/segment_membership_{no_inputs,builtin_and_traits,explicit_ids}.json`
+  (TS == Python == Rust).
+- `server-python/tests/adapters/test_static.py` and
+  `server-rust/tests/static_providers.rs` (segment membership tests).
+- `tests/server-node-local-segment-membership.test.ts`.
+
+### `update()` carries `experiments` and `builtin_dimensions`; server-computed keys are dropped at every browser entry point (BL-0352, ruling D-36)
+
+**What changed.** `update()`'s exhaustiveness check never ran. It was an
+`expectTypeOf` inside a vitest `.test.ts`, and vitest does not typecheck. Four
+fields had reached `RevTurbineUpdateInput` without reaching
+`RECOGNIZED_UPDATE_KEYS`, so `update()` accepted them at compile time and
+silently dropped them at runtime. Each one now has an explicit disposition:
+
+- *(`builtin_dimensions` superseded by BL-0381 above: it is server-assigned
+  and dropped.)* `experiments` and `builtin_dimensions` are **now applied**
+  by `update()`.
+  The app may supply experiment assignments it already knows
+  (`runtime/experiment-assignment.md` §3, plan 183), and it may seed built-in
+  dimensions, for example in `local_only` mode. The client-context overlay
+  still wins when it is present (`targeting-studio-ui.md` §4.1). Before this
+  change, `update({ experiments })` compiled and did nothing.
+- `activity_score` and `activity_score_computed_at` are **server-computed**.
+  The control plane's hourly activity-score refresh writes them (plan 180),
+  and the browser receives only the derived `activity_level` dimension. Like
+  `seat_type_handle` (BL-0351), they are now omitted from
+  `RevTurbineUserContext`, `RevTurbineUpdateInput` and `IdentifyContextInput`.
+- `setUserContext()` and the `user` init option now **drop server-assigned
+  keys at runtime** (`seat_type_handle`, `activity_score`,
+  `activity_score_computed_at`) and report them. `identify()` and `update()`
+  already dropped them, and now report them with a server-assigned warning
+  that names the backend as the writer, not the "pass it under `custom`"
+  hint. Before this change, a plain-JS `setUserContext({ seat_type_handle })`
+  merged the key into the held context, and local mode persisted it. A state
+  blob persisted before this change is purged of those keys when it is
+  restored. A server-action result that echoes them back is stripped without
+  a warning.
+- New exported types `RecognizedUpdateKey` and `RecognizedIdentifyKey`
+  (additive) back a real compile-time derivation in
+  `web-sdk/update-keys-exhaustiveness.test-d.ts`, which
+  `pnpm check:types:exact` compiles. A future `UserContext` field fails the
+  build until it is added to the runtime list or omitted as server-assigned.
+
+**Deferred to `0.12.0`:** `setUserContext()` still takes
+`RevTurbineUserContext` without `Exact<>`, so other undeclared keys that
+arrive through a variable are not rejected at compile time. Adding `Exact<>`
+would break callers that pass a wider object today. `IdentifyContextInput`
+also still declares 11 keys that `identify()` drops with a warning (`trial`,
+`tiers`, `experiments`, …). The type-test pins that list, so it cannot grow
+silently. Narrowing the type is a breaking change and waits for the minor.
+
+The `@revt-eng/*` pins move to `0.1.370` (scaffold #427: discovery-owned
+`SurfaceSlotSchema.slot_name`). That field now appears in the generated client
+types and the vendored Python and Rust port types. The SDK does not write it.
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** the same release. The compile-time omission and the
+runtime drop at all four entry points both ship in it.
+**Proving test:**
+- `web-sdk/update-keys-exhaustiveness.test-d.ts` (`pnpm check:types:exact`).
+- `web-sdk/identify-guardrails.test.ts`: describe blocks
+  `server-computed keys never enter the browser context`,
+  `setUserContext() drops server-assigned keys at its runtime boundary` and
+  `update() carries app-owned experiments` (renamed by BL-0381).
+
+### server-node `assignSeatType()` writes a user's seat type (BL-0354, plan 279 TASK-16a, ruling D-36)
+
+**What changed.** Additive. `RevTurbineServer` (server-node) gains
+`assignSeatType(userId: string, seatTypeHandle: string | null)`. It calls
+`upsertServerUserContext` (`POST /api/sdk/user-contexts`) through the generated
+typed client with the server key the client already holds. The request body is
+exactly `{ user_id, seat_type_handle }`. `null` clears the assignment. The
+tenant comes from the key: it is not a parameter, and no tenant header is sent.
+It resolves to the stored assignment
+`{ tenant_id, user_id, updated_at, seat_type_handle }` (re-exported as
+`ServerUserContextAssignment`).
+
+A refusal throws the new `RevTurbineSeatAssignmentError`. It carries `status`,
+`requestId`, the control plane's machine `code` when present, and a typed
+`reason`: `unknown_seat_type` (422: the handle is not one of the tenant's seat
+types), `forbidden` (403: the credential is not a server key), `unauthorized`
+(401), `invalid_request` (400) or `request_failed`. Like
+`RevTurbineClientSessionError`, it never carries the key or the free-text
+response message.
+
+Per D-36 the seat assignment is server-written only, so there is no browser SDK
+surface for this. The Python and Rust ports have no HTTP client or server-key
+client, only the vendored `ServerUserContextUpsert` / `ServerUserContextAssignment`
+models, so they gain no helper.
+
+The `@revt-eng/*` pins move to `0.1.369`, which adds that operation to the
+external contract (scaffold #425).
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** n/a (additive).
+**Proving test:** `tests/server-node-assign-seat-type.test.ts`.
+
+### `seat_type_handle` is server-assigned and never a browser input (BL-0351, plan 279 TASK-16a, ruling D-36)
+
+**What changed.** Scaffold `0.1.368` adds `UserContextSchema.seat_type_handle`,
+the user's persisted seat-type assignment. Per D-36 it has exactly two writers:
+the tenant's backend (a server-key user-context upsert) and RevTurbine's own
+server-side enrichment in hosted mode. The browser never writes it. Without a
+change here the new field would have flowed into the browser input types
+through `UserContextInput`. Instead:
+
+- `RevTurbineUserContext` omits `seat_type_handle`. So do
+  `RevTurbineUpdateInput`, which derives from it, and `IdentifyContextInput`.
+  `identify()`, `update()` and the `user` init option reject the key at compile
+  time, including when it arrives through a variable (`Exact<…>`).
+  `setUserContext()` rejects it in an object literal.
+- The key stays out of the runtime recognized-key lists, so a plain-JS caller's
+  `seat_type_handle` is dropped at the `identify()`/`update()` boundary and
+  reported by the existing unrecognized-key warning. It is never merged into the
+  held context.
+- The browser receives the **resolved** seat type as
+  `builtin_dimensions.seat_type` / `builtin_dimensions.buyer_role` from the
+  client-context fetch (plan 279 TASK-16, web), unchanged here.
+
+No released SDK type ever carried `seat_type_handle`, so nothing an
+integration compiles today stops compiling. The `@revt-eng/*` pins move to
+`0.1.368`. That version also adds `SeatTypeSchema.is_buyer` (default `false`),
+which now appears in the vendored Python and Rust port types.
+
+A server-node `assignSeatType(userId, handle | null)` helper was **not** in this
+change, because the server-key operation it wraps (`upsertServerUserContext`,
+`POST /api/sdk/user-contexts`, plan 279 TASK-15a) was not yet in the published
+external contract. It shipped with scaffold `0.1.369` (see the BL-0354 entry
+above).
+
+**Landed in:** 0.11.14. This PR bumps pins only.
+**Fail-closed in:** the same release (compile-time rejection; runtime drop).
+**Proving test:**
+- `web-sdk/user-context-exactness.test-d.ts`: the `@ts-expect-error` block
+  "Server-assigned fields" (`pnpm check:types:exact`).
+- `web-sdk/identify-guardrails.test.ts`: describe block
+  `seat_type_handle never enters the browser context`.
+
 ## 0.11.13
 
 ### Slot lifecycle events carry the slot's `route` (BL-0207, ruling D-30)