OpenXR Reason-Code Version Migration Mixed Adjudication and Policy Drift on Quest - Fix

After you ship a reason-code taxonomy update (split codes, new context rules, or remapped policy effects), some disputes still close under the old semantics while others use the new set. Promotion gates, waiver behavior, and confidence-band downstream policy then disagree with what reviewers thought they logged.

In 2026, this shows up more often on Quest lanes because adjudication volume is high and teams roll code-set changes without a bounded migration window or lineage on each close event.

Problem

Typical symptoms:

the same reason code appears to mean different things before and after a rollout cutover
policy recompute hashes differ for “similar” disputes closed days apart
reopens are re-evaluated with a different code version than the original close
dashboards show spikes in out-of-context code usage or missing version metadata
escalation packets cite tie-break rules that no longer match the active registry

If mixed-version handling is undefined, you get policy drift that looks like reviewer error.

Direct answer

Run reason-code changes as versioned migrations: assign every adjudication a reason_code_version (and migration window ID), enforce compatibility mapping for in-flight work, block closes that lack version lineage, and define one explicit reopen policy (stay on original version with overlay, or migrate with logged remap).

Root cause summary

Mid-window semantic switch — v2 codes go live before in-flight v1 disputes finish.
No lineage on close — systems cannot tell which registry interpretation applied.
Partial validator updates — new context rules reject some paths while old paths still write legacy codes.
Ad hoc reopen handling — reopened cases silently pick “latest” version without remap logs.
Policy recompute decoupled — recompute runs without the same version tuple as the adjudication record.

Fastest safe fix path

Freeze further code-set edits until migration state is explicit (preparation / migrate / stabilize).
Backfill required fields on close: reason_code_version, migration_window_id (if applicable), policy_hash.
Publish compatibility map (old → new) and block unmapped legacy codes in active migration lanes.
Pick one reopen rule for the window (see below) and document it in the runbook.
Replay a small sample of boundary disputes before expanding migration scope.

Step-by-step fix

1) Declare migration window metadata

Minimum fields operators and tooling must share:

migration_window_id
version_from / version_to
phase: preparation, controlled migration, or stabilization
scope (which routes/lanes)

Without a window ID, postmortems cannot separate rollout artifacts from real quality regressions.

2) Enforce close-time lineage

At adjudication close:

reject if reason_code_version is null
reject if selected code is not valid for active window + context
attach policy_hash produced under that version

This stops “silent mixed” closes.

3) Apply compatibility mapping consistently

For each changed family:

define 1:1, 1:n, or retired mappings with required context fields
disallow free-text or unmapped “temporary” codes in production lanes

4) Choose reopen handling (one policy per window)

Option A — Original version + overlay
Reopen stays on the close-time version; compatibility overlay maps display/reporting only.

Option B — Migrate on reopen
Reopen moves to current version but must log remap_path and preserve original lineage for audit.

Do not mix A and B ad hoc per reviewer.

5) Align policy recompute

Ensure recompute jobs read the same reason_code_version and tuple as the adjudication row. If recompute uses “latest always,” you will see drift even when adjudication was correct.

6) Red-state guardrails

If mapped-code reopen rate or policy divergence crosses threshold:

pause scope expansion
require secondary review on affected families
publish a short operator advisory with expiry

Verification checklist

[ ] Sample of recent closes includes version + window metadata on 100% of production-lane disputes.
[ ] No unmapped legacy codes appear in migration-scoped lanes.
[ ] Reopen replay shows consistent policy output for equivalent evidence under chosen reopen policy.
[ ] Exception queue for migration violations is draining within SLA.

Alternative fixes and prevention

Strict cutover (single instant switch) only when change is small and volume is low; otherwise prefer phased migration with dual-read sampling.
Defer behavioral remaps until a scheduled governance window; ship clarification-only doc updates first if pressure is high.
Keep dual-write modes time-boxed; retire them in stabilization or they become permanent complexity.

FAQ

Can we skip version fields if the change is “just renaming”

No. Renames still change analytics joins and audit replay; store version lineage even for clarification-only releases if tooling behavior changes.

Should migration run during the busiest release day

Avoid starting behavioral migrations on peak deployment days unless rollback is pre-approved and rehearsed.

What if we already shipped without lineage

Backfill by time bands where possible, mark inferred rows explicitly, and do not use inferred lineage for automatic promotion decisions until audited.

Escalation criteria

Escalate to governance hold review when:

policy hash divergence rate crosses your migration playbook threshold
migration exception backlog breaches SLA
multiple routes show conflicting outcomes for the same mapped code family

Bookmark this fix next to your reason-code registry and migration runbook so operators can recover quickly when mixed-version drift appears.