CRATONVM_* flag inventory

Report P1, Centralize configuration reads. Acceptance:

Environment variables are parsed once into a typed immutable configuration; semantic code contains no direct environment reads.

This file is the inventory half. It records every CRATONVM_* identifier, where it is read, whether it is declared, whether it latches, whether it can change a program's result, and its default — plus the plan for the reads that still go straight to std::env.

Contents

1. How to regenerate
2. Where the surface stands
3. Latching, and why an undeclared flag is a test hazard
4. What was declared in this pass
5. The typed configuration
6. Migration plan
7. The allowlist, and why each row is on it
8. Open reconciliation items
9. Full inventory

---

How to regenerate

tools/flag-census/render-inventory.sh

The table in Full inventory is generated, not maintained. For its first eight months that was a claim with no generator behind it, and the table drifted 42 rows behind INVENTORY while stating a declared count of 647 against a true 689. Nothing failed, because "generated" is exactly the label that stops anyone reading a file sceptically. There is now a generator (above) and a test — types/tests/flag_docs_generated.rs — that fails cargo test -p cratonvm-types when the checked-in table and the code disagree about which variables exist, or when the counts below do not describe the table.

Its three inputs are all in the tree:

Derivation rules, so a regenerated table matches this one:

• Shape — opt-in when only on_key is set, opt-out when only off_key is set, default-on when on_key carries an off_word, both when the knob has an explicit spelling in each direction, scalar for the five named scalars, group for the ten grouped variables.
• Default — off for opt-in/both, on for opt-out/default-on. This is the default of the canonical token, which is always stated positively. CRATONVM_MOVING_YOUNG_NO_JIT therefore appears as opt-out / on: the token is moving-young-jit-frames, that capability is on, and exporting the NO_ variable is what removes it.
• Class — diag for the DBG group, whose contract is that no token in it can change a program's result; behaviour for every other group. That is a contract, not a measurement: a flag that changes behaviour does not belong in DBG no matter how diagnostic its name sounds. (CRATONVM_DBG_GC_STRESS is the standing exception and is documented as such at GcFlags::gc_stress_bytes — it changes GC scheduling.)
• Latched — snapshot for every declared name, live getenv for the allowlisted ones. See the next section for why this column is the interesting one.
• Read in — crates whose src/ contains the name as an exact string literal, outside a whole-line comment. types/src/flag_groups.rs is excluded: the registry names every variable, and that is a declaration, not a read.

Three tests keep the inputs honest, and all three are cargo test -p cratonvm-types:

tools/flag-census/check-surface.sh is the CI-side companion.

---

Where the surface stands

Read-path split, over <crate>/src only:

The 421 already resolve against the snapshot. The 38 CratonVM ones do not, and they are what the migration plan is about. The 3 non-CratonVM reads are semantically correct where they sit, but they still trip check-surface.sh check 4, which bans the call shape rather than the flag — see Open reconciliation items.

---

Latching, and why an undeclared flag is a test hazard

flags::runtime_var is a fork in the road:

if declared_flag_names().contains(name) {
    return flags().legacy_var_os(name);   // the latched snapshot
}
std::env::var(key)                        // live getenv

So a variable's declaration status silently decides its semantics:

The third row is the one that costs debugging days.

Suppose a test wants a flag on. The supported way to do that is with_thread_overrides(&[("CRATONVM_X", Some("1"))], || …), which builds a VmFlags and installs it for the calling thread. If CRATONVM_X is declared this works: the reader calls runtime_var, runtime_var consults flags(), flags() returns the override. If CRATONVM_X is undeclared the override is built and installed and then completely ignored — the reader falls through to std::env, which the override never touched. The test does not fail; it measures whatever the developer's shell happened to export. Worse, the whole class of "flag off" assertions passes vacuously on a clean machine and starts failing on a CI runner that inherits the variable, which reads as a flake.

The mirror-image defect — set_var on a flag that is declared — has the same shape and is already written up: libcratonvm-no-jdk-test-order-dependent-fixed-20260730.md. flag_env_mutation_guard.rs catches that one. flag_declaration_guard.rs, added in this pass, catches this one.

