Module env 

Serialized BuildEnvironment — the persistent build-state record that mirrors Sphinx’s BuildEnvironment (environment/__init__.py), scoped to the fields this wave’s read-and-resolve phase populates (see docs/superpowers/plans/2026-08-31-m2-wave4-research-spec-sphinx-env-toctree-domains.md §1 for the full attribute-by-attribute mapping this struct is drawn from).

Persisted as bincode (bincode::serde + bincode::config::standard(), the same config crate::doctree::to_bincode/from_bincode use) to <cache_dir>/env.bin. That file lives inside the cache directory governed by the .config-fingerprint wipe protocol in src/cache.rs: a change to a content-bearing configuration value nukes the whole cache dir, env.bin included — which is the desired behavior, since the environment was built under the old configuration. Note that this is broader than Sphinx, which only invalidates its environment for config values with rebuild class 'env' and never deletes its doctrees; the filter in builder::EXCLUDED_FROM_FINGERPRINT keeps at least the purely operational flags (-W, -n) from triggering it.

Every collection here is a BTreeMap/BTreeSet rather than the Hash* equivalent so that bincode bytes and BuildEnvironment::snapshot output are deterministic across runs and processes.

Re-exports

pub use py_domain::PyDomainData;

pub use std_domain::StdDomainData;

Modules

dependencies

env.dependencies[docname] — the files a document is built from besides its own source, and the reason a build re-reads a document whose source never changed.

genindex

The index domain and the general index it feeds: Sphinx’s IndexDomain (domains/index.py) collection half, and IndexEntries.create_index (environment/adapters/indexentries.py:54-197) — the assembly half that turns the collected 5-tuples into the grouped, sorted structure genindex.html renders.

metadata

env.metadata[docname] — the document’s bibliographic field list, read as build metadata.

numbers

Section and figure numbering: TocTreeCollector.assign_section_numbers and assign_figure_numbers (sphinx/environment/collectors/toctree.py:197-378), the two halves of get_updated_docs the resolve phase runs once every document’s toc is in the environment.

objects

The domains’ get_objects() (domains/__init__.py:285): every object a domain exposes to the object inventory (objects.inv) and the search index (searchindex.js), as the (name, dispname, type, docname, anchor, priority) rows Sphinx yields — plus the two per-type lookups both consumers share, the search priority (ObjType.attrs['searchprio']) and the localized type name (Domain.get_type_name).

py_domain

The py domain: object and module registration with Sphinx’s duplicate semantics — PythonDomain.note_object / note_module / clear_doc / merge_domaindata (sphinx/domains/python/__init__.py:780-832 and :744-757) — and the resolution half: find_obj / resolve_xref (:855-994) plus the builtin_resolver missing-reference listener (:1077-1098).

resolve

Cross-reference resolution: the std half of Sphinx’s ReferencesResolver post-transform (transforms/post_transforms/__init__.py:60-160) plus StandardDomain.resolve_xref (domains/std/__init__.py:1034-1293) and the dangling-reference warnings both of them can raise [ENV §4, §8 #4-#13].

std_domain

The std domain: cross-reference labels, glossary terms, program options and generic objects — Sphinx’s StandardDomain (domains/std/__init__.py).

toctree

Sphinx’s toctree bookkeeping: the read-phase half of sphinx/environment/collectors/toctree.py plus the two pieces of sphinx/directives/other.py and sphinx/environment/adapters/toctree.py that feed it.

Structs

BuildEnvironment

Persistent build-state record: the subset of Sphinx’s BuildEnvironment attributes this wave’s read-and-resolve phase populates. See the module doc comment for the persistence protocol.

FileTimes

What BuildEnvironment::get_outdated_files needs to know about the filesystem, as the three questions it actually asks — so the computation itself stays pure and the caller decides what “the source of docname” and “the doctree of docname” mean.

IndexEntryRecord

One entry harvested from a document’s index nodes, as recorded in Sphinx’s env.domaindata['index']['entries'][docname]. main mirrors Sphinx’s literal 'main'/'' marker string as a bool; BuildEnvironment::snapshot converts it back to that string form to match the oracle fixture shape.

Outdated

The three sets env.get_outdated_files splits the project into (environment/__init__.py:521-554).

Constants

ENV_VERSION

Bumped whenever the on-disk shape of BuildEnvironment changes. BuildEnvironment::load discards (returns None for) any file whose stored version doesn’t match current — mirroring Sphinx’s own ENV_VERSION check, where a stale environment is simply rebuilt from scratch rather than partially trusted.