Module environment 

The environment generator: docs/reference/environment.md from the env::var call sites, filtered through an explicit allow-list (D34).

Why an allow-list at all. The workspace contains both public process contracts and internal test-harness switches: ATUNE_BLESS_JOURNAL_GOLDEN regenerates a byte golden, ATUNE_NFS_* and ATUNE_CONC_* drive multi-process journal tests, ATUNE_SPIKE_SEED seeds the Oniro spike. A generator that published every call site would present golden-blessing switches as public API, and one that published a curated list would drift the first time a variable was added. D34’s answer is both halves at once, and it is fail-closed in both directions:

• a variable the code touches and env_public.toml does not classify is an error naming the file and line — it can be neither silently published nor silently omitted;
• a variable env_public.toml classifies and the code no longer touches is also an error, so the list cannot outlive what it describes.

Three registries, not one. §7 says “env::var call sites”, which turns out to be the smaller half of the surface. The most user-facing variables of all — ATUNE_STUDY, ATUNE_SEED, ATUNE_CHECKPOINT, ATUNE_PARAM_<name> — are the handshake atune writes for a trial’s child process, and atune never reads them: the user’s own script does. They are declared as pub const ENV_* in atune_core::exec, which is a registry with a doc comment on every entry, so this generator collects

1. const … : &str = "SHOUTY_NAME" declarations (the names atune publishes as API, and the description prose that already sits next to them),
2. env::var/env::var_os reads,
3. Command::env writes,

and requires every name from all three to be classified. A read whose variable cannot be determined statically — a helper that takes the key as an argument — is not silently skipped either: its file must be listed as [[opaque]] with a reason.

Macro bodies are walked too, which syn::visit does not do on its own: a macro carries a token stream rather than parsed syntax, so a read inside assert!(…) or println!(…) was invisible to all three registries and to the fail-closed rule that is the point of them (§1.3.152). A body that parses as an expression list is visited; one that does not is scanned as text and makes the file opaque if it names env::var at all.

Structs

AllowList 🔒

env_public.toml, parsed.

Environment

Generates the environment-variable reference page.

PublicEntry 🔒

One published variable.

Scan 🔒

One file’s call sites.

Surface 🔒

Everything the workspace says about environment variables.

Variable 🔒

One variable, and everything the code says about it.

Constants

ALLOW_LIST 🔒

The allow-list D34 requires.

GENERATOR 🔒

This generator’s name, for fail-closed error messages.

SCANNED 🔒

The directories scanned for call sites: every crate and every example.

Functions

array_of_tables 🔒

A top-level [[key]] array of tables, as key/value maps.

as_string 🔒

A TOML value as a string, or a fail-closed error.

description 🔒

A variable’s description, from the code where the code has one.

is_env_name 🔒

Does this string literal look like an environment variable’s name?

provenance 🔒

The sentence saying who sets a variable and who reads it.

render_page 🔒

Writes the page.

required_string 🔒

One required string field of an entry.

string_array 🔒

A top-level array of strings.

string_constants 🔒

Every const/static of type &str in a file, with its documentation.