There is a second, quieter consequence. flags() latches on first use, and the first use is whatever runs earliest — types::field_layout's compact-reference decision, native_io's deployment profile, classloading's classpath setup. An undeclared flag read after that point sees a different world from every declared flag around it, which is exactly the kind of "these two gates disagree" bug the CRATONVM_JIT_MY_SHADOW_EMISSION note in jit::x64::licm warns about: emission and root-scan are two halves of one agreement, and a flag that reaches only one half is a collector walking a shadow stack the codegen never pushed to.

---

What was declared in this pass

71 variables, 71 new tokens, no change to any observable default. Every entry below was read against its call site before being written down; the Parser column names the exact idiom at that site.

Eight of the 71 were not in the original brief and were found by running the new guard while writing this document: CRATONVM_JIT_VERIFY_MEMORY_CHAIN, CRATONVM_JIT_VERIFY_ARENA_ORDER and CRATONVM_DBG_IR_SLOTS arrived from a concurrent jit change, and CRATONVM_GPU_CRITICAL_WAIT_MS / CRATONVM_GPU_CRITICAL_LEASE_MS from a concurrent cuda-bridge change, and CRATONVM_PHASE_ACCOUNTING / _OUT / _JFR from a concurrent jfr change — all within the same session. That rate — eight new undeclared flags in one afternoon on one branch — is the argument for the guard being a test rather than a convention.

JIT IR verifier — jit/src/ir_verify.rs

CRATONVM_JIT_VERIFY_IR is the only genuinely tri-state knob in the table and the reason parse::tristate_word exists:

• unset — the per-pass verifier follows cfg!(debug_assertions), and the unconditional pre-lowering check stays on;
• 1 — the per-pass verifier runs in a release build too;
• 0 — the per-pass verifier is off and pre_lower_verify_disabled fires, which is the operator's escape hatch from a verifier false positive costing them the entire optimizing tier.

Collapsing that into a bool at the parse boundary would lose the third state. The off_word: Some("0") on the inventory row is what lets CRATONVM_JIT=-verify-ir reach it, rather than merely unsetting the variable back to the profile default.

The last two rows landed mid-pass: a concurrent change split the old check_schedule lane in two and added CRATONVM_DBG_IR_SLOTS. They were caught by running the new guard, which is the argument for the guard.

JIT metrics — jit/src/metrics.rs

_OUT treats an exported-but-empty value as "no sink", and _RING=0 falls back rather than being honoured — a ring of zero would make last_compilation_report permanently None, which is never what an operator means. Both are preserved in JitMetricsConfig. The 256 itself stays in jit: it is a tuning constant of the ring, not of the environment, so ring_capacity_or(default) takes it.

Other JIT / execution-engine knobs

CRATONVM_DBG_IR_BAILOUT, CRATONVM_DBG_IR_COMPILES, CRATONVM_DBG_IR_RELOC, CRATONVM_DBG_IR_SLOTS, CRATONVM_DBG_EXCFRAME, CRATONVM_DBG_JIT_CODE_FREE, CRATONVM_DBG_JIT_PIN, CRATONVM_DBG_JIT_STALE_IC, CRATONVM_DBG_JIT_UNMAP, CRATONVM_DBG_DEOPTSLOT, CRATONVM_DBG_DISPATCH_TALLY, CRATONVM_DBG_ROOTSNAP_EVERY, CRATONVM_DBG_ROOTSNAP_VERIFY — diagnostics, all default-off, all DBG tokens.

Behaviour-changing, and five of them default ON — worth stating because the name does not say so:

CRATONVM_JIT_STRICT_CALLEE_ROOTS deserves the bold: its own doc comment describes it as something you turn on with =1, but the code is .unwrap_or(true) — it is on unless you turn it off. The declaration follows the code, and this line exists so the next reader does not have to re-derive it.

The three moving-young bisect levers — CRATONVM_JIT_MY_SCRATCH_FLUSH, CRATONVM_JIT_MY_SELFCALL_PROOF, CRATONVM_JIT_MY_SHADOW_EMISSION — are also default-on. MY_SHADOW_EMISSION is read in two crates (jit::x64::licm and vm::jit::conservative_roots) with a byte-identical expression, on purpose: they are two halves of one agreement. One declaration now covers both halves.

