KArtSell.Aegis/docs/CURRENT/ui-provider-switch.md

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. No feature source may import PrimeVue or AG Grid. Vendor imports are confined to frontend/src/shared/ui/adapter/primevue/.
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

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):