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.