Phase 3: Compile-aware loader, :compile? flag, compile-and-eval

- loader.janet: load-ns with compile? dispatch, compiled-cache, compiled?, clear-compiled-cache
- compiler.janet: compile-ast (Janet data structures for direct eval), compile-and-eval
- api.janet: compile-string, compile-file, eval-string dispatches to compile-and-eval when :compile? is true
- types.janet: :compile? flag and :compiled-cache table in context env
- Stateful forms (def, defmacro, ns, deftype, defmulti, defmethod) fall back to interpreter
- All 317 tests pass + 16 new Phase 3 tests

.dirge/memory/MEMORY.md

@@ -1,7 +1,5 @@
-Compiler implementation plan (6 phases): Phase 1 — compiler.janet skeleton + emit* for const/do/if/let/fn/def/invoke. Phase 2 — symbol classifier (resolve locals/vars/core at analyze time). Phase 3 — loader.janet + api.janet wiring (:compile? flag, load-ns, caching). Phase 4 — macro integration (expand at analyze time via interpreter). Phase 5 — remaining ops (loop/recur, try/throw, quote, syntax-quote, set!, deftype, .). Phase 6 — tests + benchmarks. New files: src/jolt/compiler.janet, src/jolt/loader.janet, test/compiler-test.janet. Modified files: evaluator.janet (compiler fast-path), types.janet (compiled-cache table), api.janet (compile-string, load-ns). Reader and core unchanged.
+Compiler Phases 1-3 COMPLETE. src/jolt/compiler.janet (342 lines): analyze-form→emit-ast two-phase. Phase 2: symbol classification (locals→core→symbol, shadowing works). Phase 3: compile-and-eval via parser→consume→eof→produce→eval pipeline, :compile? flag in types.janet context, loader.janet (80 lines) for namespace loading, api.janet updated (compile-string, compile-file, compile-aware eval-string). Stateful forms (def, defmacro, ns, deftype, defmulti, defmethod, require, in-ns) always route to interpreter. All 317 tests pass. Next: Phase 4 (macro integration), Phase 5 (remaining ops: loop/recur, try/throw, quote, syntax-quote, set!, .), Phase 6 (benchmarks).
 §
-Compiler is in `src/jolt/compiler.janet` (352 lines). Two-phase architecture: `analyze-form` produces annotated AST with `:op` keys, `emit-ast` dispatches on `:op` to emit Janet source, `compile-form` ties them together returning a Janet source string. Source-to-source (not bytecode). `core-renames` table maps Clojure core names to Janet function names (e.g., "inc" → "core-inc"). Phase 1 covers: const, do, if, def, fn*, let*, invoke, symbol, core-symbol, qualified-symbol, quote, vector, map. Tests in `test/compiler-test.janet` (79 lines). Phase 2 (symbol classification — locals/vars/core at analyze time) is the next step.
+Compiler is in `src/jolt/compiler.janet` (342 lines). Two-phase: `analyze-form [form bindings]` → annotated AST with `:op` keys, `emit-ast` dispatches on `:op` → Janet source string via StringBuffer. `compile-form` for source output, `compile-and-eval` for direct eval via `eval-janet-source` (parser/new→consume→eof→produce→eval pipeline). `core-renames` table maps Clojure→Janet names. Ops covered: const, do, if, def, fn*, let*, invoke, symbol (local/core-symbol/qualified classification), quote. Symbol classification order: locals → core-symbol → symbol (shadowing works). Stateful forms (def, defmacro, etc.) must use interpreter path, not compile-and-eval.
 §
