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

config/dependency-audit-exceptions.json

@@ -1,4 +1,53 @@
 {
   "schemaVersion": 1,
-  "exceptions": []
+  "exceptions": [
+    {
+      "advisory": "@grpc/grpc-js",
+      "owner": "@BernardOnuh",
+      "reason": "Pending patch update in dependabot PR #582; internal gRPC exposure only",
+      "expiresOn": "2026-11-30"
+    },
+    {
+      "advisory": "@opentelemetry/auto-instrumentations-node",
+      "owner": "@BernardOnuh",
+      "reason": "Transitive dependency on OpenTelemetry instrumentations; upgrade planned in P3 roadmap",
+      "expiresOn": "2026-11-30"
+    },
+    {
+      "advisory": "GHSA-qqmp-wf37-98f9",
+      "owner": "@BernardOnuh",
+      "reason": "OpenTelemetry database username span attribute exposure; tracked in P3 upgrade plan",
+      "expiresOn": "2026-11-30"
+    },
+    {
+      "advisory": "brace-expansion",
+      "owner": "@BernardOnuh",
+      "reason": "Transitive dependency via glob tooling; pending upstream release",
+      "expiresOn": "2026-11-30"
+    },
+    {
+      "advisory": "ip-address",
+      "owner": "@BernardOnuh",
+      "reason": "Transitive dependency; pending upstream patch",
+      "expiresOn": "2026-11-30"
+    },
+    {
+      "advisory": "minimatch",
+      "owner": "@BernardOnuh",
+      "reason": "Transitive dependency via gaxios; pending patch",
+      "expiresOn": "2026-11-30"
+    },
+    {
+      "advisory": "proxy-addr",
+      "owner": "@BernardOnuh",
+      "reason": "proxy-addr IPv4-mapped IPv6 trust subnet issue; pending express upgrade",
+      "expiresOn": "2026-11-30"
+    },
+    {
+      "advisory": "smol-toml",
+      "owner": "@BernardOnuh",
+      "reason": "smol-toml quadratic parse issue; non-user-facing config parser",
+      "expiresOn": "2026-11-30"
+    }
+  ]
 }

docs/API_KEYS.md

@@ -70,7 +70,8 @@ New keys are **read-only by default**. Write scopes must be explicitly requested
 | `dlq:read` | read | enforced | — | Inspect the dead-letter queue. | — | `GET /api/v1/admin/dlq/inspect`, `GET /api/v1/admin/notifications/dlq` |
 | `erasure:read` | read | declared-only | — | Preview what an erasure would delete. | No route requires this scope today — the erasure preview route is gated by the generic read scope. Declared so a key can be provisioned ahead of a route that needs it. | — |
 | `fiat:read` | read | enforced | — | Read fiat providers and their health. | — | `GET /api/v1/admin/fiat/providers` |
-| `keys:read` | read | enforced | — | Read admin API keys and wallet rotation status. | — | `GET /api/v1/admin/keys`, `GET /api/v1/admin/keys/scopes`, `GET /api/v1/admin/wallets/rotation-status` |
+| `flags:read` | read | enforced | — | Read feature flags and rollout state. | — | `GET /api/v1/admin/feature-flags`, `GET /api/v1/admin/feature-flags/:key`, `GET /api/v1/admin/feature-flags/history` |
+| `keys:read` | read | enforced | — | Read admin API keys and wallet rotation status. | — | `GET /api/v1/admin/keys`, `GET /api/v1/admin/wallets/rotation-status` |
 | `messages:read` | read | enforced | — | Read message delivery state. | — | `GET /api/v1/admin/messages`, `GET /api/v1/admin/messages/:id`, `GET /api/v1/admin/messages/stats` |
 | `metrics:read` | read | enforced | — | Read operational metrics and dashboards. | — | `GET /api/v1/admin/jobs/dashboard`, `GET /api/v1/admin/stellar/metrics` |
 | `outbox:read` | read | enforced | — | Read the durable outbox. | — | `GET /api/v1/admin/outbox`, `GET /api/v1/admin/outbox/:id`, `GET /api/v1/admin/outbox/stats` |
@@ -91,13 +92,14 @@ New keys are **read-only by default**. Write scopes must be explicitly requested
 | `wallet` | money | declared-only | — | Custodial wallet operations. | No route requires this scope today — the wallet rotation-status route is gated by keys:read. Declared so a key can be provisioned ahead of a route that needs it. | — |
 | `erasure:write` | destructive | enforced | — | Create, approve, reject and execute erasure requests. | Execution requires super — approval and execution are deliberately separated so one operator cannot both authorise and carry out a deletion. | `POST /api/v1/admin/erasure` |
 | `keys:write` | destructive | enforced | — | Create, rotate and revoke admin API keys. | Minting an admin key is a takeover vector — every use is written to the admin audit log. | `DELETE /api/v1/admin/keys/:id`, `POST /api/v1/admin/keys`, `POST /api/v1/admin/keys/:id/rotate` |
