From 8a9e386fa71a95bbbe19456bd84ae11a039d87ca Mon Sep 17 00:00:00 2001
From: Yogthos <yogthos@gmail.com>
Date: Tue, 9 Jun 2026 13:35:08 -0400
Subject: [PATCH] docs: clarify fn*/let*/loop* take plain symbols only
 (jolt-f79)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

grammar.ebnf: the destructuring note already attributed patterns to the
binding MACROS; make the boundary explicit — the fn*/let*/loop* PRIMITIVES
they desugar to take plain symbols only (a non-symbol binding errors, as
in Clojure).

self-hosting-compiler.md: the 'compile destructuring via a shared
destructure expander instead of falling back' item is done (and its
jolt-7dl ref was stale) — destructuring now compiles through the
fn/let/loop/defn macros' desugaring; the primitives reject patterns.
---
 doc/grammar.ebnf             | 7 +++++--
 doc/self-hosting-compiler.md | 8 +++++---
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/grammar.ebnf b/doc/grammar.ebnf
index 4c2f30e..dffffb1 100644
--- a/doc/grammar.ebnf
+++ b/doc/grammar.ebnf
@@ -164,8 +164,11 @@ feature         = ":clj" | ":cljs" | ":default" | keyword ;
 tagged-literal  = "#" , symbol , ws , form ;
 
 (* ── Destructuring (semantics, not reader syntax) ────────────────────────────
-   The reader produces plain vectors and maps; the binding forms (let, fn, loop,
-   doseq, for, defmacro params, …) interpret them as destructuring patterns:
+   The reader produces plain vectors and maps; the binding MACROS (let, fn, loop,
+   doseq, for, defmacro params, …) interpret them as destructuring patterns. The
+   PRIMITIVES they desugar to — fn*, let*, loop* — take plain symbols ONLY (a
+   non-symbol binding is an error, as in Clojure: "fn params must be Symbols" /
+   "Bad binding form, expected symbol"). The grammar of a pattern:
 
      binding        = symbol | seq-binding | map-binding ;
      seq-binding    = "[" , { binding } , [ "&" , binding ] , [ ":as" , symbol ] , "]" ;
diff --git a/doc/self-hosting-compiler.md b/doc/self-hosting-compiler.md
index 05d9ada..ea21c56 100644
--- a/doc/self-hosting-compiler.md
+++ b/doc/self-hosting-compiler.md
@@ -150,9 +150,11 @@ linking is opt-in, never the default, so the REPL is always live.
 2. **Hybrid fallback + coverage** (`jolt-1bj`) — *done*. Forms the compiler can't
    compile throw `jolt/uncompilable` and fall back to the interpreter, so compile
    mode is always correct. Covered: multi-arity/named/variadic fns, `recur` in
-   `fn`, map/vector literals, and resolution matching the interpreter. (One
-   optimization left: compile destructuring via a shared `destructure` expander
-   instead of falling back — `jolt-7dl`.)
+   `fn`, map/vector literals, and resolution matching the interpreter.
+   Destructuring compiles via the shared `destructure` expander: the `fn`/`let`/
+   `loop`/`defn` macros desugar to plain-symbol `fn*`/`let*`/`loop*`, so it no
+   longer falls back — and the primitives reject patterns outright, matching
+   Clojure (`jolt-f79`).
 5. **Compile-by-default + AOT** (`jolt-7j9`) — *done, done out of order*. Once the
    hybrid path was validated at parity, compilation was flipped on by default and
    AOT images (`aot.janet`) landed. Done before 3–4 because it's the runtime