# Clojure Language Specification — Front Matter

**Edition**: Draft 1 · **Describes**: Clojure 1.12 (reference) · **Status**: in progress

This document specifies the Clojure programming language independently of any
implementation. See `docs/rfc/0001-language-specification.md` for motivation,
process, and scope.

## 1. Conformance terminology

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY**
are to be interpreted as described in RFC 2119.

- A statement marked **MUST** is normative: a conforming implementation
  exhibits exactly this behavior, and the conformance suite tests it.
- **implementation-defined** marks behavior a conforming implementation must
  document but may choose (e.g. the concrete error type thrown where the
  reference throws a JVM exception class).
- **host-defined** marks behavior delegated to the host platform (e.g. what
  `slurp` accepts as a source).
- **⚠ reference-divergence** marks a place where this spec deliberately
  differs from observed reference behavior, with rationale; the reference
  behavior is always recorded alongside.

## 2. Classification of the core surface

Every `clojure.core` var carries exactly one classification (dashboard:
`coverage.md`):

| Class | Meaning | Spec treatment |
|---|---|---|
| **portable** | semantics independent of host | full normative entry (§9) |
| **host-dependent** | portable *interface*, host-defined behavior | interface entry; behavior host-defined |
| **JVM-specific** | meaningful only on the JVM | catalogued in Appendix; not specified |

Initial classifications are mechanical and reviewable; reclassification is an
ordinary spec change.

## 3. The normative entry format

Each special form (§3) and portable var (§9) is specified as:

```
### name                                 — since <version>
(signature ...)  (signature ...)

Semantics
  S1. <numbered normative statement, MUST/SHOULD/MAY>
  S2. ...
Edge cases
  E1. <nil / empty / bounds / wrong-type behavior — normative>
Errors
  X1. <what MUST throw; error TYPE is implementation-defined unless stated>
Examples
  <executable; verified against the reference; sourced from ClojureDocs
   where community-validated>
Conformance
  S1 → <suite>/<test id>; E1 → ...   (statements without a test: UNVERIFIED)
```

The **Conformance** field is load-bearing: every numbered statement names the
test(s) that verify it. A normative statement with no test is labeled
`UNVERIFIED` and is a defect in the spec.

## 4. Evidence and verification

Behavioral questions are settled in this order: differential testing against
the reference implementation → cross-dialect agreement in clojure-test-suite
→ ClojureDocs community examples (verified before inclusion) → reference
source (for intent). Conformance tests live in this repository
(`test/integration/conformance-test.janet` runs each assertion through three
independent execution paths) and in the cross-dialect clojure-test-suite.

## 5. Chapter plan

| § | File | Status |
|---|---|---|
| 1 | `01-evaluation.md` | planned |
| 2 | `02-reader.md` | planned (first: jank's reader corpus gives conformance shape) |
| 3 | `03-special-forms.md` | **exemplars written** (`if`, `let*`); catalog complete |
| 4 | `04-data-types.md` | planned (numeric-tower design note required) |
| 5 | `05-sequences.md` | planned (laziness contract from jolt Phase-5 work) |
| 6 | `06-namespaces-vars.md` | planned |
| 7 | `07-polymorphism.md` | planned |
| 8 | `08-macros.md` | planned |
| 9 | `09-core-library.md` | **exemplars written** (`first`, `reduce`, `parse-uuid`) |
| A | `coverage.md` | **generated** (regenerate: `python3 tools/spec_coverage.py`) |