@spotify-confidence/openfeature-server-provider-local 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.0](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.4.0...openfeature-provider-js-v0.5.0) (2025-12-19)
+
+
+### Features
+
+* pluggable materialization ([#211](https://github.com/spotify/confidence-resolver/issues/211)) ([96aea72](https://github.com/spotify/confidence-resolver/commit/96aea72a2dce2e02fdfa4374e4fa245f0efc177b))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * rust-guest bumped from 0.1.11 to 0.1.12
+
 ## [0.4.0](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.3.0...openfeature-provider-js-v0.4.0) (2025-12-11)
 
 

package/README.md

@@ -138,15 +138,72 @@ The provider periodically:
 
 ---
 
-## Sticky Assignments
+## Materialization Stores
 
-The provider supports **Sticky Assignments** for consistent variant assignments across flag evaluations.
+Materialization stores provide persistent storage for sticky variant assignments and custom targeting segments. This enables two key use cases:
 
-**📖 See the [Integration Guide: Sticky Assignments](../INTEGRATION_GUIDE.md#sticky-assignments)** for:
-- How sticky assignments work
-- Server-managed storage (zero configuration)
-- Latency considerations
-- Custom storage options (currently Java-only, coming soon to JavaScript)
+1. **Sticky Assignments**: Maintain consistent variant assignments across evaluations even when targeting attributes change. This enables pausing intake (stopping new users from entering an experiment) while keeping existing users in their assigned variants.
+
+2. **Custom Targeting via Materialized Segments**: Precomputed sets of identifiers from datasets that should be targeted. Instead of evaluating complex targeting rules at runtime, materializations allow efficient lookup of whether a unit (user, session, etc.) is included in a target segment.
+
+### Default Behavior
+
+⚠️ Warning: If your flags rely on sticky assignments or materialized segments, the default SDK behaviour will prevent those rules from being applied and your evaluations will fall back to default values. For production workloads that need sticky behavior or segment lookups, implement and configure a real `MaterializationStore` (e.g., Redis, DynamoDB, or a key-value store) to avoid unexpected fallbacks and ensure consistent variant assignment.
+
+### Remote Materialization Store
+
+For quick setup without managing your own storage infrastructure, enable the built-in remote materialization store:
+
+```ts
+const provider = createConfidenceServerProvider({
+  flagClientSecret: process.env.CONFIDENCE_FLAG_CLIENT_SECRET!,
+  materializationStore: 'CONFIDENCE_REMOTE_STORE',
+});
+```
+
+**When to use**:
+- You need sticky assignments or materialized segments but don't want to manage storage infrastructure
+- Quick prototyping or getting started
+- Lower-volume applications where network latency is acceptable
+
+**Trade-offs**:
+- Additional network calls during flag resolution (adds latency)
+- Lower performance compared to local storage implementations (Redis, DynamoDB, etc.)
+
+### Custom Implementations
+
+For improved latency and reduced network calls, implement the `MaterializationStore` interface to store materialization data in your infrastructure:
+
+```ts
+import { MaterializationStore } from '@spotify-confidence/openfeature-server-provider-local';
+
+class MyRedisStore implements MaterializationStore {
+  async readMaterializations(readOps: MaterializationStore.ReadOp[]): Promise<MaterializationStore.ReadResult[]> {
+    // Load materialization data from Redis
+  }
+
+  async writeMaterializations(writeOps: MaterializationStore.WriteOp[]): Promise<void> {
+    // Store materialization data to Redis
+  }
+}
+
+const provider = createConfidenceServerProvider({
+  flagClientSecret: process.env.CONFIDENCE_FLAG_CLIENT_SECRET!,
+  materializationStore: new MyRedisStore(),
+});
+```
+
+For read-only stores (e.g., pre-populated materialized segments without sticky assignment writes), omit the `writeMaterializations` method.
+
+### When to Use Materialization Stores
+
+Consider implementing a materialization store if:
+- You need to support sticky variant assignments for experiments
+- You use materialized segments for custom targeting
+- You want to minimize network latency during flag resolution
+- You have high-volume flag evaluations
+
+If you don't use sticky assignments or materialized segments, the default behavior is sufficient.
 
 ---
 

package/dist/index.browser.d.ts

@@ -1,8 +1,85 @@
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
 import { EvaluationContext, JsonValue, Provider, ProviderMetadata, ProviderStatus, ResolutionDetails } from "@openfeature/server-sdk";
 
+//#region src/proto/confidence/flags/types/v1/types.d.ts
+/** Schema for the value of a flag. */
+interface FlagSchema {
+  /** Schema if this is a struct */
+  structSchema?: FlagSchema_StructFlagSchema | undefined;
+  /** Schema if this is a list */
+  listSchema?: FlagSchema_ListFlagSchema | undefined;
+  /** Schema if this is an int */
+  intSchema?: FlagSchema_IntFlagSchema | undefined;
+  /** Schema if this is a double */
+  doubleSchema?: FlagSchema_DoubleFlagSchema | undefined;
+  /** Schema if this is a string */
+  stringSchema?: FlagSchema_StringFlagSchema | undefined;
+  /** Schema if this is a bool */
+  boolSchema?: FlagSchema_BoolFlagSchema | undefined;
+}
+/** A schema of nested fields. */
+interface FlagSchema_StructFlagSchema {
+  /** Map of field name to the schema for the field */
+  schema: {
+    [key: string]: FlagSchema;
+  };
+}
+/** A number that has a decimal place. */
+interface FlagSchema_DoubleFlagSchema {}
+/** A whole number without a decimal point. */
+interface FlagSchema_IntFlagSchema {}
+/** A string. */
+interface FlagSchema_StringFlagSchema {}
+/** A boolean: true or false. */
+interface FlagSchema_BoolFlagSchema {}
+/** A list of values. */
+interface FlagSchema_ListFlagSchema {
+  /** The schema for the elements in the list */
+  elementSchema?: FlagSchema | undefined;
+}
+declare const FlagSchema: MessageFns$5<FlagSchema>;
+declare const FlagSchema_StructFlagSchema: MessageFns$5<FlagSchema_StructFlagSchema>;
+declare const FlagSchema_DoubleFlagSchema: MessageFns$5<FlagSchema_DoubleFlagSchema>;
+declare const FlagSchema_IntFlagSchema: MessageFns$5<FlagSchema_IntFlagSchema>;
+declare const FlagSchema_StringFlagSchema: MessageFns$5<FlagSchema_StringFlagSchema>;
+declare const FlagSchema_BoolFlagSchema: MessageFns$5<FlagSchema_BoolFlagSchema>;
+declare const FlagSchema_ListFlagSchema: MessageFns$5<FlagSchema_ListFlagSchema>;
+type Builtin$5 = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial$5<T> = T extends Builtin$5 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$5<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$5<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$5<T[K]> } : Partial<T>;
+type KeysOfUnion$5<T> = T extends T ? keyof T : never;
+type Exact$5<P, I extends P> = P extends Builtin$5 ? P : P & { [K in keyof P]: Exact$5<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion$5<P>>]: never };
+interface MessageFns$5<T> {
+  encode(message: T, writer?: BinaryWriter): BinaryWriter;
+  decode(input: BinaryReader | Uint8Array, length?: number): T;
+  fromJSON(object: any): T;
+  toJSON(message: T): unknown;
+  create<I extends Exact$5<DeepPartial$5<T>, I>>(base?: I): T;
+  fromPartial<I extends Exact$5<DeepPartial$5<T>, I>>(object: I): T;
+}
+//#endregion
 //#region src/proto/confidence/flags/resolver/v1/types.d.ts
-
+declare enum ResolveReason {
+  /** RESOLVE_REASON_UNSPECIFIED - Unspecified enum. */
+  RESOLVE_REASON_UNSPECIFIED = 0,
+  /** RESOLVE_REASON_MATCH - The flag was successfully resolved because one rule matched. */
+  RESOLVE_REASON_MATCH = 1,
+  /** RESOLVE_REASON_NO_SEGMENT_MATCH - The flag could not be resolved because no rule matched. */
+  RESOLVE_REASON_NO_SEGMENT_MATCH = 2,
+  /**
+  * RESOLVE_REASON_NO_TREATMENT_MATCH - The flag could not be resolved because the matching rule had no variant
+  * that could be assigned.
+  *
+  * @deprecated
+  */
+  RESOLVE_REASON_NO_TREATMENT_MATCH = 3,
+  /** RESOLVE_REASON_FLAG_ARCHIVED - The flag could not be resolved because it was archived. */
+  RESOLVE_REASON_FLAG_ARCHIVED = 4,
+  /** RESOLVE_REASON_TARGETING_KEY_ERROR - The flag could not be resolved because the targeting key field was invalid */
+  RESOLVE_REASON_TARGETING_KEY_ERROR = 5,
+  /** RESOLVE_REASON_ERROR - Unknown error occurred during the resolve */
+  RESOLVE_REASON_ERROR = 6,
+  UNRECOGNIZED = -1,
+}
 declare enum SdkId {
   SDK_ID_UNSPECIFIED = 0,
   SDK_ID_JAVA_PROVIDER = 1,
@@ -29,10 +106,6 @@ declare enum SdkId {
   SDK_ID_JS_LOCAL_SERVER_PROVIDER = 22,
   UNRECOGNIZED = -1,
 }
-/**
-* (-- api-linter: core::0123::resource-annotation=disabled
-*     aip.dev/not-precedent: SDKs are not internal Confidence resources. --)
-*/
 interface Sdk {
   /** Name of a Confidence SDKs. */
   id?: SdkId | undefined;
@@ -41,45 +114,21 @@ interface Sdk {
   /** Version of the SDK. */
   version: string;
 }
-declare const Sdk: MessageFns$2<Sdk>;
-type Builtin$2 = Date | Function | Uint8Array | string | number | boolean | undefined;
-type DeepPartial$2<T> = T extends Builtin$2 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$2<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$2<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$2<T[K]> } : Partial<T>;
-type KeysOfUnion$2<T> = T extends T ? keyof T : never;
-type Exact$2<P, I extends P> = P extends Builtin$2 ? P : P & { [K in keyof P]: Exact$2<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion$2<P>>]: never };
-interface MessageFns$2<T> {
+declare const Sdk: MessageFns$4<Sdk>;
+type Builtin$4 = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial$4<T> = T extends Builtin$4 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$4<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$4<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$4<T[K]> } : Partial<T>;
+type KeysOfUnion$4<T> = T extends T ? keyof T : never;
+type Exact$4<P, I extends P> = P extends Builtin$4 ? P : P & { [K in keyof P]: Exact$4<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion$4<P>>]: never };
+interface MessageFns$4<T> {
   encode(message: T, writer?: BinaryWriter): BinaryWriter;
   decode(input: BinaryReader | Uint8Array, length?: number): T;
   fromJSON(object: any): T;
   toJSON(message: T): unknown;
-  create<I extends Exact$2<DeepPartial$2<T>, I>>(base?: I): T;
-  fromPartial<I extends Exact$2<DeepPartial$2<T>, I>>(object: I): T;
-}
-//#endregion
-//#region src/proto/types.d.ts
-declare enum ResolveReason {
-  /** RESOLVE_REASON_UNSPECIFIED - Unspecified enum. */
-  RESOLVE_REASON_UNSPECIFIED = 0,
-  /** RESOLVE_REASON_MATCH - The flag was successfully resolved because one rule matched. */
-  RESOLVE_REASON_MATCH = 1,
-  /** RESOLVE_REASON_NO_SEGMENT_MATCH - The flag could not be resolved because no rule matched. */
-  RESOLVE_REASON_NO_SEGMENT_MATCH = 2,
-  /**
-  * RESOLVE_REASON_NO_TREATMENT_MATCH - The flag could not be resolved because the matching rule had no variant
-  * that could be assigned.
-  *
-  * @deprecated
-  */
-  RESOLVE_REASON_NO_TREATMENT_MATCH = 3,
-  /** RESOLVE_REASON_FLAG_ARCHIVED - The flag could not be resolved because it was archived. */
-  RESOLVE_REASON_FLAG_ARCHIVED = 4,
-  /** RESOLVE_REASON_TARGETING_KEY_ERROR - The flag could not be resolved because the targeting key field was invalid */
-  RESOLVE_REASON_TARGETING_KEY_ERROR = 5,
-  /** RESOLVE_REASON_ERROR - Unknown error occurred during the resolve */
-  RESOLVE_REASON_ERROR = 6,
-  UNRECOGNIZED = -1,
+  create<I extends Exact$4<DeepPartial$4<T>, I>>(base?: I): T;
+  fromPartial<I extends Exact$4<DeepPartial$4<T>, I>>(object: I): T;
 }
 //#endregion
