# Strict Naming Conventions for the Lean Port **Status:** MANDATORY — Violations block commit. **Scope:** All code in `0-Core-Formalism/lean/Semantics/` and any shim that references Lean types. **Goal:** Eliminate naming whack-a-mole. One convention. No exceptions. --- ## 1. File Names ### 1.1 Lean Source Files - **Format:** `PascalCase.lean` - **Rule:** One module per file. The file name must exactly match the primary `namespace` or `module` exported. - **Examples:** - ✅ `Bind.lean` - ✅ `FixedPoint.lean` - ✅ `ParticleDomain.lean` - ❌ `bind_physics.lean` - ❌ `fixed_point.lean` ### 1.2 Directory Names - **Format:** `PascalCase/` - **Rule:** Directories are namespaces. They must match the namespace stem. - **Examples:** - ✅ `Semantics/Physics/` - ❌ `semantics/physics/` - ❌ `physics_semantics/` ### 1.3 Test Files - **Format:** `Tests.lean` (plural) inside the domain directory. - **Rule:** One test module per directory. No `TestFoo.lean` scattered around. - **Examples:** - ✅ `Semantics/Physics/Tests.lean` - ❌ `test_physics.lean` --- ## 2. Namespaces ### 2.1 Root Namespace - **Always:** `Semantics` - No exceptions. Every file opens with `namespace Semantics` or `namespace Semantics.`. ### 2.2 Domain Namespaces - **Format:** `Semantics.` - **Rule:** Domain names are singular nouns in PascalCase. - **Canonical domains:** - `Semantics.Physics` - `Semantics.Optimization` - `Semantics.Substrate` - `Semantics.Orchestrate` - `Diagnostics` (under `Semantics.Diagnostics`) ### 2.3 Sub-Domains - **Format:** `Semantics..` - **Example:** `Semantics.Physics.Boundary` (if needed, but prefer flat: `Semantics.Physics`) - **Rule:** Max 3 levels. `Semantics.Foo.Bar.Baz.Quux` is banned. --- ## 3. Type Names (structures, inductive types, type classes, abbreviations) ### 3.1 Structures - **Format:** `PascalCase` - **Rule:** Noun or noun phrase. Must describe *what it is*. - **Examples:** - ✅ `Bind` - ✅ `Metric` - ✅ `ParticleKind` - ✅ `ModelAddress` - ❌ `bindResult` - ❌ `particle_kind` ### 3.2 Inductive Types - **Format:** `PascalCase` - **Rule:** Constructors are `camelCase` unless they are atomic tokens, then `PascalCase`. - **Examples:** ```lean inductive QuantityKind | charge | mass | baryonNumber ``` - **Exception:** If constructors are proper names or acronyms, keep them readable: ```lean inductive GaugeBoson | photon | wPlus | z ``` ### 3.3 Type Classes - **Format:** `PascalCase` - **Rule:** Must end in a noun that describes the capability. - **Examples:** - ✅ `LawfulBind` - ✅ `ConservedQuantity` - ❌ `Bindable` - ❌ `Lawful` ### 3.4 Abbreviations (`abbrev`) - **Format:** `PascalCase` - **Rule:** Must be a genuine alias for a type, not a function. - **Examples:** - ✅ `abbrev Cost := UInt32` - ❌ `abbrev cost := UInt32` --- ## 4. Function and Definition Names ### 4.1 Pure Functions - **Format:** `camelCase` - **Rule:** Verb or verb phrase. Must describe *what it does*. - **Examples:** - ✅ `bind` - ✅ `particleInvariant` - ✅ `totalQuantity` - ✅ `geodesicCost` - ✅ `fromHistory` - ❌ `Particle_Invariant` - ❌ `get_total_quantity` ### 4.2 Predicates (return `Bool` or `Prop`) - **Format:** `camelCase`, but must read as a yes/no question. - **Examples:** - ✅ `isLawful` - ✅ `conserved` - ✅ `faithfulMeasurement` - ❌ `checkLawful` - ❌ `is_conserved` ### 4.3 Cost Functions - **Format:** `Cost` - **Rule:** Always end in `Cost`. Take a `Metric` as the final argument. - **Examples:** - ✅ `physicalCost` - ✅ `geodesicCost` - ✅ `thermodynamicCost` - ❌ `costPhysical` - ❌ `computeCost` ### 4.4 Invariant Functions - **Format:** `Invariant` - **Examples:** - ✅ `particleInvariant` - ✅ `canonicalInvariant` ### 4.5 Conversion Functions - **Format:** `To` - **Examples:** - ✅ `toAddress` - ✅ `toNat` - ✅ `toFloat` - ✅ `ofFloat` - ❌ `float_of_int` - ❌ `convertToNat` ### 4.6 Constants - **Format:** `lowerCamelCase` if computed, `UPPER_SNAKE_CASE` only for true mathematical constants. - **Examples:** - ✅ `maxParticleKinds` - ✅ `maxInteractionArity` - ✅ `phiRatio` (if computed) - ✅ `Q16_16_ONE` (if a true constant literal) --- ## 5. Theorem and Lemma Names ### 5.1 Theorems - **Format:** `lowerCamelCase` - **Rule:** State exactly what is proven. No `theorem_1`. No `lemma_foo`. - **Patterns:** - `Of`: `chargeConservedOfElectronPositron` - `Is`: `electronDomainIsFermion` - `Preserves`: `bindPreservesParticleInvariant` - `Holds`: `omegaAddressBounded` ### 5.2 Examples / `#eval` Test Functions - **Format:** `example` - **Examples:** - ✅ `examplePhysicalBind` - ✅ `exampleElectron` - ❌ `test_physical_bind` - ❌ `demoElectron` --- ## 6. Instance Names ### 6.1 Type Class Instances - **Format:** `lowerCamelCase`, derived from the type and class. - **Rule:** Must be explicit enough to avoid orphan/instance search confusion. - **Examples:** - ✅ `particleKindDecidableEq` - ✅ `conservedDecidable` - ❌ `inst1` - ❌ `decEq` --- ## 7. Field Names in Structures ### 7.1 Record Fields - **Format:** `camelCase` - **Rule:** Short but unambiguous. No abbreviations unless domain-standard. - **Examples:** ```lean structure Metric where cost : UInt32 tensor : String torsion : UInt32 reference : String historyLen : Nat ``` - **Banned:** `hist_len`, `ref_str`, `tens` --- ## 8. Fixed-Point (Q16.16) Naming ### 8.1 The Type - **Name:** `Q16_16` - **Rule:** Always written with underscore separator. Never `Q1616` or `FixedPoint`. ### 8.2 Operations - **Format:** Standard arithmetic names overloaded via `HAdd`, `HMul`, etc. when practical. - **Explicit functions:** `q16_16_` - **Examples:** - ✅ `Q16_16.add` - ✅ `Q16_16.sqrt` - ✅ `Q16_16.ofFloat` --- ## 9. FFI / Extraction / Shim Naming ### 9.1 Lean Functions Marked for Extraction - **Format:** Same as pure functions, but prefixed with `export_` if they are C FFI entry points. - **Examples:** - ✅ `export_bind_request` - ✅ `export_physical_cost` - ❌ `ffi_physical_cost` ### 9.2 JSON Request/Response Types (Lean side) - **Format:** `Request` / `Response` - **Examples:** - ✅ `BindRequest` - ✅ `BindResponse` - ❌ `Req` - ❌ `Resp` ### 9.3 Python Shim Classes - **Format:** `PascalCase`, matching the Lean structure name. - **Examples:** - ✅ `class BindResult:` - ✅ `class Metric:` - ❌ `class bind_result:` --- ## 10. Banned Patterns The following are **prohibited** and will be rejected in code review: | Banned Pattern | Why | Fix | |---|---|---| | `snake_case` in Lean file names | Breaks namespace conventions | `PascalCase.lean` | | `snake_case` in type names | Not idiomatic Lean | `PascalCase` | | `getFoo` / `setFoo` / `checkFoo` | Verbose Java-isms | `foo`, `fooWithBar`, `isFoo` | | `tmp`, `temp`, `x`, `y`, `z` as top-level names | Obfuscates intent | Descriptive names | | `util`, `helper`, `misc` namespaces | Dumping grounds | Delete or properly classify | | Numeric suffixes (`_v2`, `_2`, `_final`) | Version control exists | No suffixes | | Mixed abbreviations (`nbr`, `qty`, `inv`, `calc`) | Unreadable | Full words | | `Theorem` / `Lemma` prefixes on theorem names | Redundant | `lowerCamelCase` | | `test_` prefixes on `#eval` definitions | Not a test framework | `exampleFoo` | --- ## 11. Module Organization Invariants Every `PascalCase.lean` file must obey: 1. **One top-level `namespace Semantics.`** matching the file path. 2. **No `open` without explicit import** — list all imports at the top. 3. **No `partial` without a `#guard` proof of termination plan** in a comment. 4. **No `sorry` in committed code** — `sorry` is allowed only in feature branches with a `TODO(lean-port):` comment and a linked issue. 5. **Every `def` that computes a `cost` or `invariant` must have an `#eval` example or a theorem** in the same file or in `Tests.lean`. --- ## 12. Enforcement - `lake build` does not enforce naming, but **git hooks will**. - The `metafoam_pkg.py` `build` command will reject packages containing banned patterns. - Code review checklist for every PR: 1. All file names PascalCase? 2. All types PascalCase? 3. All functions camelCase? 4. All theorems descriptive lowerCamelCase? 5. No banned patterns? 6. Every `def` has a witness (`#eval` or theorem)? --- **Document ID:** LEAN_NAMING_CONVENTIONS **Version:** 1.0 **Effective Date:** 2026-04-14 **Governance:** Human architect (no exceptions)