Can Clojure introduce a :public-only namespace declaration to enforce API boundaries?

Answer to the Question

At present Clojure has no language‑level :public-only namespace declaration. All vars, even those tagged ^:private by defn-, remain reachable through fully‑qualified symbols or deref from any namespace. Therefore a compiler‑enforced API boundary cannot be introduced without significant changes to the language runtime.

Confirmed Facts

• Defining a function with defn- attaches ^:private metadata, but this is only advisory.
• Cross‑namespace calls to a private var succeed at runtime; the compiler emits no error.
• Tooling such as clj-kondo offers a :private-call lint rule that can warn about such calls, but it is optional and does not enforce them.
• Introducing a :public-only option would require the compiler to record a namespace’s public surface and reject any implicit resolution of a private var from outside that namespace.
• Such a change would break common patterns that rely on introspecting or calling private vars for testing, profiling, or framework extensions, so an opt‑in or gradual migration path would be essential.

Likely Explanation – What Would Be Needed?

• Compiler Extension: A new namespace option, e.g. (ns my.ns (:public-only true)), would need to be added and documented.
• Resolution Rules: During symbol resolution the compiler would check the referenced var against the declared public surface and emit an error if it is private and the caller is from a different namespace.
• Runtime Support: Dynamic references (e.g. (var-get (resolve 'my.ns/priv-fn))) would also need to be guarded, which could affect existing code that uses reflection or macro expansion.
• Tooling Updates: Lint tools would have to understand the new declaration and provide warnings or errors accordingly.
• Migration Path: Libraries could opt‑in by adding the declaration and refactoring tests to use public wrappers instead of direct private calls.

Practical Take‑aways

• Use clj-kondo with the :private-call rule to surface accidental private usage in your codebase.
• When you need to expose internal helpers, prefer a public wrapper that calls the private implementation.
• Document the intended public API surface clearly so developers know which vars are internal.
• If you plan to adopt a future :public-only feature, keep your codebase clean from direct private calls to avoid migration friction.

What We Still Need to Know

If you require enforcement at compile time, runtime, or both, that would influence the complexity of the proposed changes. Clarifying that would help refine the recommendation.