@terreno/mcp 57.15.0 → 57.16.2

package/src/docs/versioned/0.29.0/implementationPlans/feature-flags-openfeature.md

@@ -1,545 +0,0 @@
-# Implementation Plan: OpenFeature Adoption for `@terreno/feature-flags`
-
-## Goal
-
-Migrate `@terreno/feature-flags` (backend) and `@terreno/rtk`'s `useFeatureFlags` (frontend) to be built on top of the OpenFeature SDKs (`@openfeature/server-sdk`, `@openfeature/react-sdk`) while preserving:
-- The Mongoose-backed `FeatureFlag` model as source of truth (no data migration)
-- The current admin UI via `@terreno/admin-backend`
-- Backwards-compatible `useFeatureFlags()` API for downstream consumers
-- The single-bulk-fetch network shape (no per-flag round trips)
-
-And add:
-- A swappable, OpenFeature-standard provider abstraction on the backend (`MongoFeatureFlagProvider`)
-- Standard OpenFeature React hooks (`useBooleanFlagValue`, `useStringFlagValue`, `<FeatureFlag>`, etc.) available to consumers
-- Live updates via Mongoose change streams + Socket.io + OpenFeature `PROVIDER_CONFIGURATION_CHANGED` events
-- Type-safe flag keys via OpenFeature's module augmentation pattern
-
-## Non-goals
-
-- Replacing Mongo storage with flagd or a third-party flag service
-- Dropping the existing admin panel UX
-- Adding analytics or experiment-results tracking (out of scope; the OF tracking hook is available to consumers but not wired up here)
-- Allowing anonymous evaluation (stays `IsAuthenticated`)
-
----
-
-## Models
-
-### `FeatureFlag` (extended, no migration)
-
-**File**: `feature-flags/src/featureFlagModel.ts`
-
-One new field on the existing schema:
-
-```typescript
-defaultVariant: {
-  type: String,
-  description:
-    "OpenFeature defaultVariant key. Returned when the flag is disabled or " +
-    "errors during evaluation. For boolean flags, must be 'on' or 'off'. " +
-    "For variant flags, must be one of the keys in `variants`. " +
-    "Auto-populated by pre-save hook for legacy docs (boolean → 'off', variant → first variant key).",
-},
-```
-
-**No Mongoose getter** — we use a `pre("save")` hook that sets `defaultVariant` when it is `undefined`, plus a normalization step in the `/flagConfiguration` build path that supplies the default at read time without mutating the doc. This avoids getter re-entrancy on `this.type` / `this.variants`.
-
-Validation (in the existing `pre("save")` hook):
-- If `defaultVariant` is set: for boolean flags it must be `"on"` or `"off"`; for variant flags it must be one of `variants[].key`. Validation is **only enforced when the field is set** — legacy docs without `defaultVariant` are not rejected; the hook populates the default before the validate step.
-- Tested explicitly in `featureFlagModel.test.ts` with both legacy-doc-update and new-doc-create paths.
-
-Also update `featureFlagAdminConfig.listFields` to include `"defaultVariant"` so admins see and can edit it.
-
-### `FlagConfiguration` (wire shape, not a Mongoose model)
-
-The response shape returned by the new `/feature-flags/flagConfiguration` endpoint. One entry per evaluated flag:
-
-```typescript
-interface FlagDefinition {
-  variants: Record<string, boolean | string>;  // {on: true, off: false} or {compact: "compact", detailed: "detailed"}
-  disabled: boolean;                            // per-user resolved disabled state
-  defaultVariant: string;
-}
-
-interface FlagConfigurationResponse {
-  data: Record<string, FlagDefinition>;
-}
-```
-
-This exactly matches OpenFeature's `TypedInMemoryProvider` input shape, so the frontend pipes it straight in.
-
----
-
-## APIs
-
-### Backend: `MongoFeatureFlagProvider`
-
-**File**: `feature-flags/src/openFeatureProvider.ts` (new)
-
-A custom OpenFeature server-side provider that delegates to the existing `evaluateFlag()` logic.
-
-```typescript
-import {
-  type EvaluationContext,
-  type JsonValue,
-  OpenFeatureEventEmitter,
-  type Provider,
-  type ResolutionDetails,
-} from "@openfeature/server-sdk";
-import type {Model} from "mongoose";
-import {evaluateFlag} from "./evaluate";
-import type {FeatureFlagDocument, SegmentFunction} from "./types";
-
-interface MongoFeatureFlagProviderOptions {
-  flagModel: Model<FeatureFlagDocument>;
-  segments?: Record<string, SegmentFunction>;
-}
-
-export class MongoFeatureFlagProvider implements Provider {
-  readonly metadata = {name: "MongoFeatureFlagProvider"} as const;
-  readonly runsOn = "server" as const;
-  readonly events = new OpenFeatureEventEmitter();
-
-  private flagModel: Model<FeatureFlagDocument>;
-  private segments: Record<string, SegmentFunction>;
-
-  constructor(options: MongoFeatureFlagProviderOptions) {
-    this.flagModel = options.flagModel;
-    this.segments = options.segments ?? {};
-  }
-
-  async resolveBooleanEvaluation(
-    flagKey: string,
-    defaultValue: boolean,
-    context: EvaluationContext
-  ): Promise<ResolutionDetails<boolean>> {
-    return this.resolve<boolean>(flagKey, defaultValue, context, "boolean");
-  }
-
-  async resolveStringEvaluation(
-    flagKey: string,
-    defaultValue: string,
-    context: EvaluationContext
-  ): Promise<ResolutionDetails<string>> {
-    return this.resolve<string>(flagKey, defaultValue, context, "variant");
-  }
-
-  async resolveNumberEvaluation(
-    flagKey: string,
-    defaultValue: number
-  ): Promise<ResolutionDetails<number>> {
-    // Not supported in v1 — return default with FLAG_NOT_FOUND
-    return {value: defaultValue, reason: "ERROR", errorCode: "FLAG_NOT_FOUND" as const};
-  }
-
-  async resolveObjectEvaluation<T extends JsonValue>(
-    flagKey: string,
-    defaultValue: T
-  ): Promise<ResolutionDetails<T>> {
-    return {value: defaultValue, reason: "ERROR", errorCode: "FLAG_NOT_FOUND" as const};
-  }
-
-  private async resolve<T extends boolean | string>(
-    flagKey: string,
-    defaultValue: T,
-    context: EvaluationContext,
-    expectedType: "boolean" | "variant"
-  ): Promise<ResolutionDetails<T>> {
-    // Use findOneOrNone per repo rule (never Model.findOne); the FeatureFlag schema has the plugin.
-    const flag = await this.flagModel.findOneOrNone({key: flagKey, archived: {$ne: true}});
-    if (!flag) {
-      return {value: defaultValue, reason: "ERROR", errorCode: "FLAG_NOT_FOUND" as const};
-    }
-    if (flag.type !== expectedType) {
-      return {value: defaultValue, reason: "ERROR", errorCode: "TYPE_MISMATCH" as const};
-    }
-    if (!flag.enabled) {
-      return {value: defaultValue, reason: "DISABLED", variant: flag.defaultVariant};
-    }
-    const targetingKey = context.targetingKey ?? "";
-    const user = context.user ?? context;  // accept either {targetingKey, user: {...}} or flat
-    const result = evaluateFlag(flag, targetingKey, user, this.segments);
-    if (expectedType === "boolean") {
-      const value = (result as boolean) as T;
-      return {value, reason: "TARGETING_MATCH", variant: value ? "on" : "off"};
-    }
-    if (result === null) {
-      return {value: defaultValue, reason: "DISABLED", variant: flag.defaultVariant};
-    }
-    return {value: result as T, reason: "TARGETING_MATCH", variant: result as string};
-  }
-
-  /** Called by the live-updates hook when a flag doc changes. */
-  emitConfigurationChanged(): void {
-    this.events.emit("PROVIDER_CONFIGURATION_CHANGED");
-  }
-}
-```
-
-The existing `evaluate.ts` is unchanged. The provider is a thin adapter.
-
-### Backend: `FeatureFlagsApp` (updated)
-
-**File**: `feature-flags/src/featureFlagsApp.ts` (updated)
-
-New responsibilities:
-1. Construct `MongoFeatureFlagProvider` and call `OpenFeature.setProvider(provider, "feature-flags")` (using a domain so we don't stomp on consumer providers).
-2. Register a new `GET /feature-flags/flagConfiguration` endpoint that returns the `FlagConfiguration` shape.
-3. Keep the existing `GET /feature-flags/evaluate` endpoint working for one release with a deprecation warning header (`Deprecation: true`, `Sunset: <date>`).
-4. Keep admin CRUD via `modelRouter` (unchanged).
-5. If `liveUpdates.socketIoServer` is provided in options, start a Mongoose change stream on the FeatureFlag collection and emit a `featureFlagsChanged` socket event to all connected clients, plus call `provider.emitConfigurationChanged()`.
-
-Updated options:
-
-```typescript
-interface FeatureFlagsOptions {
-  basePath?: string;
-  segments?: Record<string, SegmentFunction>;
-  permissions?: ModelRouterOptions<FeatureFlagDocument>["permissions"];
-  segmentsPermission?: (user: unknown) => boolean;
-  /** Optional Socket.io Server instance for live updates. */
-  liveUpdates?: {
-    socketIoServer: SocketIOServer;
-    /** Custom event name. Default: "featureFlagsChanged". */
-    eventName?: string;
-  };
-  /** Optional. Defaults to a private domain ("feature-flags") so the global default provider is left alone. */
-  openFeatureDomain?: string;
-}
-```
-
-The `/flagConfiguration` endpoint:
-
-```typescript
-app.get(
-  `${basePath}/flagConfiguration`,
-  authenticateMiddleware(),
-  asyncHandler(async (req, res) => {
-    const user = req.user as {_id?: unknown; id?: string} | undefined;
-    if (!user) throw new APIError({status: 401, title: "Authentication required"});
-    const targetingKey = String(user._id ?? user.id);
-    // Match existing evaluateAllFlags() filter — only enabled, non-archived flags ship to clients.
-    // Disabled or archived flags are omitted, matching current behavior where Object.keys(flags)
-    // does NOT include disabled flag keys.
-    const flags = await FeatureFlag.find({archived: {$ne: true}, enabled: true});
-    const config: Record<string, FlagDefinition> = {};
-    for (const flag of flags) {
-      config[flag.key] = buildFlagDefinition(flag, targetingKey, user, this.segments);
-    }
-    return res.json({data: config});
-  })
-);
-```
-
-`buildFlagDefinition` reuses `evaluateFlag()` to determine the resolved value for *this* user, then builds the OF variant shape. **Because `/flagConfiguration` only ships enabled, non-archived flags**, `disabled: false` for every entry in the response (we never embed disabled flags; consumers see them only via the admin panel). The `disabled` field stays in the type for parity with OF's `FlagConfiguration` shape:
-
-- Boolean flag → `variants: {on: true, off: false}`, `defaultVariant: result ? "on" : "off"`, `disabled: false`
-- Variant flag → `variants: {variantKey: variantKey, ...}` (identity map), `defaultVariant: result` (the existing `evaluateFlag()` guarantees a non-null string when `flag.enabled`), `disabled: false`
-
-Setting `defaultVariant` to the *resolved* value for this user makes `useBooleanFlagValue` on the frontend Just Work without re-running targeting logic on the client.
-
-### Backend: legacy `/evaluate` (deprecated, kept for one release)
-
-The legacy endpoint stays. It calls `evaluateAllFlags()` exactly as today and returns the old `Record<string, boolean | string | null>` shape, plus a `Deprecation: true` header and a `Sunset` header set to 90 days out. A `logger.warn` fires once per process when first called.
-
----
-
-## Frontend
-
-### New hook: `useTerrenoFeatureFlags`
-
-**File**: `rtk/src/useTerrenoFeatureFlags.ts` (new)
-
-```typescript
-import {OpenFeature, TypedInMemoryProvider} from "@openfeature/web-sdk";
-
-interface UseTerrenoFeatureFlagsOptions {
-  basePath?: string;             // default: "/feature-flags"
-  skip?: boolean;                // skip fetch until userId is known
-  userId?: string | null;        // current user id — when this changes, refetch & re-bucket
-  socket?: Socket | null;        // optional socket for live updates
-  socketEventName?: string;      // default: "featureFlagsChanged"
-  domain?: string;               // OF provider domain — default: "feature-flags"
-}
-
-interface UseTerrenoFeatureFlagsResult {
-  flags: FlagConfiguration;
-  isLoading: boolean;             // true until BOTH RTK query resolves AND OF PROVIDER_READY
-  error: unknown;
-  refetch: () => void;
-  client: Client;                 // OpenFeature client bound to this hook's domain
-}
-
-export const useTerrenoFeatureFlags = (
-  api: Api<any, any, any, any>,
-  options?: UseTerrenoFeatureFlagsOptions
-): UseTerrenoFeatureFlagsResult => {
-  // 1. RTK Query bulk fetch /feature-flags/flagConfiguration. Cache key INCLUDES userId so a
-  //    different user gets a fresh fetch (no stale per-user resolved values).
-  // 2. On userId change: api.util.invalidateTags(["feature-flags"]) AND OpenFeature.setContext(
-  //    domain, {targetingKey: userId}) before the refetch lands.
-  // 3. On data success: await OpenFeature.setProvider(domain, new TypedInMemoryProvider(flags)).
-  //    isLoading stays true until the PROVIDER_READY event fires (subscribed via client.addHandler).
-  // 4. If options.socket: subscribe to socketEventName → refetch.
-  // 5. Cleanup: do NOT clear the provider on unmount of an individual instance — multiple
-  //    components may use useFeatureFlags simultaneously. Use a small ref-count module-level
-  //    counter; only clear (OpenFeature.clearProviders) when the count returns to zero.
-  // 6. StrictMode safety: setProvider is idempotent for the same data, but track an in-flight
-  //    promise with a ref to prevent double-setting during the StrictMode double-mount window.
-};
-```
-
-Critical behaviors:
-- **User switching**: the cache key for the RTK Query endpoint must include `userId` so different users get different cache entries. On `userId` change, the hook calls `OpenFeature.setContext(domain, {targetingKey: userId})` and `refetch()`. The provider is replaced with the new user's values once the new fetch lands. `isLoading` returns to `true` during the transition.
-- **`isLoading` semantics**: `isLoading: true` until RTK Query has data AND OpenFeature has emitted `PROVIDER_READY` for the new provider. This avoids the race where `useBooleanFlagValue` returns `defaultValue` before the provider is ready.
-- **No provider clearing on individual unmount** (avoids breaking other mounted consumers).
-
-### Updated BC wrapper: `useFeatureFlags`
-
-**File**: `rtk/src/useFeatureFlags.ts` (rewritten as a thin wrapper)
-
-```typescript
-export const useFeatureFlags = (
-  api: Api<any, any, any, any>,
-  basePathOrOptions?: string | UseFeatureFlagsOptions
-): UseFeatureFlagsResult => {
-  const {basePath, skip} = resolveFeatureFlagsOptions(basePathOrOptions);
-  const {flags, isLoading, error, refetch, client} = useTerrenoFeatureFlags(api, {basePath, skip});
-
-  const getFlag = useCallback(
-    (key: string): boolean => client.getBooleanValue(key, false),
-    [client]
-  );
-
-  const getVariant = useCallback(
-    (key: string): string | null => {
-      // The InMemoryProvider doesn't natively report reason "DISABLED" — disabled flags are
-      // omitted from /flagConfiguration entirely. So absence in `flags` (the raw FlagConfiguration
-      // map returned by useTerrenoFeatureFlags) means the flag is disabled/missing and we return null.
-      if (!flags[key]) return null;
-      const value = client.getStringValue(key, "");
-      return value === "" ? null : value;
-    },
-    [client, flags]
-  );
-
-  // Build a Record<string, boolean | string | null> view from the FlagConfiguration to preserve
-  // the existing flags API surface used by example-frontend profile.tsx (which iterates
-  // Object.keys(flags) and renders {value: boolean|string|null}).
-  //
-  // Projection from FlagDefinition → BC value:
-  //   - boolean flag → variants[defaultVariant]    // true or false
-  //   - variant flag → defaultVariant              // string variant key
-  // Disabled flags are omitted from /flagConfiguration so they never appear in this map,
-  // which matches today's behavior where evaluateAllFlags filters enabled: true.
-  const flatFlags = useMemo<Record<string, boolean | string | null>>(() => {
-    const out: Record<string, boolean | string | null> = {};
-    for (const [key, def] of Object.entries(flags)) {
-      const value = def.variants[def.defaultVariant];
-      out[key] = value ?? null;
-    }
-    return out;
-  }, [flags]);
-
-  return {flags: flatFlags, getFlag, getVariant, isLoading, error, refetch};
-};
-```
-
-`useFeatureFlags`'s return type is unchanged from today, including `flags: Record<string, boolean | string | null>` whose **keys and values match the prior `/evaluate` payload byte-for-byte for enabled flags**. Existing consumers in `example-frontend/app/(tabs)/index.tsx:105` and `profile.tsx` keep working without edits.
-
-A snapshot test in Phase 2 will lock down this projection against the existing `profile.tsx` rendering output.
-
-### Direct OpenFeature usage (recommended for new code)
-
-Consumers add `@openfeature/react-sdk` as a direct dep and use OF hooks directly:
-
-```typescript
-import {useBooleanFlagValue, useStringFlagValue, FeatureFlag} from "@openfeature/react-sdk";
-
-const showSummary = useBooleanFlagValue("todo-summary-card", false);
-const layout = useStringFlagValue("profile-layout", "compact");
-
-return (
-  <FeatureFlag flagKey="ai-features" defaultValue={false}>
-    <AiFeaturesTab />
-  </FeatureFlag>
-);
-```
-
-`@terreno/rtk` does **not** re-export OpenFeature hooks. Consumers add `@openfeature/react-sdk` to their `package.json` and import directly. (Decision per shaping question.)
-
-**Note for consumers**: `useNumberFlagValue` and `useObjectFlagValue` always return the `defaultValue` with this provider — `MongoFeatureFlagProvider` supports only boolean and string (variant) flags, so number/object resolution returns `FLAG_NOT_FOUND` `ResolutionDetails`. Documented in `feature-flags.md` reference.
-
-### SDK regen and the new endpoint
-
-Today's `useFeatureFlags` manually injects the `/evaluate` endpoint via RTK Query (`api.injectEndpoints`) because the hook lives in `@terreno/rtk` and runs without depending on consumer-app SDK codegen. We keep the same pattern for `useTerrenoFeatureFlags` — it manually injects `/flagConfiguration` via `api.injectEndpoints`. **The consumer's SDK regen (`bun run sdk`) will ALSO emit a generated hook for `/flagConfiguration`** — that's fine; the generated hook is unused but harmless. To prevent confusion, document in `feature-flags.md` that consumers should call `useTerrenoFeatureFlags`/`useFeatureFlags`, not the generated `useGetFeatureFlagsFlagConfigurationQuery` hook from `openApiSdk.ts`. No rip-out of manual injection.
-
-### Wiring in `example-frontend`
-
-**File**: `example-frontend/app/_layout.tsx` (updated)
-
-Wrap the app in `<OpenFeatureProvider domain="feature-flags">`. Add `useTerrenoFeatureFlags(api, {socket})` at the top level after auth so the provider is set as soon as the user is known. Both must come *after* the Redux Provider since the hook uses RTK Query.
-
----
-
-## Live Updates
-
-### Backend
-
-Inside `FeatureFlagsApp.register()`, if `liveUpdates.socketIoServer` is provided:
-
-1. Start a Mongoose change stream: `FeatureFlag.watch([], {fullDocument: "updateLookup"})`.
-2. On any change event, emit `liveUpdates.socketIoServer.emit("featureFlagsChanged", {key: change.fullDocument?.key})`.
-3. Also call `provider.emitConfigurationChanged()` so any server-side OF clients with cached values invalidate (mostly future-proofing; we don't cache on the server today).
-4. Handle the stream's `error` event by logging and attempting one reconnect; subsequent errors disable the stream and log a warning to the consumer.
-5. On `app.close()` (if `TerrenoApp` exposes a shutdown hook — add one if not), call `stream.close()`.
-
-**Requirement to document**: Mongoose change streams require MongoDB to run as a replica set (even a single-node replica set is fine). The `add-feature-flags.md` how-to gets a new "Live updates" section that calls this out.
-
-### Frontend
-
-Inside `useTerrenoFeatureFlags`, if `options.socket` is provided:
-
-1. Subscribe to `socket.on(options.socketEventName ?? "featureFlagsChanged", handler)`.
-2. Handler calls `refetch()` on the RTK Query endpoint.
-3. The fresh data triggers a fresh `OpenFeature.setProvider(domain, new TypedInMemoryProvider(...))`.
-4. OpenFeature React SDK auto-re-renders all `useBooleanFlagValue` / `useStringFlagValue` consumers (this is its built-in behavior on `PROVIDER_CONFIGURATION_CHANGED`).
-5. Cleanup: `socket.off(eventName, handler)` on unmount.
-
-If `options.socket` is not provided, the hook falls back to RTK Query's existing refetch-on-mount behavior. Live updates are strictly opt-in.
-
----
-
-## Type-Safe Flag Keys
-
-Document in `docs/reference/feature-flags.md` how consumers can narrow flag-key types using module augmentation:
-
-```typescript
-// example-frontend/types/openfeature.d.ts
-declare module "@openfeature/core" {
-  export type BooleanFlagKey = "todo-summary-card" | "dark-mode-toggle" | "ai-features" | "todo-priority";
-  export type StringFlagKey = "profile-layout";
-}
-```
-
-After this, `useBooleanFlagValue("typo", false)` fails at compile time. Optional per-consumer; not required to use the feature flag package.
-
----
-
-## Notifications
-
-None needed (live updates use Socket.io directly, not the notifier system).
-
----
-
-## UI
-
-No new dedicated screens. The admin panel (auto-generated from `FeatureFlag` schema via `@terreno/admin-backend`) continues to work as today and now also exposes the new `defaultVariant` field automatically because `mongoose-to-swagger` picks up its description.
-
-`example-frontend/app/(tabs)/profile.tsx` gets a small additional debug view: alongside the existing "all flags" card, display each flag's `reason` (TARGETING_MATCH / DISABLED / ERROR) via `useBooleanFlagDetails` to demonstrate OF metadata is available.
-
----
-
-## Phases
-
-### Phase 1 — Backend OpenFeature integration
-
-Goal: server-side provider is in place and the new endpoint returns OF-shape responses; existing tests still pass; legacy endpoint kept.
-
-- Add `@openfeature/server-sdk` to `feature-flags/package.json`.
-- Add `defaultVariant` field + validation + computed-default getter to `FeatureFlag` schema. Update `types.ts` accordingly. Update existing pre-save validation to also check `defaultVariant` shape (boolean → "on"/"off"; variant → must be in variants).
-- Create `feature-flags/src/openFeatureProvider.ts` with `MongoFeatureFlagProvider` as specified above.
-- Update `feature-flags/src/featureFlagsApp.ts`:
-  - On `register()`, construct the provider with `{flagModel: FeatureFlag, segments: this.segments}` and call `OpenFeature.setProvider(domain, provider)` (domain = `openFeatureDomain ?? "feature-flags"`).
-  - Add the new `/flagConfiguration` route.
-  - Keep the existing `/evaluate` route but emit the deprecation headers + one-shot warn log.
-- Add tests:
-  - `feature-flags/src/tests/openFeatureProvider.test.ts` — boolean and variant resolution, disabled flags, type mismatch, missing flag, targetingKey hashing, rule + segment paths, missing targetingKey.
-  - Extend `featureFlagsApp.test.ts` — `/flagConfiguration` returns the right OF shape for both boolean and variant flags; respects archived/enabled; verifies `defaultVariant` propagation; verifies `/evaluate` still works and includes `Deprecation` header.
-- Update `feature-flags/src/index.ts` to export `MongoFeatureFlagProvider`.
-
-**Exit criteria**: `bun run test --filter=@terreno/feature-flags` and `bun run compile` pass. The new endpoint returns a valid `FlagConfiguration` for a logged-in user.
-
-### Phase 2 — Frontend OpenFeature integration
-
-Goal: `useTerrenoFeatureFlags` exists; legacy `useFeatureFlags` works as a thin BC wrapper; example app renders identically.
-
-- Add `@openfeature/web-sdk`, `@openfeature/react-sdk`, and `@openfeature/core` to `rtk/package.json` (peer dep `react`).
-- Create `rtk/src/useTerrenoFeatureFlags.ts` (RTK Query bulk fetch → `TypedInMemoryProvider` → `OpenFeature.setProvider(domain, ...)` + `setContext(domain, {targetingKey})`).
-- Rewrite `rtk/src/useFeatureFlags.ts` as a thin wrapper preserving today's `{flags, getFlag, getVariant, isLoading, error, refetch}` API. Same overload signature (string | options object). `getVariant` returns `null` when `reason === "DISABLED" || "ERROR"`.
-- Update `rtk/src/useFeatureFlags.test.ts` to validate against the new `FlagConfiguration` payload shape. Add `useTerrenoFeatureFlags.test.ts` covering: success path, skip behavior, refetch, domain isolation (doesn't affect the global default provider).
-- Update `rtk/src/index.ts` to export `useTerrenoFeatureFlags`. **Do not** re-export OpenFeature hooks per shaping decision.
-
-**Exit criteria**: `bun run test --filter=@terreno/rtk` and `bun run compile` pass. Calling code in `example-frontend` works without code edits.
-
-### Phase 3 — Live updates (opt-in)
-
-Goal: admin edits propagate to connected clients without a page refresh.
-
-- Backend: in `FeatureFlagsApp.register()`, if `liveUpdates.socketIoServer` is provided, start `FeatureFlag.watch()` and emit `featureFlagsChanged` on each change. Wire to `provider.emitConfigurationChanged()` too.
-- Backend tests: `featureFlagsApp.liveUpdates.test.ts` — given a mocked socket.io server, mutating a flag triggers an emission with the expected event payload. Use the in-memory MongoDB test rig and a real replica set if available; otherwise mock the change stream.
-- Frontend: in `useTerrenoFeatureFlags`, if `options.socket` is provided, subscribe to the event name and call `refetch()` on each. Verify the OF re-render is triggered (component snapshot test).
-- Documentation: add a "Live updates" section to `docs/how-to/add-feature-flags.md` (Mongoose replica-set requirement, Socket.io setup).
-
-**Exit criteria**: opt-in via constructor options; default off; tests cover both opt-in and opt-out paths.
-
-### Phase 4 — Example apps + docs + SDK regen
-
-Goal: example apps run, docs reflect the new shape, downstream consumers have a migration path.
-
-- `example-backend`: pass `liveUpdates: {socketIoServer: io}` to `FeatureFlagsApp` (the example-backend already constructs a Socket.io server for the existing `useSocketConnection` flow).
-- `example-frontend`: wrap `_layout.tsx` in `<OpenFeatureProvider domain="feature-flags">`. Call `useTerrenoFeatureFlags(terrenoApi, {socket})` once at the top of the layout after auth. Update `profile.tsx` to add the `useBooleanFlagDetails` debug row showing `reason` per flag.
-- Add a `types/openfeature.d.ts` file in `example-frontend` demonstrating the type-safe flag keys augmentation. Update SEED_FLAGS in `example-backend/src/scripts/seed-feature-flags.ts` to include `defaultVariant` on each flag, exercising the new field.
-- Regenerate SDK: `cd example-frontend && bun run sdk`.
-- Update `docs/reference/feature-flags.md` to describe the new endpoint shape, the `MongoFeatureFlagProvider` export, the `defaultVariant` field, and how to use OpenFeature hooks directly. Note `/evaluate` is deprecated.
-- Update `docs/how-to/add-feature-flags.md` to recommend OpenFeature hooks for new code, with `useFeatureFlags` shown as the BC path.
-- Add a new section "Migrating to OpenFeature" describing the breaking wire change for anyone calling `/evaluate` directly (no SDK update required if using `useFeatureFlags` — the BC wrapper handles it).
-- Update `docs/implementationPlans/feature-flags.md` with a note linking to this new IP at the top.
-
-**Exit criteria**: `bun run frontend:web` + `bun run backend:dev` runs end-to-end. Flags render with the same values as before. Admin edits propagate live to the open frontend. All workspace tests pass: `bun run lint && bun run compile && bun run test`.
-
----
-
-## Feature Flags & Migrations
-
-- No data migration: legacy `FeatureFlag` docs without `defaultVariant` get a computed value via Mongoose getter at read time.
-- The wire-protocol change is at the SDK boundary — consumers using `useFeatureFlags(api)` get the new behavior automatically because the hook handles both shapes via the BC wrapper. Direct `/evaluate` callers (none expected internally) hit the deprecated endpoint until they migrate.
-- No new feature flag is needed to gate this change since the package already gates itself.
-
----
-
-## Activity Log & User Updates
-
-None.
-
----
-
-## Risks & Mitigations
-
-| Risk | Mitigation |
-|---|---|
-| **User switching pours wrong-user data into globally-shared InMemoryProvider** | RTK Query cache key includes `userId`; on `userId` change the hook re-fetches AND calls `OpenFeature.setContext(domain, {targetingKey})` before swapping the provider. `isLoading` returns to `true` during the transition so consumers don't render stale values. Explicit test required. |
-| **`@openfeature/react-sdk` may not work in React Native** | Phase 2.1 includes a spike: import the package in a `bun test` using `@testing-library/react-native` and assert `useBooleanFlagValue` returns expected value. If it fails on RN, fall back to importing from `@openfeature/web-sdk` directly and writing a tiny React adapter in `@terreno/rtk`. **Blocking before Phase 2 proceeds.** |
-| **`OpenFeature.setProvider` is async; consumers can render with `defaultValue` before `PROVIDER_READY`** | `useTerrenoFeatureFlags` subscribes to `PROVIDER_READY` via `client.addHandler` and only flips `isLoading` to `false` once that event fires. Tested explicitly. |
-| **`OpenFeature` is a global singleton — two copies of `@openfeature/web-sdk` create two singletons** | Declare `@openfeature/web-sdk` and `@openfeature/react-sdk` as **peerDependencies** (not direct deps) in `rtk/package.json`. Consumers install once; bun dedupes automatically. Direct deps remain on `@openfeature/core` for types. |
-| **Mongoose change streams need a replica set; default test mongo is standalone** | The live-updates tests mock `FeatureFlag.watch()` to return a fake EventEmitter. We do NOT spin up a real replica set in tests. Production deployments must use a replica set — documented in `add-feature-flags.md` "Live updates" section as a prerequisite. Startup logs a warning if `watch()` throws. |
-| **Provider's `resolveStringEvaluation` could be called with a key whose stored type is `boolean`** | Provider returns `{value: defaultValue, reason: "ERROR", errorCode: "TYPE_MISMATCH"}`. Tested explicitly. |
-| **`defaultVariant` validation could reject legacy docs on edit** | Pre-save hook auto-populates `defaultVariant` for legacy docs before validation runs; validation only enforces shape constraints, not presence. Tested with both legacy-update and new-create paths. |
-| **Provider's per-flag `findOneOrNone` is N+1 for server-side OF consumers** | Acknowledged as a regression vs. `evaluateAllFlags` (one query). For our frontend bulk fetch this is fine because `/flagConfiguration` does ONE query and loops in-memory. Document that direct backend OF usage is not for hot paths; add LRU caching in a follow-up if needed. |
-| **`OpenFeature.setProvider` cleanup on unmount could break other consumers** | Do not clear on unmount of an individual instance. Use a module-level ref count; only clear when the count returns to zero. Documented in `useTerrenoFeatureFlags.ts`. |
-| **React StrictMode double-mount sets the provider twice** | Use a ref to track the in-flight `setProvider` promise; if a second mount fires while the first is in-flight, skip the second call. Tested with `<StrictMode>` wrapper. |
-| **Socket.io broadcast leaks flag keys to all connected clients** | Documented behavior. Payload contains only `{key}` (no user data). Acceptable since flag keys are not secrets — the same keys ship to every authenticated client via `/flagConfiguration` anyway. |
-| **Socket reconnects miss change events during disconnect** | After socket reconnect, hook automatically `refetch()`s once (already happens via RTK Query refetch-on-focus and via socket connection event). Document the gap is "at most one stale render" in practice. |
-| **Type-safe flag keys union can drift from runtime flag set** | Documented in `feature-flags.md` reference: the type union is a compile-time hint only; admin changes to flags may add/remove runtime keys without the TS types updating. Recommend syncing periodically. |
-
----
-
-## Not included / Future work
-
-- Server-side flag value caching keyed by `(flagKey, userId)` for very hot paths.
-- Anonymous evaluation (would require deriving a stable `targetingKey` from device id or similar).
-- Object/number flag types (currently return `FLAG_NOT_FOUND` from the provider; can be added by extending the schema and provider).
-- Native flagd or GrowthBook provider — out of scope; vendor-portability is unlocked by the OF abstraction.
-- Experiment-results tracking via `useTrack` and analytics integration.
-- Multi-tenant flag scopes (e.g., per-org overrides).
-- Flag scheduling (enable/disable at a future date) and audit log of who changed what when.