-| `super` | destructive | enforced | `support:read`, `support:write`, `read`, `write`, `wallet`, `agent`, `agent:read`, `agent:write`, `sessions:read`, `sessions:write`, `reserves:read`, `metrics:read`, `dlq:read`, `dlq:write`, `backfill:write`, `keys:read`, `keys:write`, `fiat:read`, `fiat:write`, `outbox:read`, `outbox:write`, `approvals:write`, `referrals:read`, `referrals:write`, `erasure:write`, `erasure:read`, `messages:read`, `messages:write`, `treasury:read`, `treasury:write`, `risk-metadata:read`, `risk-metadata:write`, `admin:impersonate`, `super` | Every admin scope, including erasure execution. | Held by as few keys as possible: it is a superset of every destructive scope in this catalogue. | `GET /api/v1/admin/audit/prove`, `GET /api/v1/admin/audit/verify`, `POST /api/v1/admin/erasure/requests/:id/approve`, `POST /api/v1/admin/erasure/requests/:id/execute`, `POST /api/v1/admin/erasure/requests/:id/reject` |
+| `super` | destructive | enforced | `support:read`, `support:write`, `read`, `write`, `wallet`, `agent`, `agent:read`, `agent:write`, `sessions:read`, `sessions:write`, `reserves:read`, `metrics:read`, `dlq:read`, `dlq:write`, `backfill:write`, `keys:read`, `keys:write`, `fiat:read`, `fiat:write`, `outbox:read`, `outbox:write`, `approvals:write`, `referrals:read`, `referrals:write`, `erasure:write`, `erasure:read`, `flags:read`, `flags:write`, `messages:read`, `messages:write`, `treasury:read`, `treasury:write`, `risk-metadata:read`, `risk-metadata:write`, `admin:impersonate`, `super` | Every admin scope, including erasure execution. | Held by as few keys as possible: it is a superset of every destructive scope in this catalogue. | `GET /api/v1/admin/audit/prove`, `GET /api/v1/admin/audit/verify`, `POST /api/v1/admin/erasure/requests/:id/approve`, `POST /api/v1/admin/erasure/requests/:id/execute`, `POST /api/v1/admin/erasure/requests/:id/reject` |
 | `admin:impersonate` | operational | declared-only | — | View the API as a user, read-only. | No route requires this scope today — the impersonation controller exists but is not yet exposed through the admin API. Every impersonated request is attributed to the operator in the admin audit log. | — |
 | `agent` | operational | declared-only | `agent:read`, `agent:write` | Agent loop operations. | — | — |
 | `agent:write` | operational | enforced | — | Change agent circuit breakers. | — | `POST /api/v1/admin/agent/breakers`, `POST /api/v1/admin/agent/breakers/:id/reset` |
 | `backfill:write` | operational | enforced | — | Run Stellar event backfills. | — | `POST /api/v1/admin/stellar/backfill` |
 | `dlq:write` | operational | enforced | — | Replay, retry and resolve dead-lettered work. | — | `POST /api/v1/admin/dlq/replay`, `POST /api/v1/admin/dlq/resolve`, `POST /api/v1/admin/dlq/retry`, `POST /api/v1/admin/notifications/dlq/:id/retry` |
 | `fiat:write` | operational | enforced | — | Change fiat provider failover state. | — | `POST /api/v1/admin/fiat/providers/:name/failover` |
+| `flags:write` | operational | enforced | — | Manage feature flags, staged rollouts and emergency rollbacks. | — | `POST /api/v1/admin/feature-flags/:key/reset`, `POST /api/v1/admin/feature-flags/:key/rollback`, `POST /api/v1/admin/feature-flags/:key/staged-rollout`, `POST /api/v1/admin/feature-flags/emergency-disable-all`, `PUT /api/v1/admin/feature-flags/:key` |
 | `messages:write` | operational | enforced | — | Retry and recover failed message deliveries. | — | `DELETE /api/v1/admin/messages/:id`, `POST /api/v1/admin/messages/:id/retry`, `POST /api/v1/admin/messages/retry-dead-letters` |
 | `risk-metadata:write` | operational | declared-only | — | Review and publish protocol risk metadata. | No route requires this scope today — the risk-metadata review workflow is administered from src/config/riskMetadataAdmin.ts, not through the API. Declared so a key can be provisioned ahead of a route that needs it. | — |
 <!-- END GENERATED: admin-scope-catalog -->

docs/DOCUMENTATION_INDEX.md

@@ -1,3 +1,3 @@
 # Documentation Index - Issue #23: Vault Events Persistence
 
 ## Quick Navigation
@@ -17,6 +17,7 @@
 - **[REBALANCE_EXPOSURE_COST.md](REBALANCE_EXPOSURE_COST.md)** - Rebalance exposure caps (#346) and grounded cost model + payback gate (#347): resolution, tighten-only merge, residual routing, conservative-by-default decisions
 - **[CORRELATION_DIVERSIFICATION.md](CORRELATION_DIVERSIFICATION.md)** - Portfolio APY correlation matrix + diversification score (#348): alignment, null-on-degenerate semantics, weighted score, caveat
 - **[YIELD_COMPOSITION.md](YIELD_COMPOSITION.md)** - Yield base/incentive decomposition + effective APY (#349): haircut model, schema columns, flag-gated consumption, emissions risk modifier, yield-breakdown endpoint
+- **[FEATURE_FLAGS.md](FEATURE_FLAGS.md)** - Feature flag configuration, deterministic staged rollouts, emergency rollback runbook, and evaluation observability (#494)
 - **[MESSAGING_DELIVERY.md](MESSAGING_DELIVERY.md)** - Telegram & WhatsApp message delivery reliability, retry/fallback policy, metrics, and recovery admin API (#493)
 - **[WEBHOOK_SECURITY.md](WEBHOOK_SECURITY.md)** - Inbound fiat webhook HMAC validation, freshness windows, replay receipts, and failure responses
 - **[PRISMA_QUERY_PERFORMANCE.md](PRISMA_QUERY_PERFORMANCE.md)** - Hot webhook query plans, supporting indexes, and the query-index regression check