simon/jolt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
jolt/docs/spec
History
Yogthos 45876998ad Docs: Chez-only, drop the Janet-era references and obsolete migration notes 
Bring the docs in line with the actual implementation now that Chez is the sole
substrate.

Deleted the migration/spike/handoff artifacts that only documented the Janet
era or the port effort: the port plan, phase-0 and foundational-runtime spike
writeups (+ the stray root-level copy), the self-hosting design notes, the
architecture-refactor plan, and spike/chez/RESULTS.md.

Rewrote the current reference docs against the Chez facts: building-and-deps and
tools-deps (no jpm/build step — bin/joltc off the checked-in seed, deps via
jolt.deps into ~/.jolt/gitlibs), libraries (SQLite is built-in jdbc.core over
libsqlite3, not a Janet driver), the conformance/spec test-flow docs (the Chez
corpus runner + certify, no .janet harnesses), and the transient / type-hint /
seed-overlay design notes (Chez representations: mutable transients, flat
copy-on-write vectors, HAMT maps, the seed/overlay twin). Fixed the README
collections line (vectors aren't 32-way tries) and added the ffi/transient gate
targets. rfc 0001's numerics open-question is resolved (the Scheme tower).

Renamed the built-in HTTP adapter to jolt.http.server only (dropped the
ring-janet.adapter alias — a Janet-era name).
2026-06-22 09:05:35 -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 spec/ebnf: macroexpand order, set!, letfn primitive, numeric tower 2026-06-22 01:03:48 -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 core: one alias store (jolt-ark); '.' classified as the special form it is 2026-06-10 18:37:19 -04:00
README.md Docs: Chez-only, drop the Janet-era references and obsolete migration notes 2026-06-22 09:05:35 -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
01-evaluation.md … 08-macros.md 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

Regenerate the dashboard after surface changes: python3 tools/spec_coverage.py (requires clojuredocs-export.json in the repo root and a working jolt checkout).

Current numbers (2026-06-10)

Of the 694 clojure.core vars in the ClojureDocs inventory:

  • 380 implemented in jolt and exercised by the behavioral suites
  • 154 implemented but not directly tested — each gets a test with its spec entry
  • 35 portable but missing from jolt (parse-long/parse-double/ parse-boolean, update-keys/update-vals, macroexpand, time, partitionv/partitionv-all/splitv-at, with-redefs, with-open, reader fns, ns-introspection stragglers, …) — tracked as implementation gaps
  • 22 resolvable in code but invisible to ns introspection (resolve/ns-publics can't see seed-fallback names like compare, gensym, type) — a conformance finding in its own right
  • the rest classified host/JVM/concurrency (see dashboard)

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.