OpenXR Context Validation Blocks Closes After Doc-Only Registry Publish on Quest - Fix

You publish a documentation-only reason-code registry update: examples, operator notes, and cross-links—no intentional effect-table change. Within hours, context validation starts rejecting otherwise valid closes. Reviewers see generic errors like missing required context key even though the same packet passed last week.

In 2026, this spikes on Quest adjudication lanes because validation services often load latest schema artifacts or JSON Schema drafts while adjudication rows still reference the prior registry generation. A doc-only publish can still rotate artifact hashes and trigger false breaking-change behavior when tooling does not distinguish docs drift from effect drift.

Problem

Typical symptoms:

validator version bumps without a matching reason_code_version increment policy
CI passes on Friday; Monday closes fail after a weekend docs publish
preview modal accepts a packet; submission endpoint rejects it with context-validation errors
required-context key lists grow because validators merge draft CMS fields into production checks
migration windows look unstable even when effect tables did not change

If operators cannot tell doc churn from policy churn, they bypass validators—creating worse downstream risk.

Direct answer

Separate documentation publishes from schema-effect publishes: pin validators to the adjudication row’s registry bundle generation; gate doc-only releases behind schema-diff checks; and ensure context-validation rules load from the same versioned artifact your close pipeline asserts—not from “latest” drafts.

Root cause summary

Latest-schema coupling — validators pull newest JSON Schema or CMS export regardless of close-time version.
Implicit merge rules — doc blocks introduce optional narrative fields mistaken for mandatory validation keys.
Hash rotation without semver discipline — artifact checksum changes even when logical effects are unchanged.
Dual writers — editorial registry updates land in the same bucket as automation-facing bundles without promotion staging.
Missing publish classification — releases lack change_class: docs_only | effects_touching | breaking.

Fastest safe fix path

Compare failing validator errors against registry_bundle_hash on last known good closes.
Roll validation lane to prior pinned bundle or disable strict context expansion until parity replay finishes.
Classify the triggering publish as docs-only or effects-touching with evidence (diff artifacts).
Patch loaders so adjudication validation resolves validation_schema_id from the row tuple.
Add CI proving doc-only publishes do not alter machine-checkable required-key sets without explicit bump.

Step-by-step fix

Step 1: Establish publish classification

Every registry publish ships metadata:

change_class (docs_only, effects_non_breaking, effects_breaking)
machine_schema_hash (keys automation validates)
human_doc_hash (non-authoritative for closes)

Doc-only publishes must show machine_schema_hash unchanged or include an explicit waiver reason.

Verification checkpoint: release notes link to diff artifact stored in CI.

Step 2: Pin validators to adjudication version

At validation time:

read reason_code_version and registry_bundle_ref from adjudication payload
fetch validation schema from that bundle—not CMS preview

Verification checkpoint: turning off CMS draft feed does not change validation outcomes for historical replay fixtures.

Step 3: Separate narrative fields from machine keys

Ensure editorial additions cannot become mandatory unless promoted:

narrative lives in notes_md excluded from schema required lists
machine keys listed only in validation_contract.json within versioned bundle

Verification checkpoint: doc editors can publish prose without touching automation keys.

Step 4: Fix accidental required-key inflation

Search validators for patterns that union all keys seen in sample rows into required sets—replace with explicit contract files.

Verification checkpoint: schema-required count stable across doc-only publishes in replay harness.

Step 5: Align preview and submission endpoints

Both must call the same validation module with identical bundle pointers; avoid “preview uses snapshot, submit uses live.”

Verification checkpoint: identical packets succeed or fail identically across endpoints.

Step 6: Migration-window coordination

During migration, doc publishes still rotate hashes—communicate freezes or pin lanes until stabilization completes.

Verification checkpoint: migration dashboards segment validator failures by bundle generation.

Verification checklist

[ ] Doc-only registry publish produces machine_schema_hash parity vs prior release or explicit waiver with signer approval.
[ ] Context validation loads schemas from adjudication-stored bundle references.
[ ] Replay suite passes for frozen disputes before and after doc-only publish.
[ ] Preview and submission disagree rate drops to zero on regression fixtures.
[ ] Editorial publishes no longer expand required context keys without governance approval.

Alternative fixes and prevention

Shadow validation lane — run new bundles alongside pinned bundles; compare failure deltas before promotion.
Feature flags per bundle generation — toggle strict context expansion only when effects change.
Weekly contract freeze windows during peak Quest release trains.
Automated schema linter — fails CI when optional narrative fields appear under required.

FAQ

Are doc-only publishes ever safe without CI proof

Only when machine_schema_hash matches prior release or explicit waiver documents why automation differs.

Should validators ignore documentation entirely

No—operators need docs—but automation must consume typed contracts, not rendered prose fields.

What if CMS accidentally marks a field required

Treat as incident: roll back CMS publish or publish corrective bundle with signer-visible changelog before lanes unblock.

Escalation criteria

Escalate when:

unexplained validator failure rate spikes within hours of registry publish without effects classification
preview versus submission mismatch reappears after prior fixes
migration stabilization gates cannot clear because validation noise masks real quality regressions

Bookmark this fix next to your registry promotion pipeline so doc-only releases stop masquerading as silent schema upgrades.