PREWAVE-BE-108 — Persist Protocol Admin Maintenance and Emergency Control State #809

Problem context

ProtocolAdminService stores maintenance mode, scheduled maintenance, emergency states, and service enablement in process-local fields and Maps. Restarting the API or running multiple replicas can lose or disagree on active operational controls. These controls are exposed through privileged admin endpoints and must not silently reset.

Technical scope

Persist maintenance schedules, active maintenance state, emergency actions, expiry, service state, actor, reason, and audit references in a durable store. Use atomic transitions and optimistic concurrency so concurrent admin actions cannot produce conflicting control state. On startup, reconstruct the active operational state and reconcile expired schedules. Keep operational controls separate from on-chain protocol authority; if an action requires an on-chain pause, report it as pending until the canonical contract event confirms it.

Required tests

• Maintenance and emergency state survives restart and is consistent across replicas.
• Concurrent activate/deactivate/schedule/cancel operations are atomic and audited.
• Expired controls reconcile deterministically after downtime.
• Unauthorized roles cannot change controls.
• On-chain-required actions remain pending until canonical event/finality evidence exists.
• No stale local Map can override the persisted state.

Security and architecture constraints

• Durable state must be consistent across restarts and replicas where the feature is user-, privacy-, security-, or operations-critical.
• Fail closed when persistence, authorization, policy version, or source provenance cannot be verified.
• Keep protocol authority in canonical contracts and finalized event projections.
• Protect contact details, consent records, subject identifiers, capabilities, and audit metadata.
• Do not create new protocol mutation authority in API services.

Acceptance criteria

• The process-local-only behavior is replaced by a durable/shared implementation where required.
• Ownership, role, and privacy boundaries are enforced.
• Concurrency, restart, retention, and failure behavior are covered by automated tests.
• Documentation describes the persistence and operational model.
• Exact-head required CI passes and independent review is recorded.

Dependencies

• Existing admin role and audit-trail boundaries.
• Canonical contract pause/emergency events for any operation that changes protocol state.

Non-goals

Changing the protocol's on-chain emergency authority or introducing new emergency powers.

Complexity and points

• High — 200 points

Candidate only. Activation remains maintainer-controlled; do not apply Stellar Wave as part of implementation.