Remaining JIT rows: CRATONVM_JIT_FORCE_C2, CRATONVM_JIT_LEAK_CODE, CRATONVM_JIT_NEVER_FREE_CODE, CRATONVM_JIT_POISON_FREE, CRATONVM_JIT_OSR_DEAD_MASK_BLANKET (opt-in); CRATONVM_JIT_NO_EXC_TABLE_C2, CRATONVM_NO_JIT_PRECISE_HANDLER_FRAMES, CRATONVM_NO_JIT_TLAB_ZERO_ELISION (opt-out spellings, stated positively as exc-table-c2, precise-handler-frames, tlab-zero-elision); CRATONVM_JIT_PUTFIELD_INIT and CRATONVM_TRIVIAL_GETTER (default-on kill switches); CRATONVM_TRIVIAL_GETTER_VERIFY (diagnostic).

GC — gc/src/gc_metrics.rs, gc/src/vm_heap.rs, gc/src/gen_heap.rs

CRATONVM_GC_CARD_METRICS is a presence check, so CRATONVM_GC_CARD_METRICS=0 enables it. That is what the code does today and the declaration preserves it; it is called out in GcMetricsConfig::card_metrics and pinned by a test, so that nobody "fixes" it without measuring. The gate sits on a barrier that runs on every reference store, so the thread-local byte in gc_metrics stays in front of the snapshot read — only the cold resolve step consults the config.

GPU critical sections — cuda-bridge/src/critical.rs

Filed under GC because that is where gpu-zerocopy already is, and because these budgets are what bound a collector's wait on a GPU critical section.

Both are read by resolve_ms, which takes the variable name as an argument and calls std::env::var on it. That shape is doubly outside the boundary: it bypasses the snapshot, and because the name is not a literal it is invisible to flag_declaration_guard.rs and to check-surface.sh. These two were found by reading the file, not by the guard. Declaring them fixes the reachability half; Stage 1 of the migration fixes the read.

Phase accounting — jfr/src/phase.rs

Already read through runtime_var_os and already named by pub const FLAG_* items, so declaring them costs nothing and buys CRATONVM_DBG=phase-accounting=fine. The enable gate is the fourth distinct "level word" parser in the tree and is deliberately left in jfr — a Level enum is that crate's vocabulary, and the typed config's job is to hand it the string, not to learn its grammar.

Threading — vm/src/threading/thread_state.rs

CRATONVM_STRESS_THREAD_STATES → THREADS=stress-thread-states, tri-state, off_word: "0". Unset follows the build profile; 0/false/off stands the tripwire down even in a debug build (the bisection escape hatch for a wrong entry in the legality table itself); anything else arms it. Note the parser is not the same tri-state as the JIT one: here an unrecognised word means on, because the read site is Ok(_) => true. Hence two parsers, tristate_word and tristate_off_word, rather than one that is subtly wrong for one of them.

Arming the checks and making a violation fatal are the same variable but not the same predicate — a debug build reports without aborting. ThreadStressConfig keeps those as two accessors so the asymmetry cannot be flattened by accident.

Capabilities — native-api/src/capability.rs

The mode word and the grant list stay unparsed in CapabilityConfig. CapabilityMode::parse accepts operator aliases and prints a stderr warning for an unrecognised word; that diagnostic belongs to native-api, and pushing the parse down into types would either duplicate the alias table or move a user-facing message into a crate with no business printing one.

One sharp edge, recorded at the inventory rows: CRATONVM_SECURITY=all writes 1 into every token in the group, and CapabilityMode::parse("1") is Enforce. all is not a safe way to "turn on the diagnostics" in this group.

Class loading, natives, compatibility

Plus the diagnostics CRATONVM_DBG_CLASS_RESOURCE, CRATONVM_DBG_CLINIT_FAIL, CRATONVM_DBG_JUL, CRATONVM_DBG_LINKAGE_BT, CRATONVM_DBG_LOADER_CHAIN, CRATONVM_DBG_MAPPER, CRATONVM_DBG_RTERR, CRATONVM_DBG_SETACC, CRATONVM_DBG_STAMPED, CRATONVM_DBG_STUB_BT, CRATONVM_DBG_STUBLOADER, CRATONVM_DBG_AIO_INLINE.

CRATONVM_ALLOW_NONCRYPTO_SSLENGINE is worth one extra line: it was the only undeclared flag in this batch that weakens a security control, and it was reachable neither from CRATONVM_SECURITY=… nor from any test override.

---

The typed configuration

types/src/subsystem_config.rs — SubsystemConfig, reached as flags().subsystems or through the free accessors subsystem_config::{jit_verify, jit_metrics, gc_metrics, thread_stress, capability}.

