@terreno/mcp 0.23.0 → 0.23.1

package/dist/docs/versioned/0.23.0/implementationPlans/feature-flags-openfeature.md

@@ -0,0 +1,545 @@
+# 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.