-//#region src/proto/resolver/api.d.ts
+//#region src/proto/confidence/flags/resolver/v1/api.d.ts
 interface ResolveFlagsRequest {
   /**
   * If non-empty, the specific flags are resolved, otherwise all flags
@@ -104,6 +153,7 @@ interface ResolveFlagsRequest {
   * resolve, or delayed until `ApplyFlag` is called. A flag is typically
   * applied when it is used, if this occurs much later than the resolve, then
   * `apply` should likely be set to false.
+  * In a local resolve case it is encouraged to set this to `true`
   */
   apply: boolean;
   /** Information about the SDK used to initiate the request. */
@@ -135,79 +185,105 @@ interface ResolvedFlag {
   value?: {
     [key: string]: any;
   } | undefined;
+  /** The schema of the value that was returned. */
+  flagSchema?: FlagSchema_StructFlagSchema | undefined;
   /** The reason to why the flag could be resolved or not. */
   reason: ResolveReason;
 }
+declare const ResolveFlagsRequest: MessageFns$3<ResolveFlagsRequest>;
+declare const ResolveFlagsResponse: MessageFns$3<ResolveFlagsResponse>;
+declare const ResolvedFlag: MessageFns$3<ResolvedFlag>;
+type Builtin$3 = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial$3<T> = T extends Builtin$3 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$3<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$3<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$3<T[K]> } : Partial<T>;
+type KeysOfUnion$3<T> = T extends T ? keyof T : never;
+type Exact$3<P, I extends P> = P extends Builtin$3 ? P : P & { [K in keyof P]: Exact$3<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion$3<P>>]: never };
+interface MessageFns$3<T> {
+  encode(message: T, writer?: BinaryWriter): BinaryWriter;
+  decode(input: BinaryReader | Uint8Array, length?: number): T;
+  fromJSON(object: any): T;
+  toJSON(message: T): unknown;
+  create<I extends Exact$3<DeepPartial$3<T>, I>>(base?: I): T;
+  fromPartial<I extends Exact$3<DeepPartial$3<T>, I>>(object: I): T;
+}
+//#endregion
+//#region src/proto/confidence/flags/resolver/v1/internal_api.d.ts
+interface VariantReadOp {
+  unit: string;
+  materialization: string;
+  rule: string;
+}
+interface InclusionReadOp {
+  unit: string;
+  materialization: string;
+}
+interface ReadOp$1 {
+  variantReadOp?: VariantReadOp | undefined;
+  inclusionReadOp?: InclusionReadOp | undefined;
+}
+interface ReadOperationsRequest {
+  ops: ReadOp$1[];
+}
+interface VariantData {
+  unit: string;
+  materialization: string;
+  rule: string;
+  variant: string;
+}
+interface InclusionData {
+  unit: string;
+  materialization: string;
+  isIncluded: boolean;
+}
+interface ReadResult {
+  variantResult?: VariantData | undefined;
+  inclusionResult?: InclusionData | undefined;
+}
+declare const VariantReadOp: MessageFns$2<VariantReadOp>;
+declare const InclusionReadOp: MessageFns$2<InclusionReadOp>;
+declare const ReadOp$1: MessageFns$2<ReadOp$1>;
+declare const ReadOperationsRequest: MessageFns$2<ReadOperationsRequest>;
+declare const VariantData: MessageFns$2<VariantData>;
+declare const InclusionData: MessageFns$2<InclusionData>;
+declare const ReadResult: MessageFns$2<ReadResult>;
+type Builtin$2 = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial$2<T> = T extends Builtin$2 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$2<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$2<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$2<T[K]> } : Partial<T>;
+type KeysOfUnion$2<T> = T extends T ? keyof T : never;
+type Exact$2<P, I extends P> = P extends Builtin$2 ? P : P & { [K in keyof P]: Exact$2<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion$2<P>>]: never };
+interface MessageFns$2<T> {
+  encode(message: T, writer?: BinaryWriter): BinaryWriter;
+  decode(input: BinaryReader | Uint8Array, length?: number): T;
+  fromJSON(object: any): T;
+  toJSON(message: T): unknown;
+  create<I extends Exact$2<DeepPartial$2<T>, I>>(base?: I): T;
+  fromPartial<I extends Exact$2<DeepPartial$2<T>, I>>(object: I): T;
+}
+//#endregion
+//#region src/proto/confidence/wasm/wasm_api.d.ts
 /** Request for resolving flags with sticky (materialized) assignments */
 interface ResolveWithStickyRequest {
   /** The standard resolve request */
   resolveRequest?: ResolveFlagsRequest | undefined;
-  /**
-  * Context about the materialization required for the resolve
-  * Map of targeting key (unit) to their materialization data
-  */
-  materializationsPerUnit: {
-    [key: string]: MaterializationMap;
-  };
-  /** If a materialization info is missing, return to the caller immediately */
+  /** if a materialization info is missing, we want tor return to the caller immediately */
   failFastOnSticky: boolean;
-}
-/** Map of materialization IDs to their info for a specific unit */
-interface MaterializationMap {
-  /** Map of materialization name to info */
-  infoMap: {
-    [key: string]: MaterializationInfo;
-  };
-}
-/** Information about a materialization for a specific unit */
-interface MaterializationInfo {
-  /** Whether the unit is in this materialization/rollout */
-  unitInInfo: boolean;
-  /** Map of rule name to variant name for this unit */
-  ruleToVariant: {
-    [key: string]: string;
-  };
+  /** if we should support sticky or completely skip the flag if they had sticky rules */
+  notProcessSticky: boolean;
+  /** Context about the materialization required for the resolve */
+  materializations: ReadResult[];
 }
 /** Response from resolving with sticky assignments */
 interface ResolveWithStickyResponse {
   success?: ResolveWithStickyResponse_Success | undefined;
-  missingMaterializations?: ResolveWithStickyResponse_MissingMaterializations | undefined;
+  readOpsRequest?: ReadOperationsRequest | undefined;
 }
 /** Successful resolution with materialization updates */
 interface ResolveWithStickyResponse_Success {
-  /** The resolved flags response */
   response?: ResolveFlagsResponse | undefined;
   /** New assignments that should be stored */
-  updates: ResolveWithStickyResponse_MaterializationUpdate[];
-}
-/** Information about missing materializations */
-interface ResolveWithStickyResponse_MissingMaterializations {
-  items: ResolveWithStickyResponse_MissingMaterializationItem[];
-}
-/** A missing materialization item */
-interface ResolveWithStickyResponse_MissingMaterializationItem {
-  unit: string;
-  rule: string;
-  readMaterialization: string;
-}
-/** A materialization update to be stored */
-interface ResolveWithStickyResponse_MaterializationUpdate {
-  unit: string;
-  writeMaterialization: string;
-  rule: string;
-  variant: string;
+  materializationUpdates: VariantData[];
 }
