@revturbine/sdk 0.11.1 → 0.11.3

package/CHANGELOG.md

@@ -47,6 +47,139 @@ also require a changelog entry.
 
 ---
 
+## 0.11.3
+
+### `placement_interaction` now carries `rule_handle` (BL-0182)
+
+**What changed.** #527 (BL-0062) stamped `rule_handle` at every verdict emit
+site by reading `decision.output.rule_id`, but `placement_interaction` is not
+a lifecycle event and does not spread `placementLifecycleBase` — its
+placement keys are all optional, because a bare `trackTreatmentInteraction`
+caller may supply none of them — so the click between exposure and outcome
+was the one step of the funnel with no rule key. That is the step
+click-through and CTR are computed over: the funnel was sliceable by rule at
+both ends and not in the middle.
+
+Five emit sites now reach the same stamped payload: `trackTreatmentInteraction`
+(the projection itself), `PlacementController.trackInteraction`
+(dismiss / remind_me_later / cta_clicked / cta_completed — and therefore every
+React hook and `useSurfaceSlot` / `FixedSurfaceSlot` click handler built on
+it), `PlacementController.fireImpression`, `trackOutputInteraction`
+(output-addressed `convert()` / `dismiss()` / `snooze()`), and the
+server-action `trackResult` resolver.
+
+Spread, not set: `rule_handle` is **absent** when no decision was in scope
+(a bare `trackTreatmentInteraction` call with no placement context), and
+`null` on the wire means "a rule was selected and none matched" — conflating
+the two would poison the slice's coverage numbers. The unknown-output branch
+of `trackOutputInteraction` stamps nothing on purpose: no decision from this
+SDK produced that output, so there is no rule to name.
+
+Companion to `revturbine-scaffold#391`, which added `rule_handle` to the
+`placement_interaction` payload contract and `ruleHandle` to
+`RevTurbineTreatmentInteractionInput` (published as `@revt-eng/*` v0.1.339,
+pinned in this release).
+
+**No wire-shape change beyond the new optional field.** `rule_handle` is
+optional-and-nullable on the schema side (#391), which keeps every
+already-deployed SDK out of `quarantineVerdict`. `@public` signatures are
+unchanged (`web-sdk/generated/public-api.json` untouched) and
+`flushInteractionQueue` still maps the treatment-interaction record field by
+field, so `ruleHandle` never reaches a customer webhook.
+
+**Python and Rust are unaffected.** Neither port emits events.
+
+**Landed in** `0.11.3` (BL-0182, #530).
+
+**Fail-closed in** not applicable — additive field, nothing old is rejected.
+
+**Proving test:** `web-sdk/customer-side-canonical-interaction.test.ts`.
+
+---
+
+### A gate no longer paywalls forever when it loses the cold-start config race (BL-0179)
+
+**What changed.** BL-0177 (below) split `config_unavailable` into a transient and
+a terminal state for **placements** and left `checkEntitlement` on the old
+behaviour. So the same cold-start race denied entitlements instead: while the
+Playbook load was in flight, `checkEntitlement` — and therefore `can()`,
+`gate()`, `useCan`, `useEntitlement` and `useGatedAction` — returned the
+fail-closed deny with reason `config_unavailable`, which is indistinguishable
+from a rule denial. A gate mounted before config resolution rendered its paywall
+and never re-evaluated, hiding a feature the user had paid for.
+
+The entitlement path now takes the same two-state split:
+
+| state | when | behaviour |
+|---|---|---|
+| **transient** | a Playbook load is in flight (`getPlaybookLoadState() === 'loading'`) | `checkEntitlement` waits for it (bounded, 4s) and re-evaluates. If the load outruns that bound, `EntitlementGate` **parks** the deny instead of publishing it — `result` stays `null`, `denied` stays `false`, `isLoading` stays `true`, and **no** `gate_evaluated` is emitted — then re-checks when the load settles, at most twice per cycle. |
+| **terminal** | no config provider is configured, or the load settled without a config | unchanged: fail-CLOSED deny, reason `config_unavailable` in Server mode / `entitlement_not_in_playbook` in local mode, with its `resolution_failure` diagnostic and exactly one `gate_evaluated` carrying the verdict (and its `rule_handle`). |
+
+The emission rule is the one worth stating plainly: **exactly one
+`gate_evaluated` per settled verdict, and none for the transient state** — a
+lost race is not an evaluation and must not enter the gate funnel as a denial.
+
+**No API, wire or reason-code change.** `@public` signatures are unchanged
+(`web-sdk/generated/public-api.json` is untouched), both reason codes keep their
+meanings, and `tests/reason-contract.json` is unchanged. A `limited`-but-allowed
+result is untouched; the fail-closed contract for terminal unavailability is
+untouched.
+
+**Python and Rust are unaffected by design**, for the same reason as BL-0177:
+both take the Playbook as a required constructor argument, do no I/O, and have no
+not-yet-loaded window.
+
+**Landed in.** `0.11.3` (BL-0179, #529).
+
+**Fail-closed in.** Not applicable — terminal behaviour is unchanged; only the
+transient race is now absorbed.
+
+**Proving test.** `web-sdk/react/useCan.config-race.test.tsx` (a gate mounted
+mid-race ends on the rule's verdict, allow and deny) and
+`web-sdk/entitlement-config-race.test.ts` (both states, the emission rule, and
+the bounded post-bound retry for `PlacementController` and `EntitlementGate`,
+reached by injecting a `0` wait bound rather than with fake timers).
+
+---
+
+### A slot no longer paints its fallback forever when it loses the cold-start config race (BL-0177)
+
+**What changed.** `getPlacementDecision` returns `config_unavailable` when the
+Playbook has not arrived, uncached, specifically so a retry can succeed — but
+nothing retried. `useSurfaceSlot` / `FixedSurfaceSlot` decide once per mount, so
+on a cold `revturbine_server` load, whenever the first decision beat the two-hop
+bootstrap → `/api/sdk/config` chain, the slot rendered its `fallback`
+permanently and every integration had to hand-roll a retry.
+
+`config_unavailable` now has two distinct states and the SDK handles each:
+
+| state | when | behaviour |
+|---|---|---|
+| **transient** | a Playbook load is in flight | `getPlacementDecision` waits for it (bounded, 4s) and re-resolves. If the load outruns that bound, `PlacementController` re-decides when it settles — at most twice per load cycle. The slot stays in `isLoading` meanwhile and emits **no** `placement_resolved` / `slot_empty`: a lost race is not a resolution and must not enter the funnel as one. |
+| **terminal** | no config provider is configured, or the load settled without a config | unchanged from before: the decision is `config_unavailable`, `visible: false`, uncached, with the resolution-failure diagnostic and the lifecycle + slot events. Bounded retries mean it settles rather than spinning. |
+
+**No API, wire or reason-code change.** `config_unavailable` is still the reason
+code, the decision shape is untouched, and `tests/reason-contract.json` is
+unchanged. Customer code that already hand-rolls a retry keeps working — it is
+now redundant, not wrong.
+
+**Python and Rust are unaffected by design.** Both ports take the Playbook as a
+required constructor argument and raise on a missing or malformed one
+(`server-python/src/revturbine/sdk.py` `__init__`, `server-rust/src/sdk.rs`
+`new`), perform no I/O, and never emit `config_unavailable` — there is no
+not-yet-loaded window to retry. This is a browser/hosted-mode state only.
+
+**Landed in.** `0.11.3` (BL-0177, #528).
+
+**Fail-closed in.** Not applicable — the terminal behaviour is unchanged; only
+the transient race is now absorbed.
+
+**Proving test.** `web-sdk/placements/FixedSurfaceSlot.config-race.test.tsx`
+(both states), plus `e2e/journey.transport.spec.ts`, whose two hand-rolled retry
+loops were deleted — a retry loop reappearing there is the regression signal.
+
+---
+
 ## 0.11.1
 
 ### The generated schema *types* gained their `Playbook*` names (BL-0165)