simon/jolt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
jolt/docs/spec
History
Yogthos d21ab77e7e Run core.memoize's test suite on jolt 
Shaking out clojure.core.memoize (207 assertions, 0 fail) cleared several
general gaps:

- deref/@ on a deftype or reify implementing clojure.lang.IDeref dispatches to
  its deref method (RetryingDelay / make-derefable).
- deftype mutable fields (^:unsynchronized-mutable / ^:volatile-mutable) are
  read live: a set! within a method is observed by a later read in the same
  invocation, not the entry-time capture. Needed for double-checked locking.
  Immutable fields stay let-bound. Field reads rewrite to (.-field inst) with
  lexical-shadow tracking.
- def metadata values are evaluated, like Clojure: ^{:k (f)} stores (f)'s
  result and ^{:af some-fn} the fn. :tag stays a literal hint.
- try dispatches catch clauses by class in order via the exception supertype
  hierarchy; a non-matching value re-throws, an untyped host condition is caught
  by a RuntimeException/Exception/Throwable clause. Previously the last clause
  won and the class was ignored.
- locking takes a real per-object monitor (recursive Chez mutex) now that
  futures/agents/threads share one heap; it was a no-op.
- supers/ancestors reflect a small modeled JVM interface hierarchy, so
  (ancestors (class f)) yields Runnable/Callable (core.memoize's arg check).
- AssertionError / Error constructors.

JOLT_FEATURES is gone from the docs: it isn't read anywhere on Chez, and the
reader already includes :clj in its default feature set. RFC 0002's
{:jolt :default} design was reverted in the reader; docs now match the code.

Raises the SCI floor 205 -> 210.
2026-06-25 13:23:05 -04:00
..
00-front-matter.md Docs: Chez-only, drop the Janet-era references and obsolete migration notes 2026-06-22 09:05:35 -04:00
02-reader.md Run core.memoize's test suite on jolt 2026-06-25 13:23:05 -04:00
03-special-forms.md spec: set! now supports deftype mutable fields 2026-06-22 01:19:21 -04:00
09-core-library.md docs: language specification RFC + spec skeleton with normative exemplars 2026-06-10 10:53:44 -04:00
coverage.md Clean up codebase: rename stdlib layer, strip porting residue, fix tooling 2026-06-22 22:18:00 -04:00
README.md Clean up codebase: rename stdlib layer, strip porting residue, fix tooling 2026-06-22 22:18:00 -04:00

README.md

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.

Documents

Doc Content Status
00-front-matter.md conformance terms, entry format, host classification drafted
02-reader.md token grammar + reader-macro catalog drafted
01, 04–08 see chapter plan in front matter planned
03-special-forms.md special-form catalog + normative exemplars (if, let*) exemplars
09-core-library.md per-var entry format + exemplars (first, reduce, parse-uuid) exemplars
coverage.md generated dashboard over the 694-var surface generated
../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.