-After compiler Phase 1: 317 tests pass, 0 failures (was 253 before). Compiler tests add 8 test groups (literals, do, if, def, fn, let, invoke — 19 assertions). Run with `jpm test`.
-§
-Compiler development workflow: (1) add match arm in `analyze-form` → produces `{:op :new-op ...}` AST, (2) add `emit-*` helper + dispatch arm in `emit-ast`, (3) add test assertions in `test/compiler-test.janet` using `compile-str` helper, (4) run `janet test/compiler-test.janet` then `jpm test`. Tests compare source-to-source output strings, not execution results. Any fn added to `core-bindings` in core.janet must also be added to `core-renames` in compiler.janet.
+Compiler tests in `test/compiler-test.janet` (143 lines, 10 test groups). Phase 1: 7 groups, 19 string-output assertions. Phase 2: local classification (3 assertions: shadowing, param shadowing, nested let). Phase 3: compile-and-eval round-trip (9 assertions) + :compile? flag tests (7 assertions). All 317 tests pass. Run with `janet test/compiler-test.janet` or `jpm test`.

.dirge/memory/PITFALLS.md

@@ -1,5 +1,5 @@
-Bit operations in Janet (brshift, brushift, band, bor, bxor) use 32-bit signed integers. Values from (hash key) can exceed 32-bit range (>2^31). brshift with out-of-range value fails with 'rhs must be valid 32-bit signed integer'. Use (band x 0xFFFFFFFF) before shifting, or use arithmetic approaches (mod, /, pow) instead of bit ops for hash-based data structures.
-§
-`.clj` source files are loaded at init time by Jolt's own reader/evaluator. PersistentVector (17 forms) and PersistentHashMap (12 forms) live in `src/jolt/clojure/lang/persistent_*.clj`. api.janet's `init` calls `load-persistent-structures` which slurps and eval-forms each file, then swaps clojure.core bindings (vec, vector, vector?, hash-map) to the persistent versions. Pass `{:mutable? true}` to skip loading and use Janet-native types.
-§
 Janet LSP produces false positives on `.janet` files — it doesn't understand Janet syntax (thinks docstring lines are unresolved symbols, doesn't know `declare-project`/`declare-source` macros, etc.). These are pre-existing and should be ignored — they don't affect runtime correctness.
+§
+Janet `(parse s)` returns `[symbol, error-position]` for forms — e.g., `(parse "(+ 1 2)")` gives `[+ 1]`, not a parsed tuple. For proper evaluation of special forms, must use the parser pipeline: `parser/new` → `parser/consume` → `parser/eof` → `parser/produce` → `eval`. Without `parser/eof`, `produce` returns nil for simple forms like numbers. Janet's `eval` also doesn't support special forms natively in data structures — `(eval [if true 1 2])` fails with "unknown symbol if". Must parse strings, not eval tuples.
+§
+When you need to mutate a local with `set`, use `(var x nil)` not `(def x nil)`. `def` creates constants — `(set ns-name ...)` on a `def` fails with "cannot set constant". This hit us in loader.janet ns-name extraction loop.

.dirge/skills/.usage.json

@@ -1,16 +1,35 @@
 {
+  "jpm-build": {
+    "created_by": "agent",
+    "use_count": 0,
+    "view_count": 11,
+    "patch_count": 0,
+    "last_viewed_at": "2026-06-02T17:43:38.327259+00:00",
+    "created_at": "2026-06-01T20:56:39.144222+00:00",
+    "state": "active",
+    "pinned": false
+  },
   "jolt-dev": {
     "created_by": "agent",
-    "use_count": 24,
-    "view_count": 35,
-    "patch_count": 30,
-    "last_used_at": "2026-06-02T18:45:23.321430+00:00",
-    "last_viewed_at": "2026-06-02T18:45:23.310874+00:00",
-    "last_patched_at": "2026-06-02T17:27:24.746485+00:00",
+    "use_count": 25,
+    "view_count": 36,
+    "patch_count": 31,
+    "last_used_at": "2026-06-02T19:13:37.620054+00:00",
+    "last_viewed_at": "2026-06-02T19:13:37.612317+00:00",
+    "last_patched_at": "2026-06-02T19:14:06.338745+00:00",
     "created_at": "2026-06-01T21:26:06.614465+00:00",
     "state": "active",
     "pinned": false
   },
+  "jolt-compiler": {
+    "created_by": "agent",
+    "use_count": 0,
+    "view_count": 0,
+    "patch_count": 0,
+    "created_at": "2026-06-02T17:54:38.690279+00:00",
+    "state": "active",
+    "pinned": false
+  },
   "jolt-bootstrap": {
     "created_by": "agent",
     "use_count": 9,
@@ -22,24 +41,5 @@
     "created_at": "2026-06-01T21:49:51.101718+00:00",
     "state": "active",
     "pinned": false
-  },
-  "jolt-compiler": {
-    "created_by": "agent",
-    "use_count": 0,
-    "view_count": 0,
-    "patch_count": 0,
-    "created_at": "2026-06-02T17:54:38.690279+00:00",
-    "state": "active",
-    "pinned": false
-  },
-  "jpm-build": {
-    "created_by": "agent",
-    "use_count": 0,
-    "view_count": 11,
-    "patch_count": 0,
-    "last_viewed_at": "2026-06-02T17:43:38.327259+00:00",
-    "created_at": "2026-06-01T20:56:39.144222+00:00",
-    "state": "active",
-    "pinned": false
   }
 }

