OpenSpec Change: enterprise-feature-flags

Change ID: enterprise-feature-flags
Package: @suaveplan/feature-flags
Category: universal
Target path: universal/config/feature-flags
Status: PROPOSED
Date: 2026-04-19
Reference spec: /mnt/s/web/suaveplan/enterprise/feature-flags.md

Summary

Greenfield build of @suaveplan/feature-flags — provider-agnostic flag evaluation with a FlagRegistry + FlagManager façade, an Evaluator that runs strategy chains, provider adapters (memory, JSON), and composable targeting strategies (PercentageStrategy, UserTargetStrategy, AttributeStrategy, ScheduleStrategy, CompositeStrategy). Typed FlagValue with deterministic bucketing via hashToPercentage.

Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

Dependencies

Workspace: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/logger
External (via catalog): zod → catalog:forms; @opentelemetry/api → catalog:observability; tslib → catalog:build
Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata → catalog:testing

Preserved public surface (from main)

Core

FlagRegistry, FlagRegistryOptions
FlagManager, FlagManagerOptions
Evaluator, EvaluatorOptions

Providers

BaseFlagProvider, BaseFlagProviderOptions
MemoryProvider
JsonProvider, JsonProviderOptions, JsonFlagConfig, parseJsonFlags

Strategies

PercentageStrategy, PercentageStrategyOptions
UserTargetStrategy, UserTargetStrategyOptions
AttributeStrategy, AttributeStrategyOptions, AttributeOperator, AttributeRule, compareValues, getNestedValue
ScheduleStrategy, ScheduleStrategyOptions
CompositeStrategy, CompositeStrategyOptions, CompositeOperator

Types

FlagDefinition, FlagDefinitionMap, FlagValue, FlagProvider, FlagChangeEvent, FlagChangeListener, FlagEvaluationResult, EvaluationContext, EvaluationReason, Strategy, StrategyResult

Utilities

hashToPercentage, combineKeys

New genesis additions

Structured errors with codes FEATURE_FLAGS.UNKNOWN_FLAG, FEATURE_FLAGS.PROVIDER_ERROR, FEATURE_FLAGS.STRATEGY_ERROR, FEATURE_FLAGS.INVALID_DEFINITION.
Zod schemas for every FlagDefinition, EvaluationContext, JsonFlagConfig.
OTel histogram ff.evaluate.duration_ms; counter ff.evaluate.total{flag, result}.
Property tests: hashToPercentage uniform over random keys within statistical tolerance; PercentageStrategy bucketing is monotonic in rollout percentage.
mitata benchmarks for Evaluator.evaluate across strategy depths.

Impact

Adds one new package: universal/config/feature-flags
Adds one new spec capability: feature-flags

2.8 KiB Raw Blame History