reader: feature set #{:jolt :default}, clause-order matching (RFC 0002)

jolt no longer satisfies :clj in reader conditionals. The shortcut was a
measured net liability: :clj branches carry JVM interop and JVM-specific
test expectations jolt fails, and they shadowed :default branches jolt
passes. A/B over the suite: clj,default = 4967 assertions / 4324 pass / 119
errors; jolt,default = 5069 / 4470 / 81 (+146 pass, -38 errors, +8 clean
files). Baselines raised to 4470/86.

Matching is now by CLAUSE order like Clojure — the first clause whose key is
in the feature set wins (#?(:default 5 :clj 6) is 5 everywhere); the old code
scanned for :clj first, then :default, regardless of position.

Foreign clj-targeted libraries are a property of the LOADING CONTEXT, not the
platform: reader-features-set! opts a load into a compatibility set, and the
SCI bootstrap/runtime tests load SCI under ["jolt" "clj" "default"] (its
.cljc selects implementations via :clj with no :jolt branches).
JOLT_FEATURES remains the process-wide override.

RFC 0002 records the decision with the measured data; spec 02-reader S18 is
now normative (clause order, documented feature set, per-context override).
Reader tests updated to the portable set + an opt-in round-trip.

docs/rfc/0002-reader-conditional-features.md

@@ -0,0 +1,82 @@
+# RFC 0002 — Reader-Conditional Feature Set
+
+- **Status**: Accepted (implemented; measured)
+- **Created**: 2026-06-10
+- **Spec**: `docs/spec/02-reader.md` §2.3 S18
+
+## Summary
+
+jolt's reader-conditional feature set is **`#{:jolt :default}`**, matched in
+**clause order** (the first clause whose key the platform satisfies wins).
+A loading context may opt a foreign, clj-targeted library into `:clj`
+compatibility via `reader-features-set!` (or process-wide via the
+`JOLT_FEATURES` environment variable). jolt does **not** satisfy `:clj` by
+default.
+
+## Background
+
+`#?(:clj … :cljs … :default …)` selects a branch by platform feature at read
+time. Until now jolt satisfied `:clj` — a compatibility shortcut inheriting
+the JVM branches of `.cljc` files, on the theory that the `:clj` branch is
+usually the "main" implementation. Each dialect chooses its own policy:
+ClojureScript satisfies only `:cljs`; jank uses `:jank`; babashka includes
+`:clj` because it genuinely is JVM-Clojure-compatible to a deep degree.
+
+Two defects forced the decision:
+
+1. jolt is *not* JVM-compatible where it matters for `:clj` branches: they
+   contain interop (`java.util.*`, `deftype` over JVM classes) and encode
+   JVM-specific *expectations* in tests (e.g. `parse-uuid`'s reference
+   permissiveness), both of which jolt fails.
+2. The old implementation also matched by **key priority** (`:clj` first,
+   then `:default`) rather than clause order — `#?(:default 5 :clj 6)` read
+   as `6`, diverging from Clojure on all platforms.
+
+## Decision and evidence
+
+Measured A/B over the cross-dialect clojure-test-suite (identical tree,
+2026-06-10):
+
+| Feature set | Assertions reached | Pass | Fail | Error | Clean files |
+|---|---|---|---|---|---|
+| `clj, default` (old) | 4967 | 4324 | 524 | 119 | 78 |
+| `jolt, default` (new) | **5069** | **4470** | **518** | **81** | **86** |
+
+The portable convention reads *more* of the suite (`:default` branches were
+being shadowed by `:clj` ones jolt can't satisfy) and improves every metric:
++146 passes, −38 errors, +8 clean files. The `:clj` shortcut was a net
+liability, not a compatibility win.
+
+The opposing case — loading real-world clj-targeted libraries — is real:
+SCI's `.cljc` sources select their implementation via `#?(:clj …)`/`:cljs`
+with no `:jolt` branches, and fail to load under the portable set. That is a
+property of the **loading context**, not of the platform: the resolution is
+per-context opt-in, exactly how the SCI bootstrap now loads
+(`(reader-features-set! ["jolt" "clj" "default"])`).
+
+## Specification (normative, mirrored in spec §2.3 S18)
+
+1. The platform feature set is implementation-defined and MUST be
+   documented. jolt's is `#{:jolt :default}`.
+2. Matching MUST be by clause order: the first clause whose key is in the
+   feature set wins. `:default` matches on every platform.
+   `#?(:default 5 :clj 6)` is `5` everywhere.
+3. An unmatched conditional reads as nothing (no form); an unmatched
+   `#?@(…)` splices nothing.
+4. Implementations SHOULD provide a per-loading-context override so foreign
+   libraries written for other dialects can be read under a compatibility
+   set; using it is a deliberate, scoped decision (jolt:
+   `reader-features-set!` / `JOLT_FEATURES`).
+
+## Consequences
+
+- Suite baselines re-measured and raised: `baseline-pass` 4324 → 4470,
+  `baseline-clean-files` 78 → 86.
+- Reader tests assert the portable set + clause-order semantics, plus one
+  opt-in round-trip through `reader-features-set!`.
+- Loading clj-ecosystem libraries via deps requires deciding their feature
+  set; the deps loader currently inherits the process default — a future
+  refinement is per-dependency feature configuration (filed with the deps
+  work, jolt-dw4).
+- `.cljc` authors targeting jolt can write `:jolt` branches and rely on
+  `:default` fallbacks.

docs/spec/02-reader.md

@@ -127,9 +127,14 @@ checks → UNVERIFIED (rows to add).
   platform satisfies, else nothing. `:default` matches any platform.
   `#?@(…)` splices a sequential form into the surrounding context.
 - Feature keys are implementation-defined; each implementation MUST document
-  its feature set. ⚠ jolt currently satisfies `:clj` (inheriting JVM branches
-  in `.cljc` files) — under review; the portable convention is
-  *own-key + `:default`*.
+  its feature set, and SHOULD follow the portable convention *own dialect key
+  + `:default`*. Matching MUST be by **clause order** — the first clause whose
+  key the platform satisfies wins (`#?(:default 5 :clj 6)` is `5` everywhere)
+  — not by key priority. Implementations SHOULD provide a per-loading-context
+  compatibility override for foreign-dialect libraries. (jolt:
+  `#{:jolt :default}`, opt-in via `reader-features-set!`/`JOLT_FEATURES`;
+  decision + A/B data in RFC 0002 — inheriting `:clj` cost 146 suite
+  assertions and 38 errors.)
 - Reader conditionals MUST be an error outside `.cljc`-style reading unless
   the implementation documents otherwise.
 

src/jolt/reader.janet

@@ -387,6 +387,34 @@
       (array/push arg-names rest-sym))
     [@[(sym "fn*") (tuple ;arg-names) replaced] new-pos]))
 
