Simplify ordinary settings edits while preserving revision and authorization guarantees #4222

Priority: P3 · Type: refactor

Problem

Routine settings changes currently pass through a draft/review/frozen-confirmation workflow with substantial state-machine and UI ceremony. This makes ordinary configuration editing harder to use and maintain than its underlying operation requires.

The editor's top-level state union contains nine statuses, including separate reviewing, confirmed, review_superseded, and submitting states. The review UI freezes a proposed patch against a revision and adds a confirmation step before submission. Some product copy also explains GET/PATCH route mechanics rather than telling users where a setting can be changed.

Evidence category

This is a usability and maintenance refactor, not a claim that revision checking or authorization is unnecessary. At the audited revision, the settings workspace contains 5,840 non-test TS/TSX lines across 16 files; the state machine is 760 lines and the model 1,019. Counts include comments and blanks. No user study was performed, so simplification should be validated against representative settings tasks.

Proposed change

For ordinary reversible edits, use one editable draft and one Save action with pending, applied, validation-error, conflict, and permission/unavailable feedback as needed. Hold a stable patch and request identity for the actual submission without requiring the user to manually advance through internal protocol phases. Retain additional review only for specifically identified changes whose consequences warrant it.

Preserve server-side compare-and-swap revisions, request idempotency, authorization, read-only keys, scope restrictions, restart/resync notices, and truthful uncertain-outcome handling. Simplification must not silently overwrite a concurrent edit or retry an effect with a new identity.

Acceptance criteria

• An ordinary valid settings change can be saved directly without mandatory review and freeze-confirm clicks.
• A stale revision produces an actionable conflict and never overwrites unseen changes.
• Lost authority and read-only configuration remain enforced; the UI explains the user's next action in plain language.
• Retries preserve the appropriate request identity and uncertain outcomes remain explicit.
• Remove redundant state transitions/components and retain behavioral tests for concurrency, authorization, failure, and successful editing.

Audit provenance

Source evidence is pinned to 30c23baa. Relevant implementation was rechecked against master at 5daa37d1; the finding remains applicable. Verification performed and its limits are stated above.