.dirge/skills/jolt-dev/SKILL.md

@@ -1,6 +1,7 @@
-# jolt-dev
-
-Jolt development workflow — build, test, special form patterns, Janet gotchas
+---
+name: jolt-dev
+description: Jolt development workflow — build, test, special form patterns, Janet gotchas
+---
 
 # Jolt Development
 
@@ -13,6 +14,29 @@ jpm test            # runs all tests
 janet test/foo.janet  # run a single test file from project root
 ```
 
+## Compiler Development
+
+See `jolt-compiler` skill for the Clojure→Janet source-to-source compiler workflow.
+
+## Janet Eval Pipeline (critical)
+
+Janet's `(parse s)` does NOT return a parsed form — it returns `[symbol, error-position]`.
+For evaluating Janet source strings, use the parser pipeline:
+
+```janet
+(def p (parser/new))
+(parser/consume p source)
+(parser/eof p)              # REQUIRED — otherwise produce returns nil
+(def form (parser/produce p))
+(eval form)
+```
+
+**Never** try `(eval [if true 1 2])` — Janet's `eval` doesn't recognize special forms in tuple data structures.
+
+## `var` vs `def`
+
+When you need to mutate a local with `set`, use `(var x nil)` not `(def x nil)`. `def` creates constants.
+
 ## Special Form Checklist
 
 To add a new special form to the evaluator:
@@ -28,4 +52,25 @@ The match arm receives `ctx`, `bindings`, and `form` (the full list). Use `(in f
 ### Current special forms (22):
 `quote`, `syntax-quote`, `unquote`, `unquote-splicing`, `do`, `if`, `def`, `defmacro`, `fn*`, `let*`, `loop*`, `recur`, `throw`, `try`, `set!`, `var`, `locking`, `instance?`, `defmulti`, `defmethod`, `deftype`, `new`, `.`
 
-## Pers… (truncated, 34945 bytes total)
+## Persistent Data Structures
+
+Located in:
+- `src/jolt/clojure/lang/persistent_vector.clj`
+- `src/jolt/clojure/lang/persistent_hash_map.clj`
+
+Loaded at init time by `load-persistent-structures` in `api.janet`. Use `{:mutable? true}` to skip and use Janet-native types.
+
+### Implementation detail
+Simple array-based implementation (node-assoc/node-find/find-key-index), NOT HAMT bit-trie.
+HAMT failed because Janet uses 64-bit doubles and bit operations require 32-bit signed ints.
+
+## Janet Gotchas
+
+- Bit operations (brshift, brushift, band) use 32-bit signed integers. Hash values can exceed 32-bit range. Use `(band x 0xFFFFFFFF)` before shifting.
+- `deftype` creates tables, not structs. `struct?` returns false.
+- `(get child :key)` DOES follow table prototype chain — resolved and confirmed working.
+- Janet LSP produces many false positives on `.janet` files — safe to ignore.
+
+## Symbol representation
+
+Jolt symbols are `{:jolt/type :symbol :ns <string-or-nil> :name <string>}` as produced by the reader.