Initial Commit

openspec/archive/2026-04-19-enterprise-feature-flags/proposal.md

@@ -0,0 +1,57 @@
+# 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`