simon/jolt

History

Yogthos ce8e89ca86 Contract fixes from the baseline audit; every residual suite failure traced Auditing the remaining cts baseline for R7 exposed real contract gaps hiding among the model residue — all fixed to reference behavior: - stale no-ratio-era stubs: numerator/denominator now work over jolt's exact rationals (non-ratio is the Ratio cast failure); rational? includes decimals - casts and pending: peek/pop demand an IPersistentStack (pop nil is nil), realized? demands an IPending (a plain list/range throws), transient demands an editable COLLECTION (non-colls throw; the RFC 0003 sorted/list/seq superset keeps the copy-on-write fallback), empty on a plain record throws - nil and empties: (nth nil i) is nil, (nth nil i d) is d, a nil index is NPE, keys/vals of anything empty are nil, (conj nil) is nil - lookups: contains? on a string is index-only (other keys IAE), get on an array is lenient (nth still throws), a VECTOR invocation has nth semantics (([1 2] 5) throws — call position and jolt-invoke both) - into only transients editable collections; a PersistentQueue/sorted target folds through conj (RT's IEditableCollection split) - numbers: number?/num accept BigDecimal, quot/rem throw on an Infinite/NaN quotient, even?/odd? demand integers - ordering: keywords compare namespace-first with nil first (Symbol.compareTo) - misc: run! honors reduced, eval self-evaluates non-form values, intern demands an existing namespace, counted? excludes strings, seqable? includes arrays, shuffle rejects maps, sort-by rejects a collection comparator, when-let demands one binding pair, case/deftype/letfn/reify/& are special symbols Two mis-certified corpus rows fixed (they threw on the JVM too and hid in the tolerated bucket): a raw \d string escape and duplicate literal map keys. SPEC.md gains the baseline-traceability section: every one of the 146 remaining suite failures maps to a documented divergence (integer-box, no-single-float, RFC 0003 transients, seq/chunking model, stm-refs, parse-uuid strictness, vec-array adoption). cts baseline 5955 -> 6042 pass, 5 errors, 30 namespaces. 9 JVM-certified corpus rows.		2026-07-02 13:52:59 -04:00
..
certify.clj	Clean up codebase: rename stdlib layer, strip porting residue, fix tooling	2026-06-22 22:18:00 -04:00
known-divergences.edn	Numbers-style category dispatch for binary numeric ops	2026-07-02 06:41:45 -04:00
profile.edn	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
regen-corpus.clj	Clean up codebase: rename stdlib layer, strip porting residue, fix tooling	2026-06-22 22:18:00 -04:00
SPEC.md	Contract fixes from the baseline audit; every residual suite failure traced	2026-07-02 13:52:59 -04:00

README.md

Conformance: certifying the corpus against reference Clojure

See SPEC.md for the full host-neutral language-spec contract: the corpus schema, conformance levels, the feature profile, and how to host jolt on a new runtime. This README covers the certification tooling specifically.

The corpus (test/chez/corpus.edn) is jolt's host-neutral behavioral suite — one row per case: {:suite :label :expected :actual}, where :actual is a Clojure source expression and :expected its result (or :throws). The runtime harness (host/chez/run-corpus.ss, invoked by make corpus) replays it on Chez and compares by value-equality.

Every :expected is sourced from reference JVM Clojure, so the corpus is both a regression suite and a specification certified against Clojure rather than against its authors' beliefs. This directory holds the certification tooling that closes that gap.

What's here

certify.clj — runs every corpus row's :actual and :expected through reference JVM Clojure (each in a fresh user namespace, output/stdin sunk, a 5s per-case watchdog) and compares with Clojure's =. It buckets each row:
- certified / certified-throws — jolt's :expected matches real Clojure
- divergent — both evaluate but jolt's :expected disagrees with Clojure
- throws-mismatch — jolt and Clojure disagree on whether it throws
- jvm-error — :actual isn't runnable on vanilla Clojure (host-coupled / jolt-specific) — informational, not certifiable
- read-error / timeout — won't read on the JVM reader, or ran too long
known-divergences.edn — every current divergence, classified. Most are deliberate jolt-specific or host-model deltas (see :legend): the all-double numeric model, snapshot-heap concurrency, the no-JVM host model, jolt reader features, the jolt printer, intentional strictness. A few are genuine :bug entries with a tracked bead. These categories become the :features flags in conformance inc3.

make certify is the gate wrapper. It skips cleanly when clojure (JVM) is not installed; otherwise it runs certify.clj and fails the build on a NEW (unclassified) divergence or a stale allowlist entry. Flaky entries (JVM result is timing-dependent, e.g. future-cancel) are tolerated either way.

Running

make certify                                                 # the gate wrapper (skips if clojure absent)
clojure -M test/conformance/certify.clj                      # gate directly (exit≠0 on new/stale)
clojure -M test/conformance/certify.clj test/chez/corpus.edn --edn /tmp/report.edn  # full machine-readable report

Current state

Of ~2740 vanilla-certifiable rows, >2730 match reference Clojure exactly; the handful of divergences are all classified (deliberate deltas plus a few tracked bugs). The corpus is trustworthy as a spec, with the host-specific deltas made explicit rather than hidden.

Adding / changing cases

When you add corpus rows or change behavior, re-run the certifier. A NEW divergence means either a real bug (file it, tag the allowlist entry :bug + :bead) or a deliberate delta (classify it). A stale entry means a divergence was fixed — remove it from known-divergences.edn.