@revturbine/sdk 0.11.19 → 0.11.20

package/CHANGELOG.md

@@ -47,6 +47,48 @@ also require a changelog entry.
 
 ---
 
+## 0.11.20
+
+### One entitlement answer for browser and server, with Entitlement Mirroring; Access Gates only fire while denied (D-60, D-61)
+
+**What changed.** Behaviour change in every port. Browser and server now run
+the same evaluation on the same inputs: the browser is trusted for
+interaction, and the server verifies.
+
+- **One effective entitlement (ts/py/rs/web).** Every entitlement check runs
+  the shared core evaluator over the Playbook and the user context (plan,
+  segments, usage, reverse-trial grants), then merges app-supplied data. Server
+  runtimes previously used a separate rule path that ignored reverse-trial
+  grants and allowed everything when the Playbook had no entitlement rules.
+  **Server-side results change for the live design partner:** a configured
+  entitlement with no rule for the user's plan is now denied on the server
+  too, and reverse-trial grants are honoured there.
+- **Entitlement Mirroring.** `UserContext.entitlements` accepts a boolean or a
+  grant (`status`, `limit`, `used`), and an app entitlement provider's
+  entries count as app data. By default the app's data wins;
+  `entitlementMerge` (`entitlement_merge` in Python and Rust) sets provider-level
+  `precedence` and per-field overrides. Browser-supplied data shapes the UI;
+  the server re-check stays authoritative.
+- **Unknown entitlement handles fail closed.** A handle neither the Playbook
+  nor the app knows is denied with `entitlement_not_in_playbook`, warned once,
+  and reported (browser telemetry; `onUnknownEntitlement` on the server).
+  0.11.19 returned `entitlement_not_found_default_allow`.
+- **Access Gates (D-60).** A gate placement appears only in an Access Gate
+  slot and fires only while its entitlement is denied or limited (a
+  tier-scoped gate below its tier counts as limited). Placement gates read the
+  same effective entitlements `checkEntitlement` returns.
+- **Reason codes.** New entitlement reason `entitlement_mirrored`; new
+  placement reasons `entitlement_not_denied` and `gate_outside_access_gate`.
+- **Scaffold pin 0.1.402 → 0.1.409** (revturbine-scaffold #462, #465
+  and #468; vendored `types.py` / `types.rs` refreshed).
+
+**Landed in** 0.11.20. **Fail-closed in** 0.11.20.
+
+**Proving tests.** `web-sdk/entitlement-mirroring.test.ts`; the D-60/D-61
+blocks in each port's resolver and runtime tests; parity fixtures
+`placement_slot_selection_is_category_first` and
+`placement_category_interactions`.
+
 ## 0.11.19
 
 ### Placement decisions rank category first; caps run before the pick; overall presentation cap rules enforced (D-59, BL-0536)

package/dist/growthbook.d.ts

@@ -293,6 +293,16 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 
+/** A mirrored grant on `UserContext.entitlements`: a boolean, or a grant-shaped record. */
+type MirroredEntitlement = boolean | {
+    status?: string;
+    allowed?: boolean;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    reason?: string;
+};
+
 /**
  * User context lifecycle — pure functions for building, merging,
  * and deriving targeting state from user context + RevTurbineConfig.
@@ -315,7 +325,12 @@ interface UserContextSnapshot {
      */
     plan?: string | UserPlanContext;
     custom?: Record<string, JsonValue>;
-    entitlements?: Record<string, boolean>;
+    /**
+     * App-supplied entitlement data keyed by handle — a boolean or a grant
+     * (D-61 Entitlement Mirroring). Merged with the Playbook evaluation by the
+     * effective-entitlement core; flattened into segment traits as a boolean.
+     */
+    entitlements?: Record<string, MirroredEntitlement>;
     usage?: Record<string, UserUsageEntry>;
     personalization?: Record<string, JsonValue>;
     /** Canonical experiment-handle to variant-handle assignments. */

package/dist/headless.d.ts

@@ -27720,6 +27720,52 @@ type PlaybookOption = {
     exportedConfig: RevTurbineConfig;
 };
 
+/**
+ * Effective entitlements — the ONE answer every SDK runtime uses (D-61,
+ * Kent 2026-10-06).
+ *
+ * The shared evaluator (`deriveLocalEntitlementFromConfiguredRules`) decides
+ * each entitlement from the Playbook + user context. An app may then enrich
+ * that answer with its own data ("Entitlement Mirroring"): grants on
+ * `UserContext.entitlements` and/or an app-registered entitlement provider.
+ * The two are merged with a configurable precedence — provider level
+ * (`precedence`, default `'app'`) with optional per-field overrides.
+ *
+ * Browser and server SDKs run this same function on the same inputs: the
+ * browser result shapes interaction, the server result verifies it.
+ *
+ * An entitlement handle neither the Playbook nor the app knows is DENIED
+ * (`entitlement_not_in_playbook`) and flagged `unknownHandle`, so the runtime
+ * can warn and report it.
+ */
+
+/** Which side wins a merge: the app's own data, or the Playbook evaluation. */
+type EntitlementSource = 'app' | 'playbook';
+/** Fields that can be given their own precedence. `status` carries `allowed` and `reason` with it. */
+type EntitlementMergeField = 'status' | 'limit' | 'used' | 'remaining';
+interface EntitlementMergeOptions {
+    /** Provider-level precedence. Default `'app'`: app-supplied data wins. */
+    precedence?: EntitlementSource;
+    /** Per-field overrides of `precedence`. */
+    fields?: Partial<Record<EntitlementMergeField, EntitlementSource>>;
+}
+/** A mirrored grant on `UserContext.entitlements`: a boolean, or a grant-shaped record. */
+type MirroredEntitlement = boolean | {
+    status?: string;
+    allowed?: boolean;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    reason?: string;
+};
+/** The trial facts reverse-trial grants depend on (`UserTrialStatus` subset). */
+interface ReverseTrialView {
+    in_trial?: boolean;
+    trial_type?: string;
+    /** The user's BASE plan while on a reverse trial. */
+    plan_handle?: string;
+}
+
 /**
  * User context lifecycle — pure functions for building, merging,
  * and deriving targeting state from user context + RevTurbineConfig.
@@ -27742,7 +27788,12 @@ interface UserContextSnapshot {
      */
     plan?: string | UserPlanContext;
     custom?: Record<string, JsonValue>;
-    entitlements?: Record<string, boolean>;
+    /**
+     * App-supplied entitlement data keyed by handle — a boolean or a grant
+     * (D-61 Entitlement Mirroring). Merged with the Playbook evaluation by the
+     * effective-entitlement core; flattened into segment traits as a boolean.
+     */
+    entitlements?: Record<string, MirroredEntitlement>;
     usage?: Record<string, UserUsageEntry>;
     personalization?: Record<string, JsonValue>;
     /** Canonical experiment-handle to variant-handle assignments. */
@@ -28023,6 +28074,13 @@ interface EntitlementUsageEntry {
     reset_date?: string;
 }
 interface EntitlementProviderState {
+    /**
+     * D-61: `'playbook_default'` marks entries the static adapter fills with a
+     * blanket default policy. Those are NOT app data and never override the
+     * Playbook evaluation; entries from any other provider are app-mirrored
+     * data and merge with it per the runtime's precedence.
+     */
+    origin?: 'playbook_default';
     /**
      * All entitlement results keyed by entitlement handle.
      * Each entry carries status ('allowed' | 'limited' | 'denied') so the
@@ -28496,7 +28554,7 @@ interface DecisionEngineOptions {
     enableCapsEnforcement?: boolean;
     /** Enable category pipeline for local-mode priority ordering. Default: false. */
     enableCategoryPipelineLocalMode?: boolean;
-    /** Default entitlement policy when no provider or entry found. Default: 'allow'. */
+    /** Default entitlement policy when no provider or entry found. Default: 'deny' (fail closed, D-61). */
     defaultEntitlementPolicy?: 'allow' | 'deny';
 }
 interface EntitlementCheckResult {
@@ -29346,6 +29404,20 @@ interface LocalRuntimeOptionsBase {
     impressionStore?: ImpressionHistoryStore;
     /** Decision engine behavior flags. */
     engineOptions?: DecisionEngineOptions;
+    /**
+     * D-61 Entitlement Mirroring: the user context's own entitlement data
+     * (`UserContext.entitlements`), merged with the Playbook evaluation.
+     */
+    userEntitlements?: Record<string, MirroredEntitlement>;
+    /** D-61: the user's trial status, so reverse-trial grants evaluate exactly as in the browser. */
+    trialStatus?: ReverseTrialView;
+    /** D-61: how app-supplied entitlement data merges with the Playbook result. Default: app wins. */
+    entitlementMerge?: EntitlementMergeOptions;
+    /**
+     * Called once per entitlement handle that neither the Playbook nor the app
+     * knows (it is denied). The runtime also logs a warning. Wire telemetry here.
+     */
+    onUnknownEntitlement?: (handle: string) => void;
     /** Interaction tracker options. */
     interactionOptions?: Partial<Pick<InteractionTrackerOptions, 'defaultDismissCooldownMs' | 'defaultRemindLaterMs'>>;
 }
@@ -29366,6 +29438,11 @@ declare class LocalRuntime {
     readonly impressionHistory: ImpressionHistory;
     private readonly playbook;
     private readonly registeredPlacements;
+    private readonly userEntitlements;
+    private readonly trialStatus;
+    private readonly entitlementMerge;
+    private readonly onUnknownEntitlement;
+    private readonly reportedUnknownEntitlements;
     private userId;
     constructor(options: LocalRuntimeOptions);
     /**
@@ -29403,7 +29480,12 @@ declare class LocalRuntime {
      */
     getPlacement(config: RevTurbinePlacementRequestConfig$1): Promise<RevTurbinePlacementDecision | null>;
     /**
-     * Check entitlement access locally using RevTurbineConfig rules.
+     * Check entitlement access locally (D-61): the shared evaluator decides
+     * from the Playbook + user context, then app-mirrored data (user-context
+     * grants and any app entitlement provider) merges per the runtime's
+     * precedence (default: app wins). The browser SDK runs the same function on
+     * the same inputs, so the server verifies exactly what the browser showed.
+     * An entitlement nobody knows is denied, warned and reported.
      */
     checkEntitlement(handle: string, context?: RevTurbineEntitlementContext): Promise<EntitlementResult>;
     /**
@@ -29466,7 +29548,11 @@ declare class LocalRuntime {
      */
     private slotRecordForConfig;
     private buildPlacementResolver;
-    private deriveEntitlementFromConfig;
+    /** Evaluator inputs from the resolved providers — the same facts the browser SDK uses. */
+    private effectiveBase;
+    /** App-mirrored data per handle: user-context grants plus non-default provider entries. */
+    private appInputsByHandle;
+    private reportUnknownEntitlement;
 }
 
 /**
@@ -30817,8 +30903,14 @@ interface RevTurbineUserContext extends Omit<UserContextInput, 'custom' | 'entit
     context_hash?: UserContextInput['context_hash'];
     /** Customer-defined fields for segmentation and personalization. */
     custom?: SdkTraits;
-    /** Feature entitlements granted by plan + entitlement rules. */
-    entitlements?: Record<string, boolean>;
+    /**
+     * App-supplied entitlement data, keyed by handle — a boolean or a grant
+     * (`status`, `limit`, `used`). This is Entitlement Mirroring (D-61): it
+     * merges with the Playbook evaluation, and by default the app's data wins.
+     * Browser-supplied data shapes the UI only; the server re-check on the
+     * same inputs stays authoritative for paid actions.
+     */
+    entitlements?: UserContextInput['entitlements'];
     /** Usage entries derived from credits / usage_limit entitlements, keyed by handle. */
     usage?: UserContextInput['usage'];
     /**
@@ -31301,6 +31393,14 @@ interface RevTurbineInitOptions {
      * Playbook.
      */
     placementBehavior?: Partial<RevTurbinePlacementBehaviorFlags>;
+    /**
+     * How app-supplied entitlement data (`userContext.entitlements`, an app
+     * entitlement provider) merges with the Playbook evaluation (D-61).
+     * Provider-level `precedence` defaults to `'app'`; `fields` overrides it
+     * per field (`status`, `limit`, `used`, `remaining`). Use the same value
+     * on your server SDK so verification matches.
+     */
+    entitlementMerge?: EntitlementMergeOptions;
     extension?: {
         enabled?: boolean;
     };
@@ -32075,6 +32175,16 @@ declare class RevTurbineCustomerSdk {
     private readonly policy;
     private readonly extensionEnabled;
     private readonly placementBehaviorOverrides;
+    private readonly entitlementMerge;
+    /** Entries from an app-registered entitlement provider (D-61 mirroring), from the last provider resolution. */
+    private appProviderEntitlements;
+    /** Plan from an app-registered plan provider (D-61) — wins over the user-context plan, as on the server. */
+    private appProviderPlanHandle;
+    /** Usage from an app entitlement provider (D-61), fed into the evaluation as on the server. */
+    private appProviderUsage;
+    /** Segment membership from an app segment provider (D-61), as a server runtime sees it. */
+    private appProviderSegments;
+    private readonly reportedUnknownEntitlements;
     private derivedPlacementBehaviorMemo;
     private readonly providerFailureSlotBehavior;
     private readonly uiPathResolvers;
@@ -32573,6 +32683,14 @@ declare class RevTurbineCustomerSdk {
      */
     private candidateCapGate;
     private recordPresentationCapRules;
+    /**
+     * D-60 + D-61: the resolver's gates read the SAME effective entitlements
+     * `checkEntitlement` returns — the shared evaluation merged with
+     * app-mirrored data — for every handle the Playbook, the user context or an
+     * app provider knows. A gate slot's reported `entitlement_status` still
+     * wins inside the resolver.
+     */
+    private withSlotEntitlementStatus;
     private slotIdForRecord;
     private hydratePresentationCaps;
     private persistPresentationCaps;
@@ -32749,22 +32867,25 @@ declare class RevTurbineCustomerSdk {
      * @public
      */
     setApiBranding(branding: BrandingConfig | undefined): void;
+    /**
+     * The effective entitlement (D-61): the shared core evaluator decides from
+     * the Playbook + user context, then app-mirrored data merges per
+     * `entitlementMerge` (default: app wins). The server SDKs run the same
+     * function on the same inputs, so a server re-check verifies exactly this.
+     * An entitlement nobody knows is denied, warned once and reported.
+     */
     private deriveLocalEntitlementFromConfiguredRules;
     /**
-     * Inline adapter — given a UserTrialStatus + the tenant's
-     * reverse_trial_rules from RevTurbineConfig, derive the inputs that
-     * close plan 43 TASK-2. Returns undefined fields when the user
-     * isn't on an active reverse trial, when no rule matches, or when
-     * the rule has no entitlements_during_trial[].
-     *
-     * Why inline (not calling scaffold's deriveReverseTrialGrants):
-     * the scaffold helper takes a `TrialInstance` (DB-side state) and
-     * matches by `rule_id`. The SDK only holds `UserTrialStatus` (the
-     * transient runtime shape) and doesn't see the rule_id. We match
-     * by `fallback_plan_id === plan_handle` instead — that's the
-     * single configured rule the user can be on per spec §2.4.2.
+     * D-61: snapshot what the app's own providers say — plan, entitlement
+     * entries, usage — so the browser evaluates on exactly the inputs a server
+     * runtime with the same providers would. A static adapter's blanket
+     * defaults are not app data.
      */
-    private resolveReverseTrialGrants;
+    private captureAppProviderState;
+    /** D-61: resolve the app's providers before an entitlement check (cached per provider TTL). */
+    private refreshAppProviderState;
+    /** D-61: an unknown entitlement handle is denied; say so once, locally and in telemetry. */
+    private reportUnknownEntitlement;
     /**
      * Return the SDK-resolved targeting snapshot for the active user.
      *