refactor: use remote resolver fallback for sticky assignments

Remove MaterializationRepository from public API for now:
- Removed materializationRepository option from ProviderOptions
- Updated provider to always use remote resolver fallback for sticky assignments
- Materializations stored on Confidence servers with 90-day TTL
- Marked MaterializationRepository interface and utilities as WIP

Documentation updates:
- Updated README to explain remote fallback approach
- Added note about upcoming custom storage feature
- Marked MAT_REPO_EXAMPLES.md as work in progress
- Updated tests to reflect remote fallback behavior

The MaterializationRepository feature will be added in a future release
to allow users to connect their own storage (Redis, database, etc.).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: nicklasl

openfeature-provider/js/MAT_REPO_EXAMPLES.md

@@ -1,5 +1,9 @@
 # MaterializationRepository Examples
 
+> **⚠️ WORK IN PROGRESS**
+> This feature is currently in development and not yet available in the public API.
+> The `MaterializationRepository` interface will allow users to provide their own storage backend for sticky assignment materializations.
+
 This document provides implementation examples for custom `MaterializationRepository` implementations.
 
 ## Table of Contents

openfeature-provider/js/README.md

@@ -71,7 +71,6 @@ await provider.onClose();
 - `initializeTimeout` (number, optional): Max ms to wait for initial state fetch. Defaults to 30_000.
 - `flushInterval` (number, optional): Interval in ms for sending evaluation logs. Defaults to 10_000.
 - `fetch` (optional): Custom `fetch` implementation. Required for Node < 18; for Node 18+ you can omit.
