OpenXR Reason-Code Compatibility Map Missing During Migration on Quest - How to Fix

You ship a reason-code taxonomy update, then a reopened dispute references a legacy code that no longer exists in the active registry. Review tools show "unknown code," policy recompute falls back to defaults, and audit packets cannot explain why a closure changed class between windows.

In 2026, this is a frequent Quest operations problem because teams are shipping versioned reason-code sets more often, but compatibility maps and remap lineage fields are still treated as optional. They are not optional once mixed-version adjudication is in flight.

If your migration window is active, the safest path is to block closes and reopens that lack deterministic old-to-new mapping metadata, then replay boundary cases under a single remap policy.

Problem

Typical symptoms:

• reopened disputes fail validation with "legacy reason code not recognized"
• close packets contain reason_code_version but no remap_path or mapping rule ID
• policy outputs diverge after reopen for equivalent evidence
• reviewers choose ad hoc replacement codes, creating inconsistent route behavior
• audit exports show missing lineage between original close and migrated reopen

When compatibility mapping is incomplete, teams confuse governance drift with reviewer mistakes.

Direct answer

Publish and enforce a versioned compatibility map (legacy code -> target code + required context), require remap lineage fields on every migrated reopen/close, and reject adjudications that cannot resolve to a deterministic mapping rule ID.

Root cause summary

1. Partial taxonomy rollout - code registry updated before full legacy mapping was published.
2. No remap contract enforcement - systems allow closes without mapping_rule_id and remap_path.
3. Mixed reopen behavior - some routes keep original code, others auto-migrate to latest.
4. Policy recompute mismatch - recompute service reads latest taxonomy without reopen lineage context.
5. No boundary replay gate - migration expands before validating high-risk legacy families.

Fastest safe fix path

1. Freeze new taxonomy edits until compatibility coverage is measurable.
2. Publish one compatibility map artifact with version + checksum.
3. Enforce remap lineage fields at close/reopen write time.
4. Choose one reopen policy for the active migration window.
5. Replay boundary packets and compare policy outputs before resuming normal throughput.

Step-by-step fix

Step 1: Publish a compatibility map artifact

For each retired or split reason code, include:

• legacy_code
• target_code
• mapping_rule_id
• required context keys
• migration window scope (window_id, routes, effective dates)

Store a checksum so reviewer tools and recompute jobs can prove they used the same mapping table.

Verification checkpoint: mapping artifact is versioned and references 100% of legacy codes touched in this rollout.

Step 2: Enforce remap lineage at write time

For any migrated reopen/close, require:

• reason_code_version_from
• reason_code_version_to
• mapping_rule_id
• remap_path (single-hop or multi-hop)
• policy_hash_after_remap

Reject writes that only include the target code label without lineage metadata.

Verification checkpoint: zero newly written adjudications in migration lanes have null mapping_rule_id.

Step 3: Pick a single reopen policy

Use one policy per migration window:

• Policy A (stable-origin): reopen remains on origin version; mapped display only.
• Policy B (migrate-on-reopen): reopen moves to latest and must log deterministic remap lineage.

Do not let route owners switch between A and B during the same window.

Verification checkpoint: reopen records include one explicit reopen_policy_id.

Step 4: Align policy recompute with remap lineage

Policy recompute must read remap lineage fields, not just the final code label.

At minimum, join by:

• dispute ID
• reopen sequence
• mapping_rule_id
• reason_code_version_from -> reason_code_version_to

If recompute only sees "latest target code," you will misclassify historical closes.

Verification checkpoint: replayed recompute for sampled migrated cases matches close-time policy class.

Step 5: Run boundary replay before expansion

Build a replay set with:

• top-volume legacy families
• prior escalation cases
• reopened disputes across migration cutover timestamps

Compare:

• final policy class
• confidence band
• escalation eligibility

Pause migration expansion if divergence exceeds your playbook threshold.

Verification checkpoint: boundary replay sign-off recorded with explicit go/hold decision.

Verification checklist

• [ ] All migration-scoped legacy codes resolve through a published compatibility map rule.
• [ ] Reopen and close writes in migration windows always include remap lineage fields.
• [ ] Recompute output matches close-time policy class for sampled migrated disputes.
• [ ] No ad hoc reviewer-selected replacement codes are accepted without mapping rule IDs.
• [ ] Migration exceptions are draining inside SLA with owner + expiry assigned.

Alternative fixes and prevention

• Hotfix patch map for urgent gaps: publish a short-lived supplemental map and merge into the canonical artifact within one governance cycle.
• Family-by-family rollout if full-map confidence is low; do not expose partial global remaps to production lanes.
• Pre-merge mapping tests in CI: reject taxonomy PRs when legacy coverage is incomplete.
• Monthly map hygiene review: retire dead mappings and revalidate context requirements to prevent stale remap logic.

Related problems and links

• OpenXR context validation blocks closes after doc-only registry publish on Quest - fix
• OpenXR policy recompute uses latest registry while adjudication rows stay versioned - Quest fix
• OpenXR reason-code version migration mixed adjudication and policy drift on Quest - fix
• OpenXR route closure reviewers disagree on confidence band - calibration dispute adjudication Quest fix
• OpenXR option scorer model version binding mismatch on Quest build - release lane and tuple lock fix
• Guide: Unity 6.6 LTS OpenXR Reason-Code Drift Detection and Adjudication Quality Calibration Loops Preflight
• Guide: Unity 6.6 LTS OpenXR Dispute Backlog SLO Tuning and Adjudication Automation Guardrails Preflight
• Course: Lesson 146 - Reason-Code Drift Detection and Adjudication Quality Calibration Loops (2026)
• Blog: Quest OpenXR reason-code version rollout governance and safe migration windows 2026 small teams
• Blog: Quest OpenXR reason-code drift detection and adjudication quality calibration loops 2026 small teams

Official references: Unity OpenXR documentation and Khronos OpenXR specification.

FAQ

Can we map one legacy code to multiple target codes

Yes, but only with explicit context requirements and deterministic precedence. If context is missing, reject the close/reopen instead of guessing.

Should we backfill remap lineage for older records

Backfill where evidence supports deterministic mapping. Mark inferred lineage clearly and exclude inferred rows from automatic promotion decisions until reviewed.

Is "latest code wins" acceptable for reopen

Only if your reopen policy explicitly defines migrate-on-reopen and logs full remap lineage. Implicit latest-code behavior causes audit and policy drift.

Escalation criteria

Escalate to governance hold review when:

• mapped reopen divergence crosses your migration-window threshold
• legacy codes appear in production lanes without mapping rule IDs
• remap exception backlog exceeds SLA in two consecutive review windows

Bookmark this fix for every reason-code migration window. It prevents silent remap drift from becoming release-lane policy instability.