-declare const ResolveFlagsRequest: MessageFns$1<ResolveFlagsRequest>;
-declare const ResolveFlagsResponse: MessageFns$1<ResolveFlagsResponse>;
-declare const ResolvedFlag: MessageFns$1<ResolvedFlag>;
 declare const ResolveWithStickyRequest: MessageFns$1<ResolveWithStickyRequest>;
-declare const MaterializationMap: MessageFns$1<MaterializationMap>;
-declare const MaterializationInfo: MessageFns$1<MaterializationInfo>;
 declare const ResolveWithStickyResponse: MessageFns$1<ResolveWithStickyResponse>;
 declare const ResolveWithStickyResponse_Success: MessageFns$1<ResolveWithStickyResponse_Success>;
-declare const ResolveWithStickyResponse_MissingMaterializations: MessageFns$1<ResolveWithStickyResponse_MissingMaterializations>;
-declare const ResolveWithStickyResponse_MissingMaterializationItem: MessageFns$1<ResolveWithStickyResponse_MissingMaterializationItem>;
-declare const ResolveWithStickyResponse_MaterializationUpdate: MessageFns$1<ResolveWithStickyResponse_MaterializationUpdate>;
 type Builtin$1 = Date | Function | Uint8Array | string | number | boolean | undefined;
 type DeepPartial$1<T> = T extends Builtin$1 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$1<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$1<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$1<T[K]> } : Partial<T>;
 type KeysOfUnion$1<T> = T extends T ? keyof T : never;