-- `materializationRepository` (optional): Custom storage for sticky assignments. See [Sticky Assignments](#sticky-assignments) below.
 
 The provider periodically:
 - Refreshes resolver state (default every 30s)
@@ -81,7 +80,7 @@ The provider periodically:
 
 ## Sticky Assignments
 
-Confidence supports "sticky" flag assignments to ensure users receive consistent variant assignments even when their context changes or flag configurations are updated. 
+Confidence supports "sticky" flag assignments to ensure users receive consistent variant assignments even when their context changes or flag configurations are updated.
 
 ### How it works
 
@@ -90,66 +89,38 @@ When a flag is evaluated for a user, Confidence creates a "materialization" - a
 - The flag's targeting rules are modified
 - New assignments are paused
 
-### Default behavior (no repository)
+### Implementation
 
-If you don't provide a `materializationRepository`, the provider automatically falls back to resolve with our cloud resolvers:
-- Materializations are stored on Confidence servers with a 90-day TTL
+The provider uses a **remote resolver fallback** for sticky assignments:
+- First, the local WASM resolver attempts to resolve the flag
+- If sticky assignment data is needed, the provider makes a network call to Confidence's cloud resolvers
+- Materializations are stored on Confidence servers with a **90-day TTL** (automatically renewed on access)
 - No local storage or database setup required
-- Best for most use cases
 
 ```ts
 const provider = createConfidenceServerProvider({
   flagClientSecret: process.env.CONFIDENCE_FLAG_CLIENT_SECRET!,
   apiClientId: process.env.CONFIDENCE_API_CLIENT_ID!,
   apiClientSecret: process.env.CONFIDENCE_API_CLIENT_SECRET!,
-  // materializationRepository is optional - uses remote storage by default
 });
-```
 
-### Custom storage with MaterializationRepository
+// Sticky assignments work automatically via remote fallback
+const client = OpenFeature.getClient();
+const value = await client.getBooleanValue('my-flag', false, {
+  targetingKey: 'user-123'
+});
+```
 
-For advanced use cases where you want full control over materialization storage (e.g., Redis, database, file system), implement the `MaterializationRepository` interface:
+### Benefits
 
-```ts
-interface MaterializationRepository {
-  /**
-   * Load ALL stored materialization assignments for a targeting unit.
-   *
-   * @param unit - The targeting key (e.g., user ID, session ID)
-   * @param materialization - The materialization ID being requested (for context)
-   * @returns Map of materialization ID to MaterializationInfo for this unit
-   */
-  loadMaterializedAssignmentsForUnit(
-    unit: string,
-    materialization: string
-  ): Promise<Map<string, MaterializationInfo>>;
-
-  /**
-   * Store materialization assignments for a targeting unit.
-   *
-   * @param unit - The targeting key (e.g., user ID, session ID)
-   * @param assignments - Map of materialization ID to MaterializationInfo
-   */
-  storeAssignment(
-    unit: string,
-    assignments: Map<string, MaterializationInfo>
-  ): Promise<void>;
-
-  /**
-   * Close and cleanup any resources used by this repository.
-   */
-  close(): void | Promise<void>;
-}
-```
+- **Zero configuration**: Works out of the box with no additional setup
+- **Managed storage**: Confidence handles all storage, TTL, and consistency
+- **Automatic renewal**: TTL is refreshed on each access
+- **Global availability**: Materializations are available across all your services
 
-**Key points:**
-- `loadMaterializedAssignmentsForUnit` should return ALL materializations for the given unit, not just the one requested
-- This allows efficient bulk loading from your storage system
-- The provider handles caching and coordination internally
+### Coming Soon: Custom Materialization Storage
 
-See [MAT_REPO_EXAMPLES.md](./MAT_REPO_EXAMPLES.md) for complete implementation examples including:
-- In-memory repository for testing
-- File-backed repository for persistent storage
+We're working on support for connecting your own materialization storage repository (Redis, database, file system, etc.) to eliminate network calls for sticky assignments and have full control over storage. This feature is currently in development.
 
 ---
 

openfeature-provider/js/src/ConfidenceServerProviderLocal.test.ts

@@ -158,7 +158,9 @@ describe('no network', () => {
 describe('sticky resolve', () => {
   const RESOLVE_REASON_MATCH = 1;
 
-  describe('with MaterializationRepository strategy', () => {
+  // TODO: WIP - MaterializationRepository support
+  // These tests will be re-enabled when MaterializationRepository is implemented
+  describe.skip('with MaterializationRepository strategy', () => {
     let mockRepository: MockedObject<MaterializationRepository>;
     let providerWithRepo: ConfidenceServerProviderLocal;
 
@@ -353,7 +355,7 @@ describe('sticky resolve', () => {
     });
   });
 
-  describe('without MaterializationRepository (uses RemoteResolverFallback)', () => {
+  describe('remote resolver fallback for sticky assignments', () => {
     let providerWithFallback: ConfidenceServerProviderLocal;
 
     beforeEach(async () => {
@@ -362,7 +364,7 @@ describe('sticky resolve', () => {
         apiClientId: 'apiClientId',
         apiClientSecret: 'apiClientSecret',
         fetch: mockedFetch
-        // No materializationRepository - will use RemoteResolverFallback
+        // Uses remote resolver fallback for sticky assignments
       });
 
       await providerWithFallback.initialize();
@@ -431,7 +433,7 @@ describe('sticky resolve', () => {
       expect(remoteResolveEndpoint).toHaveBeenCalledTimes(1);
     });
 
-    it('should not store updates when no repository configured', async () => {
+    it('should handle updates with remote fallback (no local storage)', async () => {
       mockedWasmResolver.resolveWithSticky.mockReturnValue({
         success: {
           response: {
@@ -459,8 +461,8 @@ describe('sticky resolve', () => {
         targetingKey: 'user-1'
       });
 
-      // Should not try to store when no repository is configured
-      // (success - no exception thrown)
+      // Updates are handled by remote resolver, not stored locally
+      // Verify no remote resolve was needed (successful local resolve)
       expect(remoteResolveEndpoint).not.toHaveBeenCalled();
     });
   });

openfeature-provider/js/src/ConfidenceServerProviderLocal.ts

@@ -19,8 +19,9 @@ import {
 import { Fetch, FetchMiddleware, withAuth, withLogging, withResponse, withRetry, withRouter, withStallTimeout, withTimeout } from './fetch';
 import { scheduleWithFixedInterval, timeoutSignal, TimeUnit } from './util';
 import { AccessToken, LocalResolver, ResolveStateUri } from './LocalResolver';
-import type { MaterializationRepository } from './MaterializationRepository';
-import { handleMissingMaterializations, storeUpdates } from './materializationUtils';
+// TODO: WIP - MaterializationRepository support
+// import type { MaterializationRepository } from './MaterializationRepository';
+// import { handleMissingMaterializations, storeUpdates } from './materializationUtils';
 
 export const DEFAULT_STATE_INTERVAL = 30_000;
 export const DEFAULT_FLUSH_INTERVAL = 10_000;
@@ -31,7 +32,6 @@ export interface ProviderOptions {
   initializeTimeout?:number,
   flushInterval?:number,
   fetch?: typeof fetch,
-  materializationRepository?: MaterializationRepository,
 }
 
 /**
@@ -49,7 +49,6 @@ export class ConfidenceServerProviderLocal implements Provider {
   private readonly main = new AbortController();
   private readonly fetch:Fetch;
   private readonly flushInterval:number;
-  private readonly materializationRepository?: MaterializationRepository;
   private stateEtag:string | null = null;
 
 
@@ -58,7 +57,6 @@ export class ConfidenceServerProviderLocal implements Provider {
     // TODO better error handling
     // TODO validate options
     this.flushInterval = options.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
-    this.materializationRepository = options.materializationRepository;
     const withConfidenceAuth = withAuth(async () => {
       const { accessToken, expiresIn } = await this.fetchToken();
       return [accessToken, new Date(Date.now() + 1000*expiresIn)]
@@ -130,15 +128,14 @@ export class ConfidenceServerProviderLocal implements Provider {
   async onClose(): Promise<void> {
     this.main.abort();
     await this.flush();
-    await this.materializationRepository?.close();
   }
 
   // TODO test unknown flagClientSecret
   async evaluate<T>(flagKey: string, defaultValue: T, context: EvaluationContext): Promise<ResolutionDetails<T>> {
     const [flagName, ...path] = flagKey.split('.');
 
     // Build resolve request
-    // Always use sticky resolve request
+    // Always use sticky resolve request with remote fallback
     const stickyRequest: ResolveWithStickyRequest = {
       resolveRequest: {
         flags: [`flags/${flagName}`],
@@ -147,7 +144,7 @@ export class ConfidenceServerProviderLocal implements Provider {
         clientSecret: this.options.flagClientSecret
       },
       materializationsPerUnit: {},
-      failFastOnSticky: !this.materializationRepository
+      failFastOnSticky: true  // Always fail fast - use remote resolver for sticky assignments
     };
 
     const response = await this.resolveWithStickyInternal(stickyRequest);
@@ -156,7 +153,7 @@ export class ConfidenceServerProviderLocal implements Provider {
 
   /**
    * Internal recursive method for resolving with sticky assignments.
-   * 
+   *
    * @private
    */
   private async resolveWithStickyInternal(
@@ -167,11 +164,12 @@ export class ConfidenceServerProviderLocal implements Provider {
     if (response.success && response.success.response) {
       const { response: flagsResponse, updates } = response.success;
 
+      // TODO: WIP - MaterializationRepository support
       // Store updates if present (only for MaterializationRepository)
       // Fire-and-forget - doesn't block resolve path
-      if (updates.length > 0 && this.materializationRepository) {
-        storeUpdates(updates, this.materializationRepository);
-      }
+      // if (updates.length > 0 && this.materializationRepository) {
+      //   storeUpdates(updates, this.materializationRepository);
+      // }
 
       return flagsResponse;
     }
@@ -180,18 +178,21 @@ export class ConfidenceServerProviderLocal implements Provider {
     if (response.missingMaterializations) {
       const { items } = response.missingMaterializations;
 
-      // If we don't have a MaterializationRepository, use the remote resolver fallback
-      if (!this.materializationRepository) {
-        return await this.remoteResolve(request.resolveRequest!);
-      }
-
-      // Handle MaterializationRepository case
-      const updatedRequest = await handleMissingMaterializations(
-        request,
-        items,
-        this.materializationRepository
-      );
-      return this.resolveWithStickyInternal(updatedRequest);
+      // Use remote resolver fallback for sticky assignments
+      // Materializations are stored on Confidence servers with 90-day TTL
+      return await this.remoteResolve(request.resolveRequest!);
+
+      // TODO: WIP - MaterializationRepository support
+      // When MaterializationRepository is implemented, the logic will be:
+      // if (!this.materializationRepository) {
+      //   return await this.remoteResolve(request.resolveRequest!);
+      // }
+      // const updatedRequest = await handleMissingMaterializations(
+      //   request,
+      //   items,
+      //   this.materializationRepository
+      // );
+      // return this.resolveWithStickyInternal(updatedRequest);
     }
 
     throw new Error('Invalid response: resolve result not set');

openfeature-provider/js/src/MaterializationRepository.ts

@@ -1,10 +1,18 @@
+// ============================================================================
+// WIP: MaterializationRepository - Custom Storage for Sticky Assignments
+// ============================================================================
+// This interface is currently in development and not yet part of the public API.
+// When complete, it will allow users to provide their own storage backend
+// (Redis, database, file system, etc.) for sticky assignment materializations.
+// ============================================================================
+
 import type {
   MaterializationInfo,
 } from './proto/api';
 
 
 /**
- * Strategy for storing and loading materialized assignments locally.
+ * WIP: Strategy for storing and loading materialized assignments locally.
  *
  * Use this when you want to:
  * - Store assignments in a database, Redis, or other persistent storage

openfeature-provider/js/src/materializationUtils.ts

@@ -1,3 +1,10 @@
+// ============================================================================
+// WIP: Materialization Utilities - Helper functions for MaterializationRepository
+// ============================================================================
+// These utilities are currently in development and not yet part of the public API.
+// They support the MaterializationRepository feature for custom sticky assignment storage.
+// ============================================================================
+
 import type {
   MaterializationInfo,
   MaterializationMap,
@@ -8,7 +15,7 @@ import type {
 import type { MaterializationRepository } from './MaterializationRepository';
 
 /**
- * Handle missing materializations by loading from repository and building updated request.
+ * WIP: Handle missing materializations by loading from repository and building updated request.
  * Matches Java implementation logic.
  */
 export async function handleMissingMaterializations(