SubsystemConfig
├── jit_verify     : JitVerifyConfig     verify_ir: Option<bool>, 5 lane flags
├── jit_metrics    : JitMetricsConfig    enabled, out_path: Option<OsString>,
│                                        ring_capacity: Option<usize>
├── gc_metrics     : GcMetricsConfig     card_metrics
├── thread_stress  : ThreadStressConfig  thread_states: Option<bool>
└── capability     : CapabilityConfig    mode / grants (raw), log_first_use

Three properties this design is holding on to:

• One snapshot. SubsystemConfig is a field of VmFlags, so it is filled by the same single walk of environ, latched by the same OnceLock, and reached by the same with_thread_overrides. A separate OnceLock here would be a second thing to fall out of step with the first, which is the defect the whole refactor is undoing.
• Additive. Nothing was moved or renamed. Every runtime_var / runtime_var_os call site keeps working unchanged, so call sites can migrate one at a time and nothing outside types/ has to change in lockstep.
• The build profile is an argument, not a cfg!. per_pass_enabled(debug_build) and checks_enabled(debug_build) take the caller's profile rather than evaluating cfg!(debug_assertions) inside types. types can be compiled under a different profile than jit or vm, and silently answering for the wrong one is precisely the class of divergence this exists to remove.

---

Migration plan

Ordered so that each step is independently landable and independently revertible, and so the two steps that change behaviour come first and separately.

Stage 1 — the 17 direct std::env reads in runtime crates (behaviour fix)

These bypass the snapshot entirely, so they are invisible to the override hooks and to CRATONVM_<GROUP>=…. Each is a one-line change from std::env::var[_os] to cratonvm_types::flags::runtime_var[_os]; the parse around it does not move. tools/flag-census/check-surface.sh check 4 already bans these, and is currently red because of them.

Rows 6 and 7 are the interesting ones: those flags were already declared, so a test arranging them through with_thread_overrides was already silently ineffective. Nothing about the declaration protects a call site that does not use the boundary.

Row 14 is the only one that takes more than a word change: resolve_ms receives the variable name as a &str parameter, so the swap is std::env::var(var) → cratonvm_types::flags::runtime_var(var) — one token, but it also removes the last CratonVM read in the tree that no static scan can see.

Stage 2 — the launcher, vm-cli/src/main.rs (20 sites)

All 20 name declared flags and all 20 read std::env directly. CRATONVM_DBG_ARGS alone accounts for 7. This is a lower-severity group — the launcher runs before the snapshot latches and calls flag_groups::expand_process_env — but "reads the same variable twice through two different mechanisms" is how the three-way CRATONVM_LOADER_AWARE_RESOLUTION split happened. Convert wholesale in one commit, after Stage 1 so a bisect can tell the two apart.

Stage 3 — the five subsystems, onto the typed config

Purely a typing change: these already read through runtime_var[_os], so the value they see does not move. Do them one subsystem per commit, smallest first.

Steps 4 and 5 delete the two duplicated env_flag helpers. They are today byte-identical copies of each other and of parse::tristate_word, kept apart by a comment explaining that the two modules must be able to disagree about defaults — which they still can, because the default is applied at the accessor (per_pass_enabled(debug_build) vs unwrap_or(false)), not at the parse.

Stage 4 — the long tail

