@grafana-experiments/sdk 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,339 @@
+# grafana-experiments
+
+A browser TypeScript SDK for explicitly activating OpenFeature experiments and reporting analytics to Grafana Faro and, optionally, an existing analytics reporter. It does not create flags, configure allocation, register Odin resources, or perform statistical analysis.
+
+## Quick start
+
+```ts
+import { createExperiments } from '@grafana-experiments/sdk';
+
+const experiments = createExperiments({
+  scope: 'my-application',
+  client: openFeatureClient,
+  faro: { instance: faro },
+  reportAnalytics: existingReporter, // Optional: omit for Faro-only reporting.
+  getSessionId: () => analyticsSessionId,
+  contextKey: tenantContextKey,
+  isEnabled: () => analyticsConsent,
+  events: { guide_started: 'user-action' },
+});
+
+await experiments.ready;
+
+const banner = experiments.defineExperiment({
+  id: 'learning-banner-v1',
+  flagKey: 'my-team.learning-banner',
+  flag: { type: 'boolean' },
+});
+
+// Invoke only at the intended entry point, such as opening the panel.
+const state = await banner.activate();
+const showNewBanner = state.status === 'active' && state.variant === 'treatment';
+
+const reportAnalytics = experiments.reportAnalytics;
+reportAnalytics('guide_started', { guideId });
+reportAnalytics('feedback', { helpful: true });
+```
+
+The original reporter receives the same name and properties plus the reserved `experiments` array. Each array entry identifies one activated experiment, its variant, session, flag and exposure. Before activation the array is empty. Supplying an existing `experiments` property does not override SDK attribution. Objects passed to the original reporter are not redacted; Faro receives a separate copy. Reporters may return promises; rejection is handled independently of Faro reporting.
+
+`scope` must be stable and distinct for each application. Use a new experiment ID for a new experiment run or a changed definition. `contextKey` must be a stable, non-secret identity/tenant discriminator; it is included in the session-storage key. Never use credentials or email addresses as context keys.
+
+## Faro initialization and actions
+
+Supply exactly one of `faro: { instance }` and `faro: { config }`. The latter accepts Faro's `BrowserConfig`, including collector, instrumentations, sampling and `beforeSend`. SDK-created instances are isolated, default to no global exposure, and include `UserActionInstrumentation` even when a custom instrumentation list is supplied. Call `await experiments.ready` before rendering instrumented surfaces. Reports made during initialization still reach the original reporter immediately; their Faro mirror waits for initialization.
+
+An injected instance remains host-owned. Include Faro's `UserActionInstrumentation` when initializing it (Faro's default instrumentation list already includes it). If it is missing, action calls fall back to custom events with `action_fallback: 'instrumentation-unavailable'`; the SDK does not modify an injected instance's instrumentation list.
+
+Select the representation through `events` or override it per call:
+
+```ts
+reportAnalytics(
+  'guide_started',
+  { guideId },
+  {
+    faro: { type: 'user-action' },
+  },
+);
+reportAnalytics(
+  'feedback',
+  { helpful: true },
+  {
+    faro: { type: 'custom-event' },
+  },
+);
+```
+
+- Unconfigured events default to custom events. Identical consecutive calls remain countable.
+- A user-action call starts a real Faro action; it does not also emit a custom-event mirror.
+- Starting another action ends a still-active SDK-owned action with `end_reason: 'superseded'`. This marks the observation boundary, not successful completion of the underlying operation.
+- A host-owned action is preserved. The call becomes a custom event with `action_fallback: 'host-action-active'`, and Faro correlates it with the active action according to its normal lifecycle.
+- Faro ends actions naturally after browser activity. If no qualifying activity occurs, Faro may cancel the action. RudderStack call counts therefore need not equal completed Faro action counts.
+- Explicit completion uses Faro's internal lifecycle interface, isolated in `src/faro.ts`. Compatibility is restricted to Faro 2.12.x and tested against 2.12.0 and 2.12.1.
+
+`dispose()` stops reporting, cancels pending activations, removes SDK listeners, and ends only a still-active SDK-owned action when reporting is enabled. If consent is disabled, both disposal and context reset cancel that action without emitting it; host-owned actions remain untouched. For an SDK-created Faro it also removes instrumentations and transports. It never pauses or disposes an injected Faro or an injected OpenFeature client. Disposing does not erase session deduplication state.
+
+## Activation and sessions
+
+Boolean flags map `false` to control and `true` to treatment. A failed evaluation is never counted as control. Object-valued flags require a validator:
+
+```ts
+type BannerConfig = {
+  variant: 'control' | 'treatment' | 'excluded';
+  title: string;
+};
+
+const banner = experiments.defineExperiment<BannerConfig>({
+  id: 'configured-banner-v1',
+  flagKey: 'my-team.configured-banner',
+  flag: {
+    type: 'object',
+    validate: (value): value is BannerConfig =>
+      typeof value === 'object' && value !== null && 'title' in value && typeof value.title === 'string',
+  },
+});
+```
+
+The SDK separately validates the variant. Excluded values emit no exposure. Malformed values, unavailable providers and missing flags produce `status: 'unavailable'`; keep the existing experience in that state. Readiness waits at most 10 seconds by default (`readinessTimeoutMs`). Subsequent explicit activation can retry; mounted React surfaces also retry after provider readiness/configuration recovery.
+
+Each successful activation produces `experiment_viewed` in both destinations with:
+
+| Field              | Meaning                                                  |
+| ------------------ | -------------------------------------------------------- |
+| `experiment_id`    | Stable experiment run identifier                         |
+| `experiment_group` | Stable audience label; defaults to `rollout`             |
+| `flag_key`         | Existing OpenFeature flag                                |
+| `variant`          | Control or treatment                                     |
+| `session_id`       | Host analytics session, falling back to Faro's session   |
+| `exposure_id`      | Opaque random UUID reused for the same cached assignment |
+
+Exposure is always a Faro custom event, independent of action completion. The SDK attempts reporting once; this is not a collector delivery acknowledgement. Analytics and Faro retain their existing sampling and filtering policies.
+
+The storage key serializes application scope, context, session, experiment ID, flag key and flag type. The exposure ID itself contains none of those values. Within that cache, an unchanged variant/revision/allocation/population reuses its UUID; a changed assignment gets another UUID.
+
+## Connect a deployed flag to Odin
+
+For an illustrative deployed boolean GOFF flag named `my-team.learning-banner`, use this explicit mapping:
+
+| System                           | Field                       | Example                   |
+| -------------------------------- | --------------------------- | ------------------------- |
+| GOFF / OpenFeature               | Deployed flag key           | `my-team.learning-banner` |
+| SDK definition                   | `flagKey`                   | `my-team.learning-banner` |
+| SDK definition and Faro exposure | `id` / `experiment_id`      | `learning-banner-v1`      |
+| Odin Experiment                  | `metadata.name`             | `learning-banner-v1`      |
+| Odin Experiment spec             | `grafanaFeatureToggle.name` | `my-team.learning-banner` |
+
+The quick-start definition above uses these SDK values. Create the Odin resource separately with that name and flag reference, then configure its data source and measurement manifest. For this boolean example, false is control and true is treatment. `defineExperiment()` only registers an application-local handle; it does not create or validate the deployed flag, provision an Odin resource, or check names across systems. Odin's flag reference is documentation, not an assignment authority. Verify the emitted `experiment_id` and `flag_key` in the destination against the resource and deployed flag before collecting a run.
+
+### Verify assignment before declaring randomization
+
+`population: 'randomized'` and `allocationUnit` are host assertions, not SDK verification of GOFF. Before enabling randomized inference in Odin:
+
+1. Record the deployed flag revision, eligibility rule, randomized percentage split, and the exact evaluation-context field GOFF uses for assignment. A targeting rule or a local override alone is not evidence of randomization.
+2. Trace that field through the deployed provider's evaluation request. For a stack-assigned flag, every session on a stack must use the same authoritative stack identity, and the SDK's `allocationUnit.id` must identify that same entity. Do not substitute a browser session ID, or assume an organization ID means stack assignment.
+3. Evaluate known eligible entities through the actual provider. Check that repeated evaluations for the same entity agree across sessions, that independent entities can receive both variants, and that ineligible entities are excluded. Retain the rule/context evidence: an observed 50/50 split alone does not prove randomization.
+4. Inspect stored exposures and outcomes for matching experiment/revision, variant, allocation identity and manifest. Verify collection completeness independently of assignment: sampling, filtering, consent, failed delivery and missing exposure rows can invalidate the measurement population.
+5. Only then set the SDK population declaration and Odin's randomized-population declaration. Set Odin's expected allocation to the deployed eligible-population split; change the experiment run/revision when the assignment contract changes. Until verification is complete, omit the randomization declaration and use descriptive results.
+
+These checks are an adoption contract; neither the SDK nor Odin introspects GOFF to enforce them. A sample-ratio check can detect some collection or assignment failures but cannot establish that the configured assignment rule was randomized.
+
+## Standards
+
+The SDK follows the published standards where they exist and defines only what they leave out.
+
+- **OpenFeature** is the only assignment authority. The SDK reads variants through the evaluation API, so any provider works.
+- **OpenTelemetry feature-flag semantic conventions** (release candidate). Each exposure also carries the attributes of the evaluation that produced it, mapped as [OpenFeature Appendix D](https://openfeature.dev/specification/appendix-d/) recommends:
+
+| Attribute                     | Source                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `feature_flag.key`            | Flag key                                                                       |
+| `feature_flag.result.variant` | Provider's variant                                                             |
+| `feature_flag.result.value`   | Evaluated value, only when the provider has no variant                         |
+| `feature_flag.result.reason`  | OpenFeature reason in lower snake case (`TARGETING_MATCH` → `targeting_match`) |
+| `feature_flag.provider.name`  | Provider metadata                                                              |
+| `feature_flag.context.id`     | Flag metadata `contextId`                                                      |
+| `feature_flag.set.id`         | Flag metadata `flagSetId`                                                      |
+| `feature_flag.version`        | Flag metadata `version`                                                        |
+
+- The SDK does not emit OpenTelemetry's `feature_flag.evaluation` event, which is recorded on every evaluation. An exposure is reported once per session at the entry point. Add OpenFeature's OpenTelemetry hook if you also want every evaluation.
+- `feature_flag.context.id` falls back to the targeting key in the convention. The SDK omits that fallback so identity does not reach telemetry unless the provider supplies `contextId`. Set `recordFlagValue: false` when flag values are sensitive or large.
+- **OpenFeature Tracking API**. Supply `openFeatureTracking` to also send outcome events to `client.track()` for providers that attribute goals themselves. It is off by default because it shares business data with the flag provider. Return the tracking details to send, or `null` to skip:
+
+```ts
+openFeatureTracking: (name, properties) =>
+  name === 'purchase_completed' ? { value: Number(properties.amount), currency: 'GBP' } : null,
+```
+
+To explicitly share the same attribution used by Faro and customer analytics, use the third callback argument and exported helper:
+
+```ts
+import { toOpenFeatureTrackingDetails } from '@grafana-experiments/sdk';
+
+// Within createExperiments options:
+openFeatureTracking: (name, properties, context) =>
+  name === 'purchase_completed'
+    ? { value: Number(properties.amount), ...toOpenFeatureTrackingDetails(context) }
+    : null,
+```
+
+`MeasurementContext` contains the event ID, captured assignments, schema versions and optional journey ID. The helper returns an independent OpenFeature-compatible object, omitting undefined fields. Existing two-argument callbacks remain unchanged: no attribution is added to their return value. Select only the fields your provider should receive. Faro redaction does not redact provider Tracking or customer analytics; each destination has its own policy and receives independent copies.
+
+The Web SDK supplies its **current evaluation context** to the provider's `track()` method. Our explicit tracking details retain the journey's original exposure snapshot; they neither change targeting nor guarantee that the provider uses those fields for its own attribution. Identity changes invalidate old journeys. Unsupported Tracking is a no-op, and a Tracking failure does not prevent Faro reporting. An attempted call is not a storage receipt.
+
+### Optional OpenTelemetry evaluation telemetry
+
+Use the official `@openfeature/open-telemetry-hooks` package with an existing, host-configured OTel logs SDK and exporter. This is optional; the experiments package installs no OTel pipeline or additional queue.
+
+```ts
+import { EventHook } from '@openfeature/open-telemetry-hooks';
+
+// Install once on the host's OpenFeature client after configuring OTel logs.
+// Do not also install this hook globally.
+client.addHooks(
+  new EventHook({
+    excludeAttributes: ['feature_flag.context.id', 'feature_flag.result.value'],
+  }),
+);
+```
+
+This example suppresses targeting identity and raw flag values. Review other provider metadata for sensitive data before enabling export. The host must enforce consent in its OTel collection/export pipeline, including queued records when consent changes. The SDK's `isEnabled` gate controls SDK reporting, not independently installed OpenFeature hooks or the host's OTel exporter.
+
+Three distinct signals are involved:
+
+| Signal                    | Meaning                                                           | Delivery                                                          |
+| ------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `feature_flag.evaluation` | A flag was evaluated, even if repeatedly                          | Official OTel hook through the host's OTel logs pipeline          |
+| `experiment_viewed`       | An eligible experience was explicitly activated                   | Faro and the configured exposure analytics destination            |
+| Business outcome          | An operation occurred, with captured exposure/journey attribution | Faro, optional customer analytics and opt-in OpenFeature Tracking |
+
+OTel feature-flag evaluation attributes are currently release candidate within an in-development convention. Reusing their names on a Faro exposure does **not** export that exposure through OTel. Evaluation counts must not become the exposure denominator. Native Faro actions remain distinct from explicit business outcomes; automatic errors and measurements keep origin-aware Faro enrichment.
+
+References: [OpenFeature Tracking specification](https://openfeature.dev/specification/sections/tracking/), [official OTel hooks](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/hooks/open-telemetry), and [OTel evaluation conventions](https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-events/).
+
+Neither standard defines an experiment, an exposure, attribution of outcomes to an exposure, or the allocation unit. Those remain this SDK's contract (`experiment_id`, `exposure_id`, `experiments`, `allocation_unit_*`), and the existing field names are unchanged.
+
+Assignments remain stable until the session or identity/tenant context changes. Session storage preserves assignments and deduplication across reloads in the same tab. Blocked storage falls back to in-memory deduplication. Tab duplication, concurrent SDK instances and other devices can still produce duplicate exposures; use `exposure_id` for downstream deduplication. The browser is not an authoritative source of assignment persistence.
+
+Faro session changes are observed automatically. Call `experiments.refreshSession()` when a host session ID or consent changes. Call `experiments.resetContext(newContextKey)` when switching identity/tenant, before reporting or activating there. Calling `resetContext` with the current key explicitly clears the current registered experiments' stored assignments. Neither operation changes the OpenFeature provider's context: the host must update that as well.
+
+Without either session ID, activation remains unavailable. Exposure per session does not imply assignment per session: Grafana continues to allocate by its server-defined stack/org context.
+
+## React
+
+```tsx
+import { ExperimentsProvider, useExperiment } from '@grafana-experiments/sdk/react';
+
+// Define the SDK and experiment once in application setup, not during render.
+function Panel({ eligible }: { eligible: boolean }) {
+  const state = useExperiment(banner, eligible);
+  return state.status === 'active' && state.variant === 'treatment' ? (
+    <NewExperience />
+  ) : (
+    <ExistingExperience />
+  );
+}
+
+<ExperimentsProvider experiments={experiments}>
+  <Panel eligible={panelIsOpen} />
+</ExperimentsProvider>;
+```
+
+The activation hook works with a stable experiment handle, with or without the context provider. `useExperiments()` accesses the SDK from that provider. Activation happens in an effect; abandoned renders and unmounted pending activations produce no exposure. Visibility is the application's responsibility: mount does not necessarily mean visible. Changing eligibility does not undo an already recorded exposure. The provider does not own or dispose the SDK; the application's bootstrap lifecycle does.
+
+## Grafana adapter
+
+```ts
+import { createGrafanaExperiments } from '@grafana-experiments/sdk/grafana';
+
+const experiments = createGrafanaExperiments({
+  scope: 'my-plugin',
+  domain: 'my-plugin-experiments',
+  faro: { instance: faro },
+  getSessionId: () => analyticsSessionId,
+});
+```
+
+Requires `@grafana/runtime >=13.2.2 <14`. The adapter composes Grafana's local-override and OFREP proxy providers in its own OpenFeature domain. It refuses to replace an existing named provider and does not alter Grafana's default provider or targeting context. Dispose releases only the adapter's provider registration.
+
+Ordinary events use `reportInteraction`. Exposure uses `reportExperimentView(id, group, variant)` exactly once, with no duplicate interaction event. Grafana's exposure API accepts only those three fields; Grafana supplies its own analytics identity/session context. The full SDK exposure record is available in Faro and subsequent enriched outcome events. It is not injected into unsupported Grafana exposure fields.
+
+## Consent, filtering and failures
+
+`isEnabled` gates SDK activation and reporting. Call `refreshSession()` when it changes; SDK-created Faro instances are paused on revocation and resumed only if the SDK paused them. The host remains responsible for pausing an injected Faro and its independently captured automatic telemetry. The SDK does not override the host's sampling or `beforeSend` filters.
+
+Use `transformFaroProperties(name, properties)` to redact the Faro copy, or return `null` to suppress it. Faro values are converted to strings; object values are JSON encoded. Uncloneable/unserializable properties are omitted from the Faro copy without dropping other attributes. Original-reporter and Faro failures are isolated and can be observed through `onError`. No transport retries or durable queues are added.
+
+## Development
+
+```sh
+npm ci --legacy-peer-deps
+npm run check
+npm run test:mutation
+npm pack --dry-run
+```
+
+The standalone package lives outside Odin's plugin build. Development uses `--legacy-peer-deps` because Grafana runtime is an optional host integration and its full UI peer dependency graph is unnecessary for adapter-boundary tests. Real OpenFeature clients and Faro recording transports exercise the core; only Grafana's host boundary is substituted. A/A and Pathfinder-style examples are in `examples/`. No package is published or production application migrated by these commands.
+
+## Version 2 measurement contract
+
+OpenFeature remains the only assignment authority. Define `metadata` for declared allocation identity and population, or `mapAssignment(details)` to map provider results explicitly. The SDK never infers that a browser session represents a stack or organization. Missing allocation metadata is valid descriptive telemetry; Odin withholds allocation-level inference.
+
+```ts
+const experiment = sdk.defineExperiment({
+  id: 'checkout',
+  flagKey: 'checkout-recommendations',
+  flag: { type: 'boolean' },
+  metadata: {
+    revision: 'recommendations-v2',
+    allocationUnit: { type: 'stack', id: stackId },
+    population: 'randomized',
+  },
+});
+await experiment.activate({ entryId: 'checkout-entry-1' });
+const journey = sdk.beginJourney();
+await addProduct();
+journey.reportAnalytics('product_added', { product: 'trail-pack' });
+journey.reportAnalytics('purchase_completed', { amount: 48, currency: 'GBP' });
+journey.end();
+```
+
+Use one stable `entryId` for repeated activation of a committed entry; use a new ID for a new entry. React's `useExperiment(experiment, eligible, entryId)` follows the same rule. Provider updates do not change an active journey. Re-entry evaluates again: an unchanged assignment reuses its session exposure, while variant/revision/allocation changes receive their own exposure. Omitting `entryId` preserves the original session-stable API for existing integrations.
+
+Journey handles snapshot active assignments and are invalidated on session/identity reset or `end()`. Consent is checked when events are sent. `getTelemetryContext()` supplies captured `experiments` and `journey_id` strings for explicit Faro error/measurement calls. Ended or invalidated handles return no experiment assignments. Do not use journey handles to bypass the host's Faro consent policy.
+
+Each logical call receives a unique `event_id`; repeated calls remain distinct, while transport retries reuse the same payload. Exposure IDs are opaque random identifiers. Assignment arrays retain every active experiment. The v2 storage namespace deliberately does not reuse v1 cache entries; existing v1 warehouse records remain readable as legacy session records without invented allocation metadata.
+
+### Typed events and manifests
+
+Pass `eventDefinitions` into `createExperiments`. Each definition has a positive integer `version` and `properties` mapping to `{type: 'string' | 'number' | 'boolean', required?: boolean}`. Use `defineEvent` and `createTypedReporter` to preserve TypeScript inference. `getEventManifest()` returns a JSON-serializable versioned manifest to import into Odin. Event names not in the manifest retain the original permissive reporting behavior.
+
+Malformed declared measurements still attempt the existing customer reporter but emit an `experiment_diagnostic` to Faro rather than a valid business outcome. Event manifests, including schema versions, must match Odin's analysis configuration. Exporting a manifest does not provision flags, mutate Odin, or transmit credentials.
+
+### Diagnostics and Faro enrichment
+
+`getDiagnostics()` returns a bounded snapshot (latest 200 entries); `subscribeDiagnostics(listener)` observes evaluation, activation, suppression, transitions, validation and reporting attempts/failures. Observer failures cannot break application reporting. Diagnostic messages are local developer information and should not be copied into public telemetry without redaction. A reporting attempt is never represented as confirmed storage.
+
+Use `enrichFaro: true` with SDK-owned initialization options. For an existing Faro instance, install `createExperimentEnricher({getAssignments: () => sdk?.getActiveAssignments() ?? [], isEnabled, beforeSend: existingHook})` when the host initializes Faro. The host hook runs last so its filtering/redaction remains authoritative. The SDK does not replace another integration's hooks or sampling configuration.
+
+Measurement emission time does not prove when measured activity happened. Measurements require `context.experiment_started_at` (epoch milliseconds), or an explicit journey snapshot, to receive attribution. Pre-exposure and unscoped Web Vitals remain unattributed. The SDK never installs a second replay recorder. Native Faro user-action completion is not a business conversion.
+
+### Storage ownership
+
+The SDK emits the standard Faro envelope with custom attributes. Storage provisioning and database ownership remain outside the SDK.
+
+### Delivery boundaries
+
+An `activated` diagnostic records an exposure decision. `analytics-attempted` and
+`faro-attempted` record calls to those destinations, not acknowledgements of storage.
+`faro-filtered` describes the SDK's redaction transform; filtering inside a host
+Faro hook or transport may not be observable by this SDK. Observable synchronous
+and asynchronous reporter failures produce `reporting-error` diagnostics.
+
+Faro's transport owns batching and retries. Retry attempts retain the original event
+ID; separate legitimate reporting calls receive different IDs. The SDK does not
+replace caller-owned transports or add a second delivery queue. Transport retries
+can be exhausted, and closing a browser can lose buffered telemetry. Session-persisted
+exposure deduplication is not a delivery receipt: reloading does not replay an exposure
+that has already been activated. Verify ingestion in the destination when completeness
+matters. Sampling and filtering remain controlled by the host; a complete-collection
+declaration in Odin is an operational assertion, not a guarantee from this SDK.

package/RELEASING.md

@@ -0,0 +1,36 @@
+# Publishing @grafana-experiments/sdk
+
+Releases follow grafana-coda-app's manual GitHub Actions trusted-publishing workflow. The local package retains its `grafana-experiments` name for existing consumers and the demo. Only the release artifact is named `@grafana-experiments/sdk`; its README imports are adjusted accordingly. No npm token is stored in GitHub or Vault.
+
+## One-time setup
+
+1. Ensure `@grafana-experiments/sdk` exists in the npm organization. If it does not, an organization owner must bootstrap it with an authenticated manual publish before configuring its trusted publisher. Use a scratch `0.0.0` placeholder and deprecate it; reserve the real version for the verified workflow artifact. This PR does not bootstrap or publish it.
+2. In the package's npm settings, configure GitHub trusted publishing with organization `grafana`, repository `grafana-experiments-app`, workflow filename `publish-npm.yml`, environment `Release npm package`, and permission to run `npm publish`.
+3. Configure the GitHub environment `Release npm package` to allow only `main`, with the desired reviewer protection. The workflow also refuses dispatches from other branches.
+
+The source repository is internal. Like Coda, the workflow explicitly disables npm provenance because private/internal source repositories do not support it. OIDC authentication still applies. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+## Release
+
+1. Merge this workflow into main. For subsequent releases, bump the SDK's package.json and package-lock.json version in a reviewed PR. SDK versions are independent of plugin versions.
+2. Dispatch **publish-npm** on `main`. It installs with lifecycle scripts disabled, checks/tests/builds explicitly, creates a scoped tarball, and verifies every ESM/CJS/type export plus README and LICENSE is present.
+3. The workflow checks the exact version, not the latest dist-tag. A version already published from the same commit skips publishing and can repair a missing tag. A version owned by another commit fails; registry errors other than 404 fail closed.
+4. Successful publication creates `experiments-sdk-v<VERSION>`, avoiding the plugin's `v*` release trigger. Existing tags must point to the same commit. No automatic publish on main push is enabled.
+5. Verify `npm view @grafana-experiments/sdk@<VERSION> version gitHead` and install the package in a consumer.
+
+```sh
+npm install @grafana-experiments/sdk @openfeature/web-sdk @grafana/faro-web-sdk
+```
+
+Public entry points are `@grafana-experiments/sdk`, `@grafana-experiments/sdk/react` and `@grafana-experiments/sdk/grafana`.
+
+For a local artifact check without publishing:
+
+```sh
+cd packages/grafana-experiments
+npm ci --ignore-scripts --legacy-peer-deps
+npm run check
+node scripts/pack-release.mjs /tmp
+```
+
+An npm PUT E404 usually indicates a missing package or mismatched trusted publisher: check repository, filename and environment exactly. Do not add a long-lived npm token as a fallback. No release tag is created on a failed publish.