# 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`