421 runtime_var[_os] sites remain, ~90 of them memoised on top by vm/src/runtime/env_cache.rs. These are correct as they stand: they resolve against the snapshot, they honour the override hooks via MemoSlot, and the memo layer is load-bearing for interpreter throughput (MemoSlot's doc records +1.15% of execute_instruction for the naive alternative). Migrate opportunistically, when a flag is being touched for another reason and its bool is hiding structure. Do not do it as a sweep: the win is typing, and the risk is a per-bytecode read that got slower.

---

The allowlist, and why each row is on it

types/tests/flag_declaration_guard.rs fails the build when a CRATONVM_* string literal appears anywhere in the workspace without a declaration. Eleven names are exempt. Every row carries a reason string, and the_allowlist_has_no_dead_rows deletes the possibility of a row outliving its call site — an allowlist nobody prunes is how the previous surface reached 692 names.

Three kinds, and nothing else qualifies:

Kind 1 — not an environment variable at all.

Kind 2 — deliberate "this variable does not exist" probes.

Kind 3 — test-harness and build-script knobs no production code reads. These are read before or outside a VM, where no snapshot exists and live std::env semantics are the correct ones. Declaring them would put harness plumbing into docs/CONFIG.md and into CRATONVM_TEST=…, which is the surface growth this exercise is undoing.

A flag read by anything under a crate's src/ does not qualify. If a row is added, the reason has to say why the snapshot cannot serve that call site; "it was easier" is not a reason.

How the scanner stays precise

Only an exact whole-string literal counts — the closing quote must follow the name immediately. That is what keeps the guard off b"CRATONVM_MODULES_MARKER\n" (a file's contents), "[CRATONVM_STREAM_PIN_CANARY] {site}: …" (a log tag), and "CRATONVM_DBG=jit-method-stats" (advice telling an operator what to export). Whole-line comments are skipped, so the hundreds of /// CRATONVM_X=1 does … doc comments cost nothing.

One trap, found while writing the guard and now pinned by a unit test: the obvious spelling of "is this a block-comment continuation" is line.trim_start().starts_with('*'), and it is wrong. This tree is full of *ON.get_or_init(|| std::env::var("CRATONVM_…")), and that rule swallows every one — a guard that skips exactly the once-cached flag reads it exists to find. The rule is "* ", "*/", or a bare * instead.

Known blind spot, stated rather than papered over: a name assembled at runtime (format!("CRATONVM_REAL_{sub}")) cannot be judged statically. The same caveat applies to flag_env_mutation_guard.rs.

---

Open reconciliation items

1. tools/flag-census/check-surface.sh needs one exemption. Its check 1 excludes CRATONVM_(NONEXISTENT_VAR_12345|SOMETHING_BRAND_NEW|FOO). After this pass the only remaining undeclared literal under a crate src/ is CRATONVM_COMPATIBILITY_JDK_ONLY at libcratonvm/src/lib.rs, which is an ABI constant name inside an assertion. Add it to that grep -vxE alternation.
2. check-surface.sh check 4 is red — 17 direct std::env::var[_os] calls on CRATONVM_* literals in core runtime crates, plus three on non-CratonVM names (HOME in native-awt, JBOSS_HOME in native-builtins, a dynamic key in vm/src/config.rs). Stage 1 fixes the 17. The three others are correct — an OS variable should keep live semantics — but check 4 bans the call shape, not the flag, so they need either a routing through runtime_var_os (which passes non-declared names straight through, so it is behaviour-neutral) or an explicit exemption in the script. Routing is the better answer: it makes the boundary the only door.
3. docs/CONFIG.md and docs/flag-tokens.md do not yet list the 71 new tokens. check-surface.sh check 2 only fails when the docs name a token the inventory lacks, not the reverse, so this is not blocking — but the documented surface is now 71 tokens behind the code.
4. Two env_flag helpers survive in jit/src/ir_verify.rs and jit/src/metrics.rs. They are byte-identical to each other and to parse::tristate_word. Stage 3 steps 4–5 remove them.
5. jit/, vm/, cuda-bridge/ and jfr/ were changing while this inventory was taken. Eight variables appeared mid-pass and are declared: CRATONVM_JIT_VERIFY_MEMORY_CHAIN, CRATONVM_JIT_VERIFY_ARENA_ORDER, CRATONVM_DBG_IR_SLOTS, CRATONVM_GPU_CRITICAL_WAIT_MS, CRATONVM_GPU_CRITICAL_LEASE_MS, CRATONVM_PHASE_ACCOUNTING, CRATONVM_PHASE_ACCOUNTING_OUT, CRATONVM_PHASE_ACCOUNTING_JFR. Line numbers in this document will drift; the file and function names will not. Re-run cargo test -p cratonvm-types --test flag_declaration_guard after merging — it is the cheapest way to find what landed in the meantime.
6. types/src/subsystem_config.rs models jit::ir_verify as it stood at the end of this pass, including the check_schedule → check_memory_chain + check_arena_order split. If jit moves again before the migration lands, reconcile JitVerifyConfig against VerifyOptions::from_env — the two must agree field for field or Stage 3 step 5 will silently change which lanes run.

---

Full inventory

990 rows: 979 declared, 11 allowlisted. Generated by tools/flag-census/render-inventory.py — see How to regenerate.