Environment switches
This appendix is the single operator-facing catalog of every environment
switch the toolchain reads: the rollback levers to reach for during an
incident, and the benchmark and test-harness knobs. It is kept in lockstep
with the in-code registry (oxc_diagnostics::env_registry) by a drift guard
that fails the build if this page and the registry name a different set of
switches.
An environment switch is a process-environment variable in the engineered
OXC_ / OX_ namespace that changes runtime behavior. Operational
configuration — install paths, service endpoints, credentials, and the
standard HOME / PATH / DATABASE_URL variables — is not a switch and is
documented with the deployment guide instead.
Every switch name — including test-only and bench knobs — carries the
engineered OXC_ / OX_ product prefix. A bare topic prefix (DEFEAT_, …)
is refused: such names are too generic for the process environment and
collision-prone with ambient variables. So a defeat-plane soak knob carries
the product prefix — OXC_DEFEAT_PLANE_SOAK — rather than a bare topic-only
spelling.
Truthiness
Boolean switches follow one convention. A switch is engaged when its
variable is set to a truthy value and disengaged when unset or set to a
falsy value. Falsy values are the empty string and, case-insensitively, 0,
false, off, and no (surrounding whitespace ignored); every other value
is truthy. So NAME=1 engages and NAME=0 disengages any boolean switch —
an A/B run flips one between =1 and =0 without per-switch parse rules.
Switches with a numeric or string value (case counts, seeds, iteration counts) take that value directly and state their own default below.
Classes
- rollback — changes which code path serves production answers. Flipping it can change results, latency, or the artifact a source elaborates to. These are the incident levers.
- bench/probe — a benchmark, perf-probe, or observability knob with zero product effect: it changes what a measurement run does or reports, never the answer served.
- test-only — a test-harness control (a case count, a random seed, or a golden-file regeneration toggle) with zero product effect.
Rollback levers
| Switch | Effect when set | Default (unset) | Subsystem | Introduced |
|---|---|---|---|---|
OXC_DISABLE_CHECK_CONE_SLICING | disable check-cone slicing on the write path, forcing a full recheck of every check per commit | off (slicing enabled) | oxc-runtime (write path) | #1745 |
OXC_DISABLE_INCREMENTAL_FREEZE_INDEX | rebuild the freeze-witness index from scratch each generation instead of folding the commit delta | off (incremental fold enabled) | oxc-runtime (write gate) | #1771 |
OX_DISABLE_NAIVE_CACHE | disable the per-pass naive-arrangement cache | off (cache enabled) | oxc-reasoning (executor) | #1710 |
OX_DISABLE_DECODE_CACHE | disable decode-once relation sharing across a pass | off (cache enabled) | oxc-reasoning (executor) | #1735 |
OX_DECODE_VIEWS_UNCAPTURED | skip capturing the module-sourced declaration views at each warm-store build, forcing every per-request view rebuild through the decode scan | off (views captured once per warm-store build) | oxc-runtime (indexed views) | #1857 |
OX_DECODE_BODIES_UNFROZEN | skip capturing the frozen committed-body snapshot at each warm-store build, so every per-request store clone re-decodes the committed ABox bodies | off (committed bodies frozen once per warm-store build) | oxc-runtime (decode cache) | #1865 |
OX_DISABLE_NAF_MEMO | disable the negation-as-failure verdict memo | off (memo enabled) | oxc-reasoning (executor) | #1710 |
OX_DISABLE_MODEL_RESYNC | disable the post-commit model-resync route, falling back to wholesale drop-and-rebuild of the derived model | off (resync route enabled) | oxc-runtime (maintenance router) | #1772 |
OXC_ENABLE_INCREMENTAL_CIRCUITS | prefer incremental circuit maintenance over the established per-commit recompute, falling back where circuits are unsupported | off (established recompute) | oxc-runtime (maintenance mode) | #1753 |
OXC_REQUIRE_INCREMENTAL_CIRCUITS | require incremental circuit maintenance — hard-error instead of falling back to the established recompute | off (fallback allowed) | oxc-runtime (maintenance mode) | #1753 |
OXC_ENABLE_UNAUDITED_PRODUCT_INCREMENTAL_CIRCUITS | prefer the unaudited Product well-founded circuit backend when circuits are enabled | off (qualified Product default) | oxc-runtime (maintenance mode) | #1863 |
OXC_ENABLE_AUDITED_PRODUCT_INCREMENTAL_CIRCUITS | prefer the audited Product well-founded circuit backend (the opt-in publication oracle) when circuits are enabled | off (qualified Product default) | oxc-runtime (maintenance mode) | #1863 |
OXC_REQUIRE_UNAUDITED_PRODUCT_INCREMENTAL_CIRCUITS | require the unaudited Product circuit backend — hard-error instead of selecting any other maintenance route | off (mode chosen by the other flags) | oxc-runtime (maintenance mode) | #1863 |
OXC_REQUIRE_AUDITED_PRODUCT_INCREMENTAL_CIRCUITS | require the audited Product circuit backend — hard-error instead of selecting any other maintenance route | off (mode chosen by the other flags) | oxc-runtime (maintenance mode) | #1863 |
OXC_USE_ESTABLISHED_WFS_INCREMENTAL_CIRCUITS | select the established WFS circuit backend instead of the qualified Product default when circuits are enabled — the operational escape hatch | off (qualified Product default) | oxc-runtime (maintenance mode) | #1880 |
Each rollback lever is read once per process (behind a OnceLock), so it must
be set before the process starts; changing it mid-run has no effect.
Bench and probe knobs
| Switch | Effect | Default (unset) | Subsystem | Introduced |
|---|---|---|---|---|
OX_TRACE_ARR | emit per-pass arrangement trace tallies and counters | off (no trace) | oxc-reasoning (executor) | #1690 |
OX_DECODE_COUNTERS | emit committed-body CBOR decode-execution counters to stderr | off (no counters) | oxc-runtime (decode probe) | #1657 |
OXC_PROOF_BENCH_AFFECTED | number of affected checks in the materialization-impact probe | 0 | oxc-runtime (materialization probe) | #1745 |
OXC_PROOF_BENCH_ITERS | iteration count for the materialization-impact probe | 100 | oxc-runtime (materialization probe) | #1745 |
OXC_PROOF_BENCH_OPAQUE | include opaque checks in the materialization-impact probe | off (opaque checks excluded) | oxc-runtime (materialization probe) | #1745 |
OXC_FREEZE_INDEX_BENCH | commit count for the freeze-index micro-benchmark; absent skips it | unset (skipped) | oxc-runtime (freeze-index bench) | #1771 |
OXC_FREEZE_INDEX_BENCH_RUNS | interleaved run count per cell for the freeze-index micro-benchmark | unset (bench default) | oxc-runtime (freeze-index bench) | #1771 |
OXC_PREINTERN_BENCH | visible-individual count for the enumeration-order pre-numbering pre-pass cold-seed micro-benchmark; absent skips it | unset (skipped) | oxc-runtime (pre-numbering bench) | #1851 |
OXC_SETTLE_STATS | emit process-cumulative settle route counters (eligible/counting/fallback) to stderr on every settle; per-settle deltas are the difference of successive lines | off (no counters) | oxc-reasoning (settle maintainer) | #1785 |
OXC_INCREMENTAL_SCALE | scale profile for the incremental-scale benchmark: million, ten-million, or steady-million | unset (default scales) | oxc-reasoning (incremental-scale bench) | #1753 |
OXC_CORRECTION_SAMPLES | sample count for the incremental recursive-corrections benchmark (floored at 10) | 10 | oxc-reasoning (recursive-corrections bench) | #1753 |
OXC_SAMPLED_COUNT | sample count per cell for the sampled incremental benchmark | 30 | oxc-reasoning (sampled bench) | #1753 |
OXC_SAMPLED_DELTA | run only the cells with this delta size in the sampled incremental benchmark | unset (all delta sizes) | oxc-reasoning (sampled bench) | #1753 |
OXC_SAMPLED_IMPLEMENTATION | run only this maintenance implementation in the sampled incremental benchmark: circuit, product, established, or full | unset (all implementations) | oxc-reasoning (sampled bench) | #1753 |
OXC_SAMPLED_PREPARATION_PHASES | record and report per-phase preparation timings in the sampled incremental benchmark | off (no phase report) | oxc-reasoning (sampled bench) | #1753 |
OXC_SAMPLED_PROFILE | scale profile for the sampled incremental benchmark: million or ten-million | unset (default scales) | oxc-reasoning (sampled bench) | #1753 |
OXC_SAMPLED_STATE | run only the cells with this state size in the sampled incremental benchmark | unset (all state sizes) | oxc-reasoning (sampled bench) | #1753 |
OXC_SAMPLED_WORKLOAD | run only the workload with this name in the sampled incremental benchmark | unset (all workloads) | oxc-reasoning (sampled bench) | #1753 |
OXC_WELL_FOUNDED_PREPARATION_PHASES | record and report per-phase preparation timings in the well-founded incremental memory benchmark | off (no phase report) | oxc-reasoning (well-founded memory bench) | #1876 |
OXC_AGGREGATE_PREPARATION_PHASES | record and report per-phase preparation timings in the well-founded aggregate incremental memory benchmark | off (no phase report) | oxc-reasoning (aggregate memory bench) | #1753 |
Test-harness knobs
| Switch | Effect | Default (unset) | Subsystem | Introduced |
|---|---|---|---|---|
OXC_FUZZ_CASES | per-target proptest case count for the fuzz harness | 256 | oxc-fuzz | #304 |
OXC_DEFEAT_PLANE_SOAK | extra random-seed count run past the fixed CI seeds | unset (CI seeds only) | oxc-runtime (defeat-plane oracle) | #1793 |
OXC_DEFEAT_PLANE_SEED | evaluate exactly one seed, for isolated reproduction | unset (single-seed repro skipped) | oxc-runtime (defeat-plane oracle) | #1793 |
OXC_DEFEAT_EMIT_BLESS | regenerate the defeat-emission golden vectors instead of asserting against them | unset (assert against committed goldens) | oxc-runtime (defeat-emission vectors) | #1800 |
OXC_SETTLE_CHECK | re-run each A/B stratum settle as a full recompute and hard-error on any head-extent divergence (always on under cfg(test)) | off in release (always on under test) | oxc-reasoning (settle maintainer) | #1785 |
OXC_INCREMENTAL_CONFORMANCE_CORPUS | root directory of an external incremental-conformance corpus to replay | unset (external-corpus run skipped) | oxc-driver (conformance replay) | #1753 |
OXC_INCREMENTAL_CHECKPOINT_CHILD | marks the checkpointed child process the incremental read-model test re-executes itself as | unset (parent process) | oxc-runtime (incremental read-model test) | #1753 |
OXC_COMPILED_DEFEAT_PRODUCT_CHILD | marks the Product-mutation child process the compiled-defeat test re-executes itself as | unset (parent process) | oxc-runtime (compiled-defeat test) | #1753 |
OXC_COMPILED_DEFEAT_LOCALITY_CHILD | marks the tuple-locality child process the compiled-defeat test re-executes itself as | unset (parent process) | oxc-runtime (compiled-defeat test) | #1753 |
OXC_COMPILED_DEFEAT_REINSTATEMENT_CHILD | marks the reinstatement child process the compiled-defeat test re-executes itself as | unset (parent process) | oxc-runtime (compiled-defeat test) | #1753 |
OXC_COMPILED_DEFEAT_CHECKPOINT_CHILD | marks the checkpointed child process the compiled-defeat test re-executes itself as | unset (parent process) | oxc-runtime (compiled-defeat test) | #1753 |
OXC_CROSS_MODULE_DEFEAT_PRODUCT_CHILD | marks the Product-mutation child process the cross-module-defeat test re-executes itself as | unset (parent process) | oxc-runtime (compiled-defeat test) | #1753 |
OXC_LOCKSTEP_REQUIRED_CIRCUITS_CHILD | marks the child process the lockstep-retraction test re-executes itself as with the incremental circuit engine required | unset (parent process) | oxc-runtime (lockstep-retraction test) | #1898 |
OXC_LOCKSTEP_REQUIRED_UNAUDITED_PRODUCT_CHILD | marks the child process the lockstep-retraction test re-executes itself as with the unaudited product-time well-founded backend required | unset (parent process) | oxc-runtime (lockstep-retraction test) | #1898 |
OXC_LOCKSTEP_REQUIRED_AUDITED_PRODUCT_CHILD | marks the child process the lockstep-retraction test re-executes itself as with the audited product-time well-founded backend required | unset (parent process) | oxc-runtime (lockstep-retraction test) | #1898 |
Keeping this page honest
The registry (oxc_diagnostics::env_registry) is the source of truth; this
page is its human-readable projection. A drift guard scans the workspace and
fails the build if a switch-shaped variable is read anywhere without a
registry row, if a registry row is never read, or if this page and the
registry name different sets of switches. A new switch therefore cannot ship
without a row here.