33eff7c7d8
Rename src/jolt -> stdlib (the runtime-loaded layer; jolt-core stays the seed-baked layer) and update the loader / emit-image / doc paths. Drop dead code: the spike/ experiments, the duplicate clojuredocs-export.edn (json moves to tools/), the Janet-era jolt.http binding, and the orphaned persistent_vector.clj whose ns/path didn't even match. Strip porting residue from comments and docstrings across host/chez, jolt-core, stdlib, tests, and docs: internal issue ids, "Phase N" markers, and the "vs Janet" historical exposition, leaving present-tense descriptions and the real JVM-Clojure semantic contrasts. Same pass over the corpus suite labels. The seed is unchanged (docstrings/comments aren't emitted), so the self-host fixpoint and corpus are untouched. Port tools/spec_coverage.py off the dead janet probe to bin/joltc and regenerate coverage.md; drop the dead :host/janet rule from certify.clj and regenerate the conformance profile. Add docs/host-interop.md (the JVM shims and how to register your own host class from a library) and a writing-style note in CLAUDE.md. Stabilize the four racy concurrency corpus cases (future-cancel and agent send/send-off): give the future a sleeping body and the agent a slow action, so cancel reliably catches an in-flight future and deref reliably reads the pre-update snapshot. They certify deterministically now, so drop their :flaky allowlist entries and the orphaned legend.
55 lines
3 KiB
Markdown
55 lines
3 KiB
Markdown
# The Clojure Language Specification (Draft)
|
||
|
||
A normative, implementation-independent specification of the Clojure
|
||
language, developed alongside jolt's self-hosted compiler and validated by
|
||
its executable conformance suites. **Why**: Clojure has no spec — every
|
||
alternative implementation re-derives semantics from the reference
|
||
implementation and folklore. See the RFC for motivation, scope, evidence
|
||
sources, and process: [`../rfc/0001-language-specification.md`](../rfc/0001-language-specification.md).
|
||
|
||
## Documents
|
||
|
||
| Doc | Content | Status |
|
||
|---|---|---|
|
||
| [`00-front-matter.md`](00-front-matter.md) | conformance terms, entry format, host classification | drafted |
|
||
| [`02-reader.md`](02-reader.md) | token grammar + reader-macro catalog | drafted |
|
||
| `01`, `04`–`08` | see chapter plan in front matter | planned |
|
||
| [`03-special-forms.md`](03-special-forms.md) | special-form catalog + normative exemplars (`if`, `let*`) | exemplars |
|
||
| [`09-core-library.md`](09-core-library.md) | per-var entry format + exemplars (`first`, `reduce`, `parse-uuid`) | exemplars |
|
||
| [`coverage.md`](coverage.md) | generated dashboard over the 694-var surface | generated |
|
||
| [`../grammar.ebnf`](../grammar.ebnf) | reader surface syntax (EBNF), companion to `02-reader.md` | reference |
|
||
|
||
Regenerate the dashboard after surface changes:
|
||
`python3 tools/spec_coverage.py` (reads `tools/clojuredocs-export.json` and
|
||
probes a working jolt checkout via `bin/joltc`).
|
||
|
||
## Current numbers (2026-06-22)
|
||
|
||
Of the 694 `clojure.core` vars in the ClojureDocs inventory, jolt interns 574.
|
||
Broadly:
|
||
|
||
- **568** implemented in jolt *and* exercised by the behavioral suites
|
||
- **6** implemented but not directly tested — each gets a test with its spec entry
|
||
- **6** portable but absent from jolt's resolvable surface (the REPL history
|
||
vars `*1`/`*2`/`*3`/`*e`, plus `letfn`/`re-groups`, which work but aren't
|
||
interned where `resolve` can see them) — tracked as gaps
|
||
- the rest classified host/JVM/concurrency (see the dashboard for the full
|
||
per-var breakdown — it is the source of truth)
|
||
|
||
## How this connects to the test suites
|
||
|
||
- `test/chez/corpus.edn` — the host-neutral behavioral corpus, one row per
|
||
case (`{:suite :label :expected :actual}`). The Chez compiler evaluates each
|
||
case via `host/chez/run-corpus.ss` (run with `make corpus`), and
|
||
`test/conformance/certify.clj` certifies every `:expected` against reference
|
||
JVM Clojure (run with `make certify`). Spec entries cite these cases.
|
||
- `test/conformance/` — the certification tooling and classified divergences
|
||
(`certify.clj`, `known-divergences.edn`); see its `README.md` and `SPEC.md`.
|
||
- `vendor/clojure-test-suite` — the cross-dialect suite (≥4081 assertions
|
||
passing); dialect splits there are classification evidence.
|
||
- jank's per-construct corpus (`~/src/jank/compiler+runtime/test/jank`) is
|
||
the granularity model for §2/§3 conformance.
|
||
|
||
The invariant: **every numbered normative statement names its conformance
|
||
test**, or is marked UNVERIFIED. The spec cannot drift from the
|
||
implementations that check it.
|