@@ -221,7 +297,7 @@ interface MessageFns$1<T> {
   fromPartial<I extends Exact$1<DeepPartial$1<T>, I>>(object: I): T;
 }
 //#endregion
-//#region src/proto/messages.d.ts
+//#region src/proto/confidence/wasm/messages.d.ts
 interface SetResolverStateRequest {
   state: Uint8Array;
   accountId: string;
@@ -248,12 +324,87 @@ interface LocalResolver {
   flushAssigned(): Uint8Array;
 }
 //#endregion
+//#region src/materialization.d.ts
+declare namespace MaterializationStore {
+  namespace ReadOp {
+    interface Variant {
+      readonly op: "variant";
+      readonly unit: string;
+      readonly materialization: string;
+      readonly rule: string;
+    }
+    interface Inclusion {
+      readonly op: "inclusion";
+      readonly unit: string;
+      readonly materialization: string;
+    }
+  }
+  type ReadOp = ReadOp.Variant | ReadOp.Inclusion;
+  namespace ReadResult {
+    interface Variant {
+      readonly op: "variant";
+      readonly unit: string;
+      readonly materialization: string;
+      readonly rule: string;
+      readonly variant?: string;
+    }
+    interface Inclusion {
+      readonly op: "inclusion";
+      readonly unit: string;
+      readonly materialization: string;
+      readonly included: boolean;
+    }
+  }
+  type ReadResult = ReadResult.Inclusion | ReadResult.Variant;
+  namespace WriteOp {
+    interface Variant {
+      readonly op: "variant";
+      readonly unit: string;
+      readonly materialization: string;
+      readonly rule: string;
+      readonly variant: string;
+    }
+  }
+  type WriteOp = WriteOp.Variant;
+}
+/**
+* Interface for storing and retrieving materialization data.
+*
+* Implementations can use any storage backend (e.g., Redis, BigTable, Cassandra, DynamoDB,
+* or simple key-value stores) as long as they fulfill this contract.
+*
+* @see The README for conceptual documentation on sticky assignments and materialized segments.
+*/
+interface MaterializationStore {
+  /**
+  * Reads materialization data for the given operations.
+  *
+  * For `variant` operations, returns the stored variant assignment (if any) for a unit/materialization/rule combination.
+  * For `inclusion` operations, returns whether a unit is included in a materialized segment.
+  *
+  * @param readOps - The read operations to perform.
+  * @returns Results for each operation. The order of results does not need to match the order of operations;
+  *          callers match results to operations using the `unit`, `materialization`, and `op` fields.
+  */
+  readMaterializations(readOps: MaterializationStore.ReadOp[]): Promise<MaterializationStore.ReadResult[]>;
+  /**
+  * Persists variant assignments for sticky bucketing.
+  *
+  * This method is optional. Omit it for read-only stores that only serve pre-populated
+  * materialized segments without supporting runtime sticky assignment writes.
+  *
+  * @param writeOps - The variant assignments to persist.
+  */
+  writeMaterializations?(writeOps: MaterializationStore.WriteOp[]): Promise<void>;
+}
+//#endregion
 //#region src/ConfidenceServerProviderLocal.d.ts
 interface ProviderOptions {
   flagClientSecret: string;
   initializeTimeout?: number;
   flushInterval?: number;
   fetch?: typeof fetch;
+  materializationStore?: MaterializationStore | "CONFIDENCE_REMOTE_STORE";
 }
 /**
 * OpenFeature Provider for Confidence Server SDK (Local Mode)
@@ -269,18 +420,13 @@ declare class ConfidenceServerProviderLocal implements Provider {
   private readonly main;
   private readonly fetch;
   private readonly flushInterval;
+  private readonly materializationStore;
   private stateEtag;
   constructor(resolver: LocalResolver, options: ProviderOptions);
   initialize(context?: EvaluationContext): Promise<void>;
   onClose(): Promise<void>;
   evaluate<T>(flagKey: string, defaultValue: T, context: EvaluationContext): Promise<ResolutionDetails<T>>;
-  /**
-  * Internal recursive method for resolving with sticky assignments.
-  *
-  * @private
-  */
-  private resolveWithStickyInternal;
-  private remoteResolve;
+  private resolveWithSticky;
   /**
   * Extract and validate the value from a resolved flag.
   */
@@ -289,6 +435,8 @@ declare class ConfidenceServerProviderLocal implements Provider {
   flush(signal?: AbortSignal): Promise<void>;
   private flushAssigned;
   private sendFlagLogs;
+  private readMaterializations;
+  private writeMaterializations;
   private static convertReason;
   private static convertEvaluationContext;
   /** Resolves with an evaluation of a Boolean flag */
@@ -304,4 +452,4 @@ declare class ConfidenceServerProviderLocal implements Provider {
 //#region src/index.browser.d.ts
 declare function createConfidenceServerProvider(options: ProviderOptions): ConfidenceServerProviderLocal;
 //#endregion
-export { createConfidenceServerProvider };
+export { type MaterializationStore, createConfidenceServerProvider };