feat: create feature-flag configuration for staged rollout and rollback

[OAKVISUALZ]

Description

This PR introduces a central, environment-aware feature flag system to enable safer release strategies, monotonic deterministic staged rollouts, and fast emergency rollbacks in production.

Key Changes

1. Central Feature Flag Management Engine (src/config/featureFlags.ts):
   • Implemented FeatureFlagManager and global singleton featureFlagManager.
   • Built standard catalog DEFAULT_FEATURE_FLAGS (agent_autonomous_rebalance, smart_dca_engine, enhanced_stellar_routing, ai_assistant_tool_calling, circuit_breaker_v2, fast_fiat_onramp, emergency_maintenance_mode).
   • Cryptographic SHA-256 entity hashing (hashEntityToPercentage) providing sticky, monotonic distribution for progressive canary rollouts (0% -> 10% -> 25% -> 50% -> 100%).
   • Multi-tier fail-closed resolution pipeline: Global Maintenance -> Flag Kill Switch -> Rollback -> Blocklist -> Allowlist -> Runtime Override -> Env Var Override -> Environment Defaults -> Fail-Closed Fallback.
   • Fast emergency rollback mechanism with audit history and Redis distributed synchronization.
2. Observability & Logging:
   • Winston structured evaluation decision logging (flag, decision, reason, environment, entityId, rolloutPercentage).
   • Prometheus metrics for evaluations (feature_flag_evaluations_total), rollbacks (feature_flag_rollbacks_total), and rollout percentage gauge (feature_flag_rollout_percentage).
3. Middleware & Route Protection (src/middleware/featureFlags.ts):
   • requireFeatureFlag: Route guard returning 503 FEATURE_DISABLED when feature is off or user is excluded by staged rollout.
   • featureFlagMiddleware: Injects req.isFeatureEnabled and req.evaluateFeatureFlag helpers onto Express requests.
   • emergencyMaintenanceGuard: Blocks state-mutating requests (POST, PUT, DELETE, PATCH) during emergency maintenance while preserving health probes and admin rollback routes.
4. Operational Admin Tooling (src/routes/admin.ts):
   • Added REST endpoints guarded by RBAC scopes (flags:read and flags:write):
     • GET /api/v1/admin/feature-flags
     • GET /api/v1/admin/feature-flags/history
     • GET /api/v1/admin/feature-flags/:key
     • PUT /api/v1/admin/feature-flags/:key
     • POST /api/v1/admin/feature-flags/:key/staged-rollout
     • POST /api/v1/admin/feature-flags/:key/rollback
     • POST /api/v1/admin/feature-flags/:key/reset
     • POST /api/v1/admin/feature-flags/emergency-disable-all
5. Documentation & Emergency Runbook:
   • Authored docs/FEATURE_FLAGS.md detailing architecture, deterministic hashing, decision logging, and the 4-tier emergency rollback runbook.
   • Updated docs/RUNBOOK.md and indexed in docs/DOCUMENTATION_INDEX.md.
6. Comprehensive Unit Tests:
   • Added 45 comprehensive unit tests across tests/unit/config/featureFlags.test.ts, tests/unit/middleware/featureFlags.test.ts, and tests/unit/routes/admin-feature-flags.test.ts.

Related Issues

Closes #494

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update

Checklist

• My code follows the existing code style of this project
• I have run npm run lint with no errors
• I have run npm run typecheck with no errors
• I have added tests that prove my fix/feature works
• All new and existing tests pass (npm test)
• I have updated documentation accordingly

[drips-wave]

@OAKVISUALZ Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[robertocarlous]

fix conflicts