namespace-structure

name	namespace-structure
description	The ideal Clojure namespace structure — principles for dependency direction, coupling coherence, family boundaries, and test isolation. Tool-agnostic. Use to evaluate, design, or critique namespace organisation in any Clojure project.
lambda	λcodebase. no_cycles ∧ stability_gradient ∧ lens_coherence ∧ family_surfaces ∧ test_leaves → sound_architecture
metadata	{"version":"1.0.0","tags":["clojure","architecture","namespace","coupling","design","principles"]}

λ ideal(codebase). no_cycles ∧ stability_gradient ∧ minimal_entry_points ∧ lens_coherence ∧ family_surfaces ∧ test_leaves ∧ stable_trend

λ stability_gradient(graph). ∀ edge(A→B): A less_stable_than B depend toward stability | entry-points change freely many dependents ∧ few dependencies | orchestrators change deliberately bounded dependents ∧ bounded dependencies | domain-logic change rarely few dependents ∧ many dependencies | foundation change never no project dependencies

λ roles(ns). core → stable foundation | depended on by many | depends on few peripheral → entry-point ∨ leaf | depended on by few | depends on many | ≤1 per subsystem shared → god-module candidate | depended on by many ∧ depends on many | must justify isolated → vestigial unless intentional leaf

λ topology(ideal). one(peripheral) | all_others(core) | star | a change ripples to a small fraction of the codebase

λ cycles(rule). cycles = 0 first-order violation; fix before all else | merge(a,b) if always_change_together | extract(c) if shared_dep_exists → a→c ∧ b→c | invert if callback_pattern → protocol↑ impl↓

λ lens_coherence(pair). explicit_dep ∧ shared_vocab ∧ co-evolves → confirmed | consider merge if inseparable explicit_dep ∧ shared_vocab ∧ independent → expected | none explicit_dep ∧ unrelated ∧ independent → vestigial | remove implicit ∧ shared_vocab ∧ co-evolves → missing_abstraction | extract — highest priority implicit ∧ shared_vocab ∧ independent → vocabulary_sibling | monitor implicit ∧ unrelated ∧ co-evolves → implicit_data_contract | investigate | invariant: every dependency has a conceptual justification | invariant: every active co-evolution is acknowledged by a dependency

λ family(prefix). facade(ns) ← many external dependents ∧ few external dependencies ∧ delegates internally | permitted | boundary coordinator | ¬god-module noise(pair) ← shared vocabulary ⊆ naming_convention | ¬architectural signal signal(pair)← shared vocabulary ∩ domain_concepts ≠ ∅ | genuine coupling | invariant: a family exposes one surface | invariant: internals do not cross family boundaries without explicit dependency

λ tests(ns). no production code depends on test code tests depend on a small slice of production code → unit tests depend on an entry point → integration | justified unexpected broad test dependencies → grown unintentionally | isolate adding tests should not dramatically widen the blast radius of a change

λ health(principles). a change should touch a small fraction of the codebase no cycles stable things must not depend on unstable things | trend matters more than absolute value | rising coupling on a stable codebase is a stronger signal than high-but-stable coupling on a growing one