@beignet/provider-flags-openfeature 0.0.14

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @beignet/provider-flags-openfeature
+
+## 0.0.14
+
+### Patch Changes
+
+- 6828442: Add first-class feature flag primitives, an OpenFeature-backed flags provider,
+  and devtools support for flag evaluation, exposure, and tracking events.
+
+## 0.0.13
+
+### Patch Changes
+
+- Initial OpenFeature-backed feature flags provider.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taylor Bryant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @beignet/provider-flags-openfeature
+
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
+OpenFeature-backed `FlagsPort` provider for Beignet applications.
+
+The provider installs `ctx.ports.flags` using
+[`@openfeature/server-sdk`](https://openfeature.dev/) and keeps OpenFeature
+types out of Beignet core.
+
+## Install
+
+```bash
+bun add @beignet/provider-flags-openfeature @openfeature/server-sdk
+```
+
+Install and configure your chosen OpenFeature provider package separately.
+
+## Setup
+
+```typescript
+import { createNextServer } from "@beignet/next";
+import { createOpenFeatureFlagsProvider } from "@beignet/provider-flags-openfeature";
+import { appPorts } from "@/infra/app-ports";
+import { openFeatureProvider } from "@/infra/flags/openfeature";
+
+export const server = await createNextServer({
+  ports: appPorts,
+  providers: [
+    createOpenFeatureFlagsProvider({
+      provider: openFeatureProvider,
+      domain: "app",
+    }),
+  ],
+  context: appContextBlueprint,
+});
+```
+
+The provider contributes:
+
+- `ctx.ports.flags`, the standard Beignet `FlagsPort`
+- `ctx.ports.openFeature`, an escape hatch with the raw OpenFeature client/API
+
+## Direct port factory
+
+Use `createOpenFeatureFlags(...)` when your app already owns an OpenFeature
+client:
+
+```typescript
+import { createOpenFeatureFlags } from "@beignet/provider-flags-openfeature";
+
+const flags = createOpenFeatureFlags({ client });
+```
+
+## Failure behavior
+
+OpenFeature evaluation errors return the Beignet flag default with
+`reason: "error"` in `details(...)`. Programmer errors, such as malformed flag
+definitions, remain application errors.
+
+## Devtools
+
+When `@beignet/devtools` is installed before this provider, flag evaluations,
+provider errors, explicit exposures, and tracking events appear under the
+Feature flags watcher. Private attributes are redacted from instrumentation
+details.

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @beignet/provider-flags-openfeature
+ *
+ * OpenFeature-backed feature flags provider for Beignet.
+ */
+import type { FlagEvaluationContext, FlagEvaluationDetails, FlagEvaluationOptions, FlagExposureOptions, FlagsPort, FlagTrackOptions } from "@beignet/core/flags";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+import { type Client, OpenFeature, type Provider } from "@openfeature/server-sdk";
+/**
+ * Ports contributed by the OpenFeature flags provider.
+ */
+export interface OpenFeatureFlagsProviderPorts {
+    /**
+     * Beignet feature flag port backed by OpenFeature.
+     */
+    flags: FlagsPort;
+    /**
+     * Escape hatch for advanced OpenFeature usage.
+     */
+    openFeature: OpenFeatureEscapeHatch;
+}
+/**
+ * Escape hatch for apps that need the raw OpenFeature client/API.
+ */
+export interface OpenFeatureEscapeHatch {
+    client: Client;
+    api: typeof OpenFeature;
+}
+/**
+ * Options for the direct OpenFeature flags port factory.
+ */
+export interface CreateOpenFeatureFlagsOptions {
+    client: Client;
+    instrumentation?: ProviderInstrumentationTarget;
+}
+/**
+ * Options for the OpenFeature provider package.
+ */
+export interface CreateOpenFeatureFlagsProviderOptions {
+    /**
+     * Existing OpenFeature client. When supplied, setup does not register a
+     * provider with the singleton OpenFeature API.
+     */
+    client?: Client;
+    /**
+     * OpenFeature provider to install during Beignet server setup.
+     */
+    provider?: Provider;
+    /**
+     * Optional OpenFeature domain for provider and client binding.
+     */
+    domain?: string;
+    /**
+     * Optional client version used when creating a domain-scoped client.
+     */
+    version?: string;
+    /**
+     * Await provider initialization during setup.
+     *
+     * @default true
+     */
+    waitForReady?: boolean;
+    /**
+     * Clear OpenFeature providers when the Beignet server stops.
+     *
+     * @default false
+     */
+    clearOnStop?: boolean;
+}
+/**
+ * Create a Beignet FlagsPort backed by an OpenFeature client.
+ */
+export declare function createOpenFeatureFlags(options: CreateOpenFeatureFlagsOptions): FlagsPort;
+/**
+ * Create a Beignet provider that contributes `ports.flags`.
+ */
+export declare function createOpenFeatureFlagsProvider(options?: CreateOpenFeatureFlagsProviderOptions): import("@beignet/core/providers").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
+    flags: FlagsPort;
+    openFeature: {
+        client: Client;
+        api: import("@openfeature/server-sdk").OpenFeatureAPI;
+    };
+}, unknown, void>;
+/**
+ * Ready-to-register OpenFeature flags provider using the default OpenFeature
+ * singleton client.
+ */
+export declare const openFeatureFlagsProvider: import("@beignet/core/providers").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
+    flags: FlagsPort;
+    openFeature: {
+        client: Client;
+        api: import("@openfeature/server-sdk").OpenFeatureAPI;
+    };
+}, unknown, void>;
+export type { FlagEvaluationContext, FlagEvaluationDetails, FlagEvaluationOptions, FlagExposureOptions, FlagsPort, FlagTrackOptions, };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,SAAS,EACT,gBAAgB,EAEjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,MAAM,EAIX,WAAW,EACX,KAAK,QAAQ,EAEd,MAAM,yBAAyB,CAAC;AAEjC;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,WAAW,EAAE,sBAAsB,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,OAAO,WAAW,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,qCAAqC;IACpD;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAqGD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,SAAS,CA4HX;AA8DD;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,qCAA0C;;;;;;kBAgCpD;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;;;;;iBAAmC,CAAC;AAEzE,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,SAAS,EACT,gBAAgB,GACjB,CAAC"}

package/dist/index.js

@@ -0,0 +1,265 @@
+/**
+ * @beignet/provider-flags-openfeature
+ *
+ * OpenFeature-backed feature flags provider for Beignet.
+ */
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import { OpenFeature, } from "@openfeature/server-sdk";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function toOpenFeatureContext(context) {
+    if (!context)
+        return undefined;
+    return omitUndefined({
+        ...context.attributes,
+        targetingKey: context.targetingKey,
+        subjectType: context.subject?.type,
+        subjectId: context.subject?.id,
+        tenantId: context.tenant?.id,
+        tenantSlug: context.tenant?.slug,
+        requestId: context.requestId,
+        traceId: context.traceId,
+        spanId: context.spanId,
+        parentSpanId: context.parentSpanId,
+        traceparent: context.traceparent,
+    });
+}
+function sanitizedContext(context) {
+    if (!context)
+        return undefined;
+    const privateKeys = new Set(context.privateAttributes ?? []);
+    const attributes = Object.fromEntries(Object.entries(context.attributes ?? {}).map(([key, value]) => [
+        key,
+        privateKeys.has(key) ? "[redacted]" : value,
+    ]));
+    return {
+        ...context,
+        attributes,
+    };
+}
+function normalizeReason(reason) {
+    return (reason ?? "unknown").toLowerCase();
+}
+function omitUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function normalizeDetails(flag, defaultValue, details) {
+    const error = details.errorCode || details.errorMessage
+        ? {
+            code: details.errorCode,
+            message: details.errorMessage ?? details.errorCode ?? "Flag error",
+        }
+        : undefined;
+    const reason = normalizeReason(details.reason);
+    return {
+        key: flag.key,
+        kind: flag.kind,
+        value: details.value,
+        defaultValue,
+        reason,
+        defaulted: reason === "default" || reason === "error",
+        variant: details.variant,
+        metadata: details.flagMetadata,
+        error,
+    };
+}
+function defaultDetails(flag, defaultValue, error) {
+    return {
+        key: flag.key,
+        kind: flag.kind,
+        value: defaultValue,
+        defaultValue,
+        reason: "error",
+        defaulted: true,
+        error: { message: errorMessage(error) },
+    };
+}
+/**
+ * Create a Beignet FlagsPort backed by an OpenFeature client.
+ */
+export function createOpenFeatureFlags(options) {
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "flags-openfeature",
+        watcher: "flags",
+    });
+    const client = options.client;
+    const flags = {
+        async evaluate(flag, evaluationOptions) {
+            const details = await flags.details(flag, evaluationOptions);
+            return details.value;
+        },
+        async details(flag, evaluationOptions) {
+            const startedAt = Date.now();
+            const defaultValue = evaluationOptions?.defaultValue ?? flag.defaultValue;
+            const context = toOpenFeatureContext(evaluationOptions?.context);
+            try {
+                const details = await evaluateOpenFeatureDetails(client, flag, defaultValue, context);
+                const normalized = normalizeDetails(flag, defaultValue, details);
+                instrumentation.custom({
+                    name: "flags.evaluate",
+                    label: "Flag evaluated",
+                    summary: `${flag.key} -> ${String(normalized.value)}`,
+                    requestId: evaluationOptions?.context?.requestId,
+                    traceId: evaluationOptions?.context?.traceId,
+                    details: {
+                        flagKey: flag.key,
+                        kind: flag.kind,
+                        reason: normalized.reason,
+                        defaulted: normalized.defaulted,
+                        variant: normalized.variant,
+                        durationMs: Date.now() - startedAt,
+                        context: sanitizedContext(evaluationOptions?.context),
+                    },
+                });
+                if (evaluationOptions?.expose) {
+                    await flags.recordExposure(flag, {
+                        context: evaluationOptions.context,
+                        value: normalized.value,
+                        variant: normalized.variant,
+                        metadata: normalized.metadata,
+                    });
+                }
+                return normalized;
+            }
+            catch (error) {
+                const normalized = defaultDetails(flag, defaultValue, error);
+                instrumentation.custom({
+                    name: "flags.evaluate.error",
+                    label: "Flag evaluation failed",
+                    summary: `${flag.key} -> default`,
+                    requestId: evaluationOptions?.context?.requestId,
+                    traceId: evaluationOptions?.context?.traceId,
+                    details: {
+                        flagKey: flag.key,
+                        kind: flag.kind,
+                        error: normalized.error,
+                        durationMs: Date.now() - startedAt,
+                        context: sanitizedContext(evaluationOptions?.context),
+                    },
+                });
+                return normalized;
+            }
+        },
+        async recordExposure(flag, exposureOptions) {
+            const context = toOpenFeatureContext(exposureOptions?.context);
+            client.track("flag.exposure", context, omitUndefined({
+                ...exposureOptions?.metadata,
+                flagKey: flag.key,
+                variant: exposureOptions?.variant,
+                evaluatedValue: exposureOptions?.value,
+            }));
+            instrumentation.custom({
+                name: "flags.exposure",
+                label: "Flag exposure",
+                summary: flag.key,
+                requestId: exposureOptions?.context?.requestId,
+                traceId: exposureOptions?.context?.traceId,
+                details: {
+                    flagKey: flag.key,
+                    variant: exposureOptions?.variant,
+                    context: sanitizedContext(exposureOptions?.context),
+                },
+            });
+        },
+        async track(event, trackOptions) {
+            client.track(event, toOpenFeatureContext(trackOptions?.context), omitUndefined({
+                ...trackOptions?.metadata,
+                value: trackOptions?.value,
+            }));
+            instrumentation.custom({
+                name: "flags.track",
+                label: "Flag tracking event",
+                summary: event,
+                requestId: trackOptions?.context?.requestId,
+                traceId: trackOptions?.context?.traceId,
+                details: {
+                    event,
+                    context: sanitizedContext(trackOptions?.context),
+                },
+            });
+        },
+    };
+    return flags;
+}
+async function evaluateOpenFeatureDetails(client, flag, defaultValue, context) {
+    switch (flag.kind) {
+        case "boolean":
+            return client.getBooleanDetails(flag.key, defaultValue, context);
+        case "string":
+            return client.getStringDetails(flag.key, defaultValue, context);
+        case "number":
+            return client.getNumberDetails(flag.key, defaultValue, context);
+        case "object":
+            return client.getObjectDetails(flag.key, defaultValue, context);
+    }
+    throw new Error(`Unsupported flag kind: ${String(flag.kind)}`);
+}
+function getClient(options) {
+    if (options.client)
+        return options.client;
+    if (options.domain && options.version) {
+        return OpenFeature.getClient(options.domain, options.version);
+    }
+    if (options.domain) {
+        return OpenFeature.getClient(options.domain);
+    }
+    return OpenFeature.getClient();
+}
+async function installProvider(options) {
+    if (!options.provider)
+        return;
+    if (options.waitForReady ?? true) {
+        if (options.domain) {
+            await OpenFeature.setProviderAndWait(options.domain, options.provider);
+            return;
+        }
+        await OpenFeature.setProviderAndWait(options.provider);
+        return;
+    }
+    if (options.domain) {
+        OpenFeature.setProvider(options.domain, options.provider);
+        return;
+    }
+    OpenFeature.setProvider(options.provider);
+}
+/**
+ * Create a Beignet provider that contributes `ports.flags`.
+ */
+export function createOpenFeatureFlagsProvider(options = {}) {
+    return createProvider({
+        name: "flags-openfeature",
+        metadata: {
+            packageName: "@beignet/provider-flags-openfeature",
+            ports: ["flags", "openFeature"],
+            watchers: ["flags"],
+        },
+        async setup({ ports }) {
+            await installProvider(options);
+            const client = getClient(options);
+            return {
+                ports: {
+                    flags: createOpenFeatureFlags({
+                        client,
+                        instrumentation: ports,
+                    }),
+                    openFeature: {
+                        client,
+                        api: OpenFeature,
+                    },
+                },
+                async stop() {
+                    if (options.clearOnStop) {
+                        await OpenFeature.clearProviders();
+                    }
+                },
+            };
+        },
+    });
+}
+/**
+ * Ready-to-register OpenFeature flags provider using the default OpenFeature
+ * singleton client.
+ */
+export const openFeatureFlagsProvider = createOpenFeatureFlagsProvider();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@beignet/provider-flags-openfeature",
+  "version": "0.0.14",
+  "type": "module",
+  "description": "OpenFeature feature flag provider for Beignet",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "openfeature",
+    "feature-flags",
+    "provider",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-flags-openfeature"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@beignet/core": ">=0.0.3 <1.0.0",
+    "@openfeature/server-sdk": "^1.22.0"
+  },
+  "devDependencies": {
+    "@beignet/core": "*",
+    "@beignet/devtools": "*",
+    "@openfeature/server-sdk": "^1.22.0",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "beignet": {
+    "provider": {
+      "displayName": "OpenFeature flags provider",
+      "ports": [
+        "flags",
+        "openFeature"
+      ],
+      "appPorts": [
+        {
+          "name": "flags",
+          "type": "FlagsPort"
+        }
+      ],
+      "env": [],
+      "requiredEnv": [],
+      "watchers": [
+        "flags"
+      ],
+      "registration": {
+        "required": true,
+        "tokens": [
+          "openFeatureFlagsProvider",
+          "createOpenFeatureFlagsProvider"
+        ]
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,438 @@
+/**
+ * @beignet/provider-flags-openfeature
+ *
+ * OpenFeature-backed feature flags provider for Beignet.
+ */
+
+import type {
+  FlagDef,
+  FlagEvaluationContext,
+  FlagEvaluationDetails,
+  FlagEvaluationOptions,
+  FlagExposureOptions,
+  FlagsPort,
+  FlagTrackOptions,
+  FlagValue,
+} from "@beignet/core/flags";
+import {
+  createProvider,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "@beignet/core/providers";
+import {
+  type Client,
+  type EvaluationContext,
+  type EvaluationDetails,
+  type JsonValue,
+  OpenFeature,
+  type Provider,
+  type TrackingEventDetails,
+} from "@openfeature/server-sdk";
+
+/**
+ * Ports contributed by the OpenFeature flags provider.
+ */
+export interface OpenFeatureFlagsProviderPorts {
+  /**
+   * Beignet feature flag port backed by OpenFeature.
+   */
+  flags: FlagsPort;
+  /**
+   * Escape hatch for advanced OpenFeature usage.
+   */
+  openFeature: OpenFeatureEscapeHatch;
+}
+
+/**
+ * Escape hatch for apps that need the raw OpenFeature client/API.
+ */
+export interface OpenFeatureEscapeHatch {
+  client: Client;
+  api: typeof OpenFeature;
+}
+
+/**
+ * Options for the direct OpenFeature flags port factory.
+ */
+export interface CreateOpenFeatureFlagsOptions {
+  client: Client;
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
+/**
+ * Options for the OpenFeature provider package.
+ */
+export interface CreateOpenFeatureFlagsProviderOptions {
+  /**
+   * Existing OpenFeature client. When supplied, setup does not register a
+   * provider with the singleton OpenFeature API.
+   */
+  client?: Client;
+  /**
+   * OpenFeature provider to install during Beignet server setup.
+   */
+  provider?: Provider;
+  /**
+   * Optional OpenFeature domain for provider and client binding.
+   */
+  domain?: string;
+  /**
+   * Optional client version used when creating a domain-scoped client.
+   */
+  version?: string;
+  /**
+   * Await provider initialization during setup.
+   *
+   * @default true
+   */
+  waitForReady?: boolean;
+  /**
+   * Clear OpenFeature providers when the Beignet server stops.
+   *
+   * @default false
+   */
+  clearOnStop?: boolean;
+}
+
+type OpenFeatureDetails = EvaluationDetails<
+  boolean | string | number | JsonValue
+>;
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function toOpenFeatureContext(
+  context: FlagEvaluationContext | undefined,
+): EvaluationContext | undefined {
+  if (!context) return undefined;
+
+  return omitUndefined({
+    ...context.attributes,
+    targetingKey: context.targetingKey,
+    subjectType: context.subject?.type,
+    subjectId: context.subject?.id,
+    tenantId: context.tenant?.id,
+    tenantSlug: context.tenant?.slug,
+    requestId: context.requestId,
+    traceId: context.traceId,
+    spanId: context.spanId,
+    parentSpanId: context.parentSpanId,
+    traceparent: context.traceparent,
+  }) as EvaluationContext;
+}
+
+function sanitizedContext(context: FlagEvaluationContext | undefined) {
+  if (!context) return undefined;
+  const privateKeys = new Set(context.privateAttributes ?? []);
+  const attributes = Object.fromEntries(
+    Object.entries(context.attributes ?? {}).map(([key, value]) => [
+      key,
+      privateKeys.has(key) ? "[redacted]" : value,
+    ]),
+  );
+
+  return {
+    ...context,
+    attributes,
+  };
+}
+
+function normalizeReason(reason: string | undefined) {
+  return (reason ?? "unknown").toLowerCase();
+}
+
+function omitUndefined(
+  value: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined),
+  );
+}
+
+function normalizeDetails<TValue extends FlagValue>(
+  flag: FlagDef<TValue>,
+  defaultValue: TValue,
+  details: OpenFeatureDetails,
+): FlagEvaluationDetails<TValue> {
+  const error =
+    details.errorCode || details.errorMessage
+      ? {
+          code: details.errorCode,
+          message: details.errorMessage ?? details.errorCode ?? "Flag error",
+        }
+      : undefined;
+  const reason = normalizeReason(details.reason);
+
+  return {
+    key: flag.key,
+    kind: flag.kind,
+    value: details.value as TValue,
+    defaultValue,
+    reason,
+    defaulted: reason === "default" || reason === "error",
+    variant: details.variant,
+    metadata: details.flagMetadata,
+    error,
+  };
+}
+
+function defaultDetails<TValue extends FlagValue>(
+  flag: FlagDef<TValue>,
+  defaultValue: TValue,
+  error: unknown,
+): FlagEvaluationDetails<TValue> {
+  return {
+    key: flag.key,
+    kind: flag.kind,
+    value: defaultValue,
+    defaultValue,
+    reason: "error",
+    defaulted: true,
+    error: { message: errorMessage(error) },
+  };
+}
+
+/**
+ * Create a Beignet FlagsPort backed by an OpenFeature client.
+ */
+export function createOpenFeatureFlags(
+  options: CreateOpenFeatureFlagsOptions,
+): FlagsPort {
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "flags-openfeature",
+      watcher: "flags",
+    },
+  );
+  const client = options.client;
+
+  const flags: FlagsPort = {
+    async evaluate(flag, evaluationOptions) {
+      const details = await flags.details(flag, evaluationOptions);
+      return details.value;
+    },
+    async details(flag, evaluationOptions) {
+      const startedAt = Date.now();
+      const defaultValue = evaluationOptions?.defaultValue ?? flag.defaultValue;
+      const context = toOpenFeatureContext(evaluationOptions?.context);
+
+      try {
+        const details = await evaluateOpenFeatureDetails(
+          client,
+          flag,
+          defaultValue,
+          context,
+        );
+        const normalized = normalizeDetails(flag, defaultValue, details);
+
+        instrumentation.custom({
+          name: "flags.evaluate",
+          label: "Flag evaluated",
+          summary: `${flag.key} -> ${String(normalized.value)}`,
+          requestId: evaluationOptions?.context?.requestId,
+          traceId: evaluationOptions?.context?.traceId,
+          details: {
+            flagKey: flag.key,
+            kind: flag.kind,
+            reason: normalized.reason,
+            defaulted: normalized.defaulted,
+            variant: normalized.variant,
+            durationMs: Date.now() - startedAt,
+            context: sanitizedContext(evaluationOptions?.context),
+          },
+        });
+
+        if (evaluationOptions?.expose) {
+          await flags.recordExposure(flag, {
+            context: evaluationOptions.context,
+            value: normalized.value,
+            variant: normalized.variant,
+            metadata: normalized.metadata,
+          });
+        }
+
+        return normalized;
+      } catch (error) {
+        const normalized = defaultDetails(flag, defaultValue, error);
+        instrumentation.custom({
+          name: "flags.evaluate.error",
+          label: "Flag evaluation failed",
+          summary: `${flag.key} -> default`,
+          requestId: evaluationOptions?.context?.requestId,
+          traceId: evaluationOptions?.context?.traceId,
+          details: {
+            flagKey: flag.key,
+            kind: flag.kind,
+            error: normalized.error,
+            durationMs: Date.now() - startedAt,
+            context: sanitizedContext(evaluationOptions?.context),
+          },
+        });
+        return normalized;
+      }
+    },
+    async recordExposure(flag, exposureOptions) {
+      const context = toOpenFeatureContext(exposureOptions?.context);
+      client.track(
+        "flag.exposure",
+        context,
+        omitUndefined({
+          ...exposureOptions?.metadata,
+          flagKey: flag.key,
+          variant: exposureOptions?.variant,
+          evaluatedValue: exposureOptions?.value as JsonValue | undefined,
+        }) as TrackingEventDetails,
+      );
+      instrumentation.custom({
+        name: "flags.exposure",
+        label: "Flag exposure",
+        summary: flag.key,
+        requestId: exposureOptions?.context?.requestId,
+        traceId: exposureOptions?.context?.traceId,
+        details: {
+          flagKey: flag.key,
+          variant: exposureOptions?.variant,
+          context: sanitizedContext(exposureOptions?.context),
+        },
+      });
+    },
+    async track(event, trackOptions) {
+      client.track(
+        event,
+        toOpenFeatureContext(trackOptions?.context),
+        omitUndefined({
+          ...trackOptions?.metadata,
+          value: trackOptions?.value,
+        }) as TrackingEventDetails,
+      );
+      instrumentation.custom({
+        name: "flags.track",
+        label: "Flag tracking event",
+        summary: event,
+        requestId: trackOptions?.context?.requestId,
+        traceId: trackOptions?.context?.traceId,
+        details: {
+          event,
+          context: sanitizedContext(trackOptions?.context),
+        },
+      });
+    },
+  };
+
+  return flags;
+}
+
+async function evaluateOpenFeatureDetails<TValue extends FlagValue>(
+  client: Client,
+  flag: FlagDef<TValue>,
+  defaultValue: TValue,
+  context: EvaluationContext | undefined,
+): Promise<OpenFeatureDetails> {
+  switch (flag.kind) {
+    case "boolean":
+      return client.getBooleanDetails(
+        flag.key,
+        defaultValue as boolean,
+        context,
+      );
+    case "string":
+      return client.getStringDetails(flag.key, defaultValue as string, context);
+    case "number":
+      return client.getNumberDetails(flag.key, defaultValue as number, context);
+    case "object":
+      return client.getObjectDetails(
+        flag.key,
+        defaultValue as JsonValue,
+        context,
+      );
+  }
+
+  throw new Error(`Unsupported flag kind: ${String(flag.kind)}`);
+}
+
+function getClient(options: CreateOpenFeatureFlagsProviderOptions): Client {
+  if (options.client) return options.client;
+  if (options.domain && options.version) {
+    return OpenFeature.getClient(options.domain, options.version);
+  }
+  if (options.domain) {
+    return OpenFeature.getClient(options.domain);
+  }
+  return OpenFeature.getClient();
+}
+
+async function installProvider(
+  options: CreateOpenFeatureFlagsProviderOptions,
+): Promise<void> {
+  if (!options.provider) return;
+
+  if (options.waitForReady ?? true) {
+    if (options.domain) {
+      await OpenFeature.setProviderAndWait(options.domain, options.provider);
+      return;
+    }
+    await OpenFeature.setProviderAndWait(options.provider);
+    return;
+  }
+
+  if (options.domain) {
+    OpenFeature.setProvider(options.domain, options.provider);
+    return;
+  }
+  OpenFeature.setProvider(options.provider);
+}
+
+/**
+ * Create a Beignet provider that contributes `ports.flags`.
+ */
+export function createOpenFeatureFlagsProvider(
+  options: CreateOpenFeatureFlagsProviderOptions = {},
+) {
+  return createProvider({
+    name: "flags-openfeature",
+    metadata: {
+      packageName: "@beignet/provider-flags-openfeature",
+      ports: ["flags", "openFeature"],
+      watchers: ["flags"],
+    },
+    async setup({ ports }) {
+      await installProvider(options);
+      const client = getClient(options);
+
+      return {
+        ports: {
+          flags: createOpenFeatureFlags({
+            client,
+            instrumentation: ports,
+          }),
+          openFeature: {
+            client,
+            api: OpenFeature,
+          },
+        } satisfies OpenFeatureFlagsProviderPorts,
+        async stop() {
+          if (options.clearOnStop) {
+            await OpenFeature.clearProviders();
+          }
+        },
+      };
+    },
+  });
+}
+
+/**
+ * Ready-to-register OpenFeature flags provider using the default OpenFeature
+ * singleton client.
+ */
+export const openFeatureFlagsProvider = createOpenFeatureFlagsProvider();
+
+export type {
+  FlagEvaluationContext,
+  FlagEvaluationDetails,
+  FlagEvaluationOptions,
+  FlagExposureOptions,
+  FlagsPort,
+  FlagTrackOptions,
+};