Your platform team must decide what a compile-time expansion may read beyond the source it is given, so where do you draw the line?

## What the stage can reach A compile-time expansion is not a template engine reading a file. In most toolchains it is arbitrary code executing inside the build process, which means it can do whatever that process can do: read the clock, read environment variables, read files outside the module, open a socket, generate a random number. Some toolchains deliberately restrict the stage to an effect-free subset; others impose nothing. Knowing which kind you are in is the first question, because the second question -- what should it be allowed to do -- only has teeth if the answer is enforceable. The mechanical fact underneath the whole decision is simple: **whatever the stage reads is rendered into the artifact as a constant**, and the source then shows the call, not the value. ## Four things an undeclared read costs 1. **Reproducibility.** Two builds of identical source produce different artifacts. Every downstream comparison -- is this binary the one we reviewed, did this change actually change anything -- stops working. 2. **Caching and incremental builds.** A build system invalidates on inputs it was told about. An expansion that reads something undeclared produces stale output that nothing knows is stale, which surfaces as the worst class of bug: it works on one machine and fails on another, and a clean build fixes it until it does not. 3. **Auditability.** The artifact carries a value with no origin anywhere in the repository. A reader six months later can see the constant and cannot see where it came from, because the code that fetched it ran once, elsewhere, and left nothing behind. 4. **Supply chain.** Allowing a dependency's expansions means running that dependency's code on your build machine, with your builder's filesystem access, environment and credentials. This is a trust decision of the same weight as running its installation scripts, and it is usually made implicitly. ## The rule worth setting A defensible default, stated as a rule other teams can follow: - An expansion is a **pure function of its declared inputs**: the source fragment it receives, plus files that are checked in, version-pinned and declared to the build system. - **No clock, no environment, no network, no randomness** inside an expanding stage. - A genuine need for outside data goes to an **explicit generation step** whose output is written to disk, reviewed like source, and committed. - Exceptions exist but are **named, reviewed and few**, with the exceptional input declared to the build system so caching stays honest. ## What the rule costs | Situation | Under the rule | What the team gives up | |---|---|---| | Expansion derived from a checked-in description | Allowed as-is | Nothing | | Expansion needs data from a live service | Moved to a generation step | Convenience; gains a reviewable diff | | Expansion wants a build timestamp or identifier | Passed in as a declared input | Direct reads; gains cache correctness | | A dependency ships its own expansions | Reviewed and pinned | Speed of adoption | The honest cost is friction. A generation step is a pipeline someone maintains, its output is a diff someone reviews, and the loop from "the upstream description changed" to "the code changed" gets one step longer. Teams that skip the rule are not being reckless for no reason -- they are buying that step back. The judgment is whether reproducible, cacheable, auditable builds are worth a pipeline, and at more than a handful of engineers the answer is usually yes. ## Enforcing it - **Declare inputs explicitly** so the build system can invalidate correctly, and treat an undeclared input as a defect rather than a style preference. - **Run the same build twice in different environments and on different days**, then compare artifacts. A difference points straight at something a stage read that nobody declared. This is the cheapest detector there is. - **Sandbox where the toolchain allows it**, restricting what the stage may reach rather than relying on convention. - **Review what an expansion emits**, not only how it is called. A stage reading a value nobody declared looks perfectly ordinary at every call site. ## Where the line genuinely moves The rule is not universal. A single-maintainer tool with a five-second build and no external consumers pays a lot of process for benefits it will not feel. A platform whose artifacts are deployed by other teams, cached across a fleet and attested for provenance cannot function without it. State the rule at the level where the build is actually shared, and write down the escape hatch alongside it -- an unwritten exception path is what turns a good rule into one everyone quietly routes around.