+# The reader-conditional feature set (spec 02-reader S18): jolt is its own
+# dialect, so the portable convention applies — the dialect key plus :default.
+# Matching is by CLAUSE order (the first clause whose key is in the feature
+# set wins), exactly like Clojure — NOT key-priority. JOLT_FEATURES overrides
+# (comma-separated, e.g. "jolt,clj,default") for compat experiments and A/B
+# measurement; :default is always honored.
+# Mutable so a loading context can opt a clj-targeted foreign library into
+# :clj compatibility (e.g. SCI) — see reader-features-set!. jolt itself and
+# the conformance surface read under the portable set.
+(var reader-features nil)
+
+(defn reader-features-set!
+  "Replace the active reader-conditional feature set (a list of keyword-name
+  strings or keywords). :default is always honored. Returns the previous set
+  so callers can restore."
+  [names]
+  (def prev reader-features)
+  (def t @{})
+  (each n names (put t (if (keyword? n) n (keyword n)) true))
+  (put t :default true)
+  (set reader-features t)
+  prev)
+
+(reader-features-set!
+  (let [env (os/getenv "JOLT_FEATURES")]
+    (if env (filter |(> (length $) 0) (string/split "," env))
+      ["jolt" "default"])))
+
 (defn read-reader-conditional [s pos]
   # pos is at #, next char is ? or ?@
   (def splice? (and (< (+ pos 2) (length s)) (= (s (+ pos 2)) 64))) # @ = 64
@@ -394,23 +422,16 @@
   (let [[form new-pos] (read-form s form-start)]
     (if (array? form)
       (do
+        # First clause (in clause order) whose feature key is in the set.
+        # `matched` is tracked separately: a matched clause may be nil.
         (var result nil)
+        (var matched false)
         (var i 0)
-        (while (< i (length form))
-          (if (= (in form i) :clj)
-            (do
-              (set result (in form (+ i 1)))
-              (set i (length form)))
-            (++ i)))
-        # Fallback to :default if :clj not matched
-        (when (nil? result)
-          (set i 0)
-          (while (< i (length form))
-            (if (= (in form i) :default)
-              (do
-                (set result (in form (+ i 1)))
-                (set i (length form)))
-              (++ i))))
+        (while (and (not matched) (< i (length form)))
+          (when (get reader-features (in form i))
+            (set result (in form (+ i 1)))
+            (set matched true))
+          (+= i 2))
         (if splice?
           # #?@ splicing: resolve :clj branch, wrap for splice
           (let [items (if (nil? result)

test/integration/clojure-test-suite-test.janet

@@ -43,9 +43,9 @@
 # Raised 4004 -> 4034 / clean 66 -> 67 porting partition-all + repeatedly to the
 # overlay, which required fixing two leniencies (a char is not callable; take
 # validates its count) — correct beyond those fns, so the suite rose broadly.
-(def baseline-pass 4324)
+(def baseline-pass 4470)
 # A file is "clean" when it ran with zero failures AND zero errors.
-(def baseline-clean-files 78)
+(def baseline-clean-files 86)
 # Per-file wall-clock budget (seconds). Normal files finish in well under 1s, so
 # this normally only fires on genuinely-infinite-sequence hangs. It's an env var
 # (JOLT_SUITE_TIMEOUT) so CI — whose runners are slower than a dev machine — can

test/integration/sci-bootstrap-test.janet

@@ -2,6 +2,12 @@
 (use ../../src/jolt/types)
 (use ../../src/jolt/reader)
 (use ../../src/jolt/api)
+(use ../../src/jolt/reader)
+# SCI is a clj/cljs-targeted library: its .cljc sources select implementation
+# via #?(:clj ...) and have no :jolt branches — load it under clj-compat
+# features (spec 02-reader S18: feature sets are a property of the loading
+# context; the portable default is #{:jolt :default}).
+(reader-features-set! ["jolt" "clj" "default"])
 
 (def ctx (init))
 

test/integration/sci-runtime-test.janet

@@ -2,6 +2,12 @@
 (use ../../src/jolt/types)
 (use ../../src/jolt/reader)
 (use ../../src/jolt/api)
+(use ../../src/jolt/reader)
+# SCI is a clj/cljs-targeted library: its .cljc sources select implementation
+# via #?(:clj ...) and have no :jolt branches — load it under clj-compat
+# features (spec 02-reader S18: feature sets are a property of the loading
+# context; the portable default is #{:jolt :default}).
+(reader-features-set! ["jolt" "clj" "default"])
 
 (defn- load-stubs [ctx filepath]
   (var s (slurp filepath))

test/spec/reader-syntax-spec.janet

@@ -45,8 +45,14 @@
   ["anon fn %&"         "[2 3]"     "(#(vec %&) 2 3)"]
   ["discard #_"         "[1 3]"     "[1 #_2 3]"]
   ["regex literal"      "true"      "(= \"abc\" (re-find #\"abc\" \"xabcx\"))"]
-  ["reader conditional" "1"         "#?(:clj 1 :cljs 2 :default 3)"]
-  ["reader cond splice" "[1 2 3]"   "[#?@(:clj [1 2 3] :cljs [4 5])]"]
+  # Feature set is #{:jolt :default} (spec 02-reader S18; RFC 0002) — :clj
+  # branches are NOT taken; matching is by clause order.
+  ["reader conditional" "3"         "#?(:clj 1 :cljs 2 :default 3)"]
+  ["reader cond :jolt"  "4"         "#?(:clj 1 :jolt 4 :default 3)"]
+  ["reader cond clause order" "5"   "#?(:default 5 :jolt 6)"]
+  ["reader cond no match" "[]"      "[#?(:clj 1 :cljs 2)]"]
+  ["reader cond splice" "[1 2 3]"   "[#?@(:jolt [1 2 3] :cljs [4 5])]"]
+  ["reader cond splice no match" "[]" "[#?@(:clj [1 2 3] :cljs [4 5])]"]
   ["inst literal reads" "true"      "(some? #inst \"2020-01-01T00:00:00Z\")"]
   ["uuid literal"       "\"550e8400-e29b-41d4-a716-446655440000\"" "(str #uuid \"550e8400-e29b-41d4-a716-446655440000\")"]
   ["tagged literal var" "true"      "(var? #'+)"]

test/unit/reader-test.janet

@@ -123,18 +123,23 @@
   (let [[form2 _] (parse-next rest-str)]
     (assert (deep= [3 4] form2) "second form is vector")))
 
-# Reader conditional — resolves :clj branch at read time
-(assert (= 1 (parse-string "#?(:clj 1 :cljs 2)"))
-        "#?(:clj) picks :clj branch")
+# Reader conditional — feature set is #{:jolt :default} (spec 02-reader S18,
+# RFC 0002); matching is by clause order. reader-features-set! lets a loading
+# context opt a clj-targeted library into :clj compat (restored below).
+(assert (= 3 (parse-string "#?(:clj 1 :jolt 3 :cljs 2)"))
+        "#?(...) picks :jolt branch")
 (assert (= nil (parse-string "#?(:cljs 999)"))
-        "#?(:cljs) returns nil on CLJ")
-(assert (= 42 (parse-string "#?(:clj 42)"))
-        "#?(:clj) with single branch")
-(assert (deep= (sym "clj-only") (parse-string "#?(:clj clj-only :cljs cljs-only)"))
-        "#?(:clj) picks :clj symbol")
-# Nested inside a list — :clj branch is evaluated at read time
-(assert (deep= @[(sym "+") 1 3] (parse-string "(+ 1 #?(:clj 3 :cljs 4))"))
-        "#? inside list picks :clj")
+        "unmatched conditional reads as nothing")
+(assert (= 7 (parse-string "#?(:clj 1 :default 7)"))
+        ":default reached when :clj not in feature set")
+(assert (= 5 (parse-string "#?(:default 5 :jolt 6)"))
+        "clause order wins, not key priority")
+(assert (deep= @[(sym "+") 1 3] (parse-string "(+ 1 #?(:jolt 3 :cljs 4))"))
+        "#? inside list picks :jolt")
+(let [prev (reader-features-set! ["jolt" "clj" "default"])]
+  (assert (= 1 (parse-string "#?(:clj 1 :cljs 2)"))
+          "clj-compat opt-in picks :clj")
+  (reader-features-set! (keys prev)))
 
 # Characters — the reader now produces char values {:jolt/type :jolt/char :ch N}
 (let [form (parse-string "\\newline")]