58 lines
2.8 KiB
Markdown
58 lines
2.8 KiB
Markdown
# 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`
|