Module drift 

cargo xtask codex-schema drift [--dir <dump-dir>] [--json] [--strict] - diffs the vendored schema/methods.json + schema/CODEX_VERSION.txt against a fresh codex app-server generate-json-schema dump (or an existing dump directory passed via --dir), so an upstream codex version bump that adds, removes, or renames a method can’t silently slip past the version-string-only staleness check in crates/shared/codex-app-server-client/build.rs.

Reuses regen’s exact schema-load + manifest-build code path (load_combined_defs + merge::build_methods_manifest) to build the “installed” manifest in memory - this module never reimplements schema parsing or method extraction, it only diffs two already-built manifests. See crates/shared/codex-app-server-client/README.md’s “Regenerating the schema” section, build.rs’s non-fatal staleness warning, and codex_app_server_client::compat::CompatibilityReport (schema-version + method-count only) for the prior art this check sharpens into a real diff.

Structs

ChangedMethod 🔒

DriftOptions 🔒

DriftReport 🔒

MethodEntry 🔒

MethodSignature 🔒

One method’s diffable signature: everything about it other than its name that regen derives from the schema. Notification entries never carry a response_type key in the manifest JSON, so response_type is None for every notification-section entry - correctly comparing “no key” in both vendored and installed as equal, rather than a spurious “changed”.

SectionDiff 🔒

VersionDelta 🔒

Enums

Outcome 🔒

Constants

SECTIONS 🔒

Section names in the vendored/installed methods.json shape, in the fixed order the report is always rendered in.

USAGE 🔒

Functions

build_installed_manifest 🔒

Builds the “installed” manifest via the exact same code path regen uses to write methods.json (load_combined_defs + build_methods_manifest), then converts it to a Value so it can be diffed with the same section-shaped logic as the vendored JSON file - no separate parsing path to drift out of sync with the real one.

build_report 🔒

codex_version_or_skip 🔒

Runs codex --version and distinguishes “codex is not on PATH at all” (the one condition this check must never hard-fail on) from every other failure mode (codex present but broken), which are real errors.

compute_outcome 🔒

Builds the diff outcome: either a skip reason (no codex on PATH and no --dir) or a full DriftReport. Keeps the temp dump directory (when one is created) alive for the duration of the manifest build via the returned TempDir guard’s drop timing.

diff_section 🔒

Diffs one section (client_requests, server_requests, server_notifications, or client_notifications) between the vendored and installed manifests. added/removed/changed are each sorted by method name for stable, scannable output regardless of the underlying BTreeMap iteration order (which is already method-name order, but the explicit sort documents the intent and survives a future change to how the maps are built).

generate_fresh_dump 🔒

Shells out to the exact command documented in this crate’s regen workflow (codex_schema.rs’s print_help) to produce a fresh dump.

installed_version_best_effort 🔒

Best-effort installed-version lookup for --dir mode: codex is purely informational there (the dump already exists), so any failure is silently treated as “unknown” rather than blocking the diff - mirrors build.rs’s check_codex_staleness.

load_vendored_manifest 🔒

load_vendored_version 🔒

parse_args 🔒

print_human_report 🔒

run

section_map 🔒

Parses one manifest’s section array (client_requests, etc.) into a method -> signature map. Shared by both the vendored JSON file and the installed manifest (also serialized to Value), so both sides go through identical extraction logic - a field name typo here would otherwise show up as one specific, hard-to-diagnose false “changed” or “added”/“removed” pair instead of a loud, obvious error.