# UI provider switch and rollback runbook

**WBS / Requirement / UI / Test:** AEG-V16-015 / REQ-V16-UI4-07 / UI-V16-UI4-07 / T-V16-UI4-07
**Owners:** FE Lead (primary), UX/QA (secondary)
**Mode:** human-approved deployment operation only; provider selection is startup-only.

## Source / Assumption / Unknown / Decision Required

- **Source:** `contracts/ui/ui-adapter.v4.json`, `frontend/src/main.ts`, `frontend/src/shared/ui/provider/resolveUiProvider.ts`, `tools/validate_v16.py`.
- **Assumption:** deployment configuration supplies `VITE_UI_ADAPTER` before building the immutable frontend artifact. The application does not read a mutable provider setting after bootstrap.
- **Unknown:** visual-regression baseline, keyboard/focus acceptance artifact, and production performance budget approval are not present in this workspace.
- **Decision Required:** FE Lead and UX/QA must approve the named target provider and attach all required evidence before a production switch. This runbook never authorizes an automatic provider switch.

## Safety invariants

1. Allowed provider values are `primevue` and `native`; any other value fails closed at startup.
2. Feature source remains vendor-free. Existing application-owned components under `frontend/src/shared/ui/components/` may use the selected vendor directly to preserve full component functionality. New vendor-neutral components may use `frontend/src/shared/ui/adapter/`; the direct-component ownership harness prevents accidental adapter regression.
3. Changing a provider means building and deploying a new artifact. Do not mutate the active application's global provider.
4. Rollback restores the last approved artifact and its recorded provider value. It does not alter data, decisions, evidence, or audit records.

## Preflight — required before approval

Record the operator, UTC/KST timestamp, source commit SHA, artifact hash, previous/target provider, and correlation/change reference in the release evidence.

| Check | Required evidence | Result field |
| --- | --- | --- |
| Contract conformance | `pnpm test -- --run src/shared/ui/adapter/tests/uiAdapter.contract.spec.ts src/shared/ui/tests/adapterCompatibility.spec.ts` | test output path/hash |
| Vendor boundary | `python tools/validate_v16.py` returns `PASS=1` | output path/hash |
| Startup selection | fresh artifact starts once with the target `VITE_UI_ADAPTER` value | startup log reference |
| Keyboard/focus | approved keyboard/focus test for fields, dialog, grid, and tabs | QA evidence ID |
| Accessible name | automated/manual accessibility report for changed screens | QA evidence ID |
| State matrix | T01–T10 result for the affected screen catalogue | QA evidence ID |
| Visual regression | approved baseline comparison for target viewport set | visual evidence ID |
| Performance | approved large-list interaction evidence using the agreed budget | performance evidence ID |

Any missing, failed, expired, or mismatched evidence blocks the switch. Do not replace a missing target or baseline with a guessed threshold.

## Approved switch procedure

1. Confirm a human change approval references the exact commit, artifact hash, target provider, and all preflight evidence.
2. Build a new frontend artifact with `VITE_UI_ADAPTER=<target>`; preserve the build output and configuration hash.
3. Deploy via the approved release process. Do not change the provider inside a running application.
4. Verify the startup log identifies the target provider and that the version/hash matches the approved artifact.
5. Run the approved smoke route and the affected T01–T10 checks. Stop on the first failure and begin rollback.
6. Append the outcome, timestamps, operator, artifact hash, and evidence links to the release ledger; never overwrite a prior entry.

## Rollback procedure

Use rollback when startup selection fails, a required state/keyboard/accessibility check fails, the visual comparison is rejected, or the approved performance evidence is not reproduced.

1. Declare the change stopped; record the incident/change reference and preserve browser/server logs.
2. Select the previously approved immutable artifact and its recorded provider configuration.
3. Deploy that artifact through the approved release process; do not hot-swap the provider in memory.
4. Verify its startup provider, artifact hash, critical smoke route, and a focused regression check.
5. Append a rollback outcome with reason, timestamps, operator, evidence links, and owner/secondary notification. Retain the failed artifact and its evidence for diagnosis.
6. Open a corrective WBS/issue for the failed contract, accessibility, visual, or performance condition. A rollback does not silently waive the failed gate.

## Evidence record template

```text
Change reference:
Operator / secondary:
Previous provider + artifact SHA:
Target provider + artifact SHA:
Contract / boundary evidence:
Keyboard / accessible-name / T01–T10 evidence:
Visual / performance evidence:
Startup log reference:
Outcome: switched | blocked | rolled back
Rollback reason (if applicable):
Recorded at (UTC) / display time (KST):
```
