Impact of marking a var private with ^:private on cross‑namespace usage in Clojure 1.12

In Clojure 1.12, marking a var with ^:private is a compile-time mechanism rather than a runtime access control. It prevents the symbol from being referenced in other namespaces during compilation, but it does not protect against code that has already been compiled or uses reflection.

Compile-time vs. Runtime Enforcement

Marking a var with ^:private guarantees that any attempt to reference that var from another namespace will trigger a CompilerException, provided the calling code is compiled or evaluated after the var is marked private. This enforcement applies regardless of whether the calling code is AOT-compiled or loaded dynamically, as the check occurs during the compilation phase.

Downstream Project Impact and Linkage

If a downstream project has already compiled against a public version of your library, switching to a private declaration will not cause linkage errors or silent failures at runtime immediately. Because Clojure resolves symbols to Var objects at compile time, the already-compiled bytecode holds a reference to the Var. The error will only manifest when:

• The downstream project is recompiled against the new version of the library.
• Someone attempts to evaluate new code that references the private symbol.
• The downstream project uses reflection to access the var (as private metadata only affects the compiler's resolution).

Clojure 1.12 vs. Older Versions and REPL

There are no known breaking differences in how Clojure 1.12 versus earlier releases treats the metadata of ^:private vars regarding tools.namespace or the REPL. The behavior remains consistent:

• When using tools.namespace/load-ns, existing compiled forms in other namespaces that reference the var will still function, but any new code evaluated referencing the private var will fail to compile.
• In the REPL, if you redefine a public var as private, any functions already defined in the REPL session that call that var will continue working, but the next evaluation of a function referencing it will throw a compiler error.

Assumptions and Uncertainty

This analysis assumes standard usage patterns—direct symbol resolution (e.g., (namespace/helper)). If consumers are using @reflection or the var-get function, the ^:private metadata will have no effect, as these methods bypass the compiler's namespace visibility checks.

Diagnostic Question: Are your downstream consumers using reflection or var-get to access these helper functions?