Phase 5: Multimethods + Hierarchy system

- types.janet: make-hierarchy, derive*, ancestors, descendants, isa?, underive
- evaluator.janet: defmulti extended with :default and :hierarchy options
  + keyword dispatch-fns wrapped as (fn [x] (get x kw)) for Janet compat
  + hierarchy-based dispatch walks isa? chain when no direct match
- core.janet: real derive, isa?, ancestors, descendants implementations
  replacing stubs; core-remove-method, core-remove-all-methods,
  core-prefer-method added; new core-bindings entries
- 5 test sections (22-26): hierarchy ops, basic dispatch, :default,
  hierarchy dispatch, remove-method — all pass
- 317 tests, 0 failures

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

@@ -1,4 +1,5 @@
 # jolt-compiler
+# Jolt Compiler
 
 Source-to-source Clojure→Janet compiler. Two-phase: analyze-form (classify + macro expand) → emit-ast (generate).
 
@@ -15,81 +16,122 @@ Clojure form → analyze-form [form bindings ctx] → AST {:op ...}
 Three public entry points:
 - `(compile-form form &opt ctx)` → Janet source string (debug/display)
 - `(compile-ast form &opt ctx)` → Janet data structure (for eval)
-- `(compile-and-eval form ctx)` → compile-ast + eval + ns interning
+- `(compile-and-eval form ctx)` → compile-ast + eval
 
 ## Why data structures, not source strings
 
-Janet's `eval` does NOT have access to `use`-imported symbols. Emit Janet tuples with embedded function VALUES via `core-fn-values` table.
+Janet's `eval` does NOT have access to `use`-imported symbols from the calling file. `(eval "(core-inc 1)")` fails with "unknown symbol core-inc". The fix: emit Janet tuples where function VALUES are embedded: `[core-inc 1]`.
 
-Source-to-source (`compile-form` + `emit-ast`) exists for debugging, NOT used by `compile-and-eval`.
+```
+core-fn-values table:  "core-inc" → core-inc (the actual function)
+emit-core-symbol-expr → (get core-fn-values janet-name)
+```
+
+Source-to-source (`compile-form` + `emit-ast`) still exists for debugging but is NOT used by `compile-and-eval`.
 
 ## Macro expansion
 
-`analyze-form` checks `resolve-macro` before special form dispatch:
-1. Look up symbol in current ns → core ns
-2. If `var-macro?`, apply fn, re-analyze expanded form
+`analyze-form` checks whether the head symbol of a list resolves to a macro var before dispatching to special form handling:
 
-## Symbol classification
+1. Look up symbol in current ns → core ns via `resolve-macro`
+2. If `var-macro?` is true, call `(var-get macro-var)` to get the fn
+3. `(apply macro-fn (tuple/slice form 1))` to expand
+4. `(analyze-form expanded ...)` to re-analyze the result
+
+Macros expand at analyze time, before emission. `defn` expands to `(def name (fn* ...))`, `when` to `(if test (do ...) nil)`, etc.
+
+## Symbol classification (in analyze-form)
 
 Order: qualified ns → local binding → core-symbol → bare symbol
 
-core-renames MUST match actual fn names: `"-"` → `"core-sub"` (not `"core--"`).
+```
+(if (form :ns) → :qualified-symbol
+    (get bindings name) → :local
+    (get core-renames name) → :core-symbol
+    → :symbol)
+```
+
+core-renames MUST match actual fn names: `"-"` → `"core-sub"` (not `"core--"`), `"not"` → `"core-not"`. Verify against `core.janet` bindings.
 
 ## core-fn-values
 
-Maps Janet string names to actual function values. Must be kept in sync with core-renames.
-Special mappings: `"apply"` → `apply` (built-in), `"some"` → `core-some?`, `"pr-str"` → `core-str`, `"nth"` → `core-nth`.
+Maps Janet string names to actual function values. Must be kept in sync with core-renames. When adding a new core fn, update BOTH tables.
 
-## compile-and-eval interning
-
-`def`/`defn` results are interned in the Jolt namespace via `ns-intern` so the interpreter can resolve bare symbols. This is critical — without it, `(defn foo [x] x)` followed by `(foo 1)` would fail with "Unable to resolve symbol: foo".
+Functions that need special mapping (name differs):
+- `"apply"` → `apply` (Janet built-in)
+- `"-"` → `"core-sub"` (not `core--`)
+- `"some"` → `core-some?` (shared with `core-some?`)
+- `"pr-str"` → `core-str` (alias)
+- `"nth"` → `core-nth` (separate function, added in Phase 6)
+- `"list"` → `core-list`, `"name"` → `core-name`, `"subs"` → `core-subs`
 
 ## Loop/recur compilation
 
-`loop*` → `(do (var name nil) (set name (fn [params] body)) (name init-vals...))`
-`recur` → `(loop-name arg...)` via `:jolt/current-loop` binding
+`loop*` emits a self-referential closure:
+```janet
+(do (var _loop_N nil)
+    (set _loop_N (fn [params] body))
+    (_loop_N init-vals...))
+```
+
+`recur` saves `:loop-name` in the AST (looked up from bindings `:jolt/current-loop`), then `emit-recur-expr` rewrites to `(loop-name arg1 arg2...)`.
+
+In the string emitter, recur similarly emits `(loop-name arg ...)`.
 
 ## Throw/try compilation
 
 - `throw` → `(error val)` in Janet
-- `try` → `(try body ([err] handler))` — Janet uses `([sym] handler)`, NOT `(catch sym handler)`
+- `try/catch` → `(try body ([err] handler-body))` — NOTE: Janet uses `([sym] handler)` format, NOT `(catch sym handler)`
+- `try/finally` → appends do-block after catch clause in the Janet tuple
 
-## Quote — use raw-form->janet
+## Quote in data-structure emitter
 
-Don't re-analyze quoted forms. Use `raw-form->janet` to pass Jolt reader forms verbatim to Janet's `quote`.
+Don't re-analyze quoted forms. Use `raw-form->janet` to pass Jolt reader forms through verbatim to Janet's `quote`:
+```
+(emit-quote-expr expr) → ['quote (raw-form->janet expr)]
+```
+raw-form->janet converts symbols to Janet symbols, arrays/tuples recursively.
 
 ## Remaining ops (interpreter only)
 
-`syntax-quote`, `set!`, `deftype`, `defmulti`, `defmethod` — stateful/complex, always use interpreter.
+`syntax-quote`, `set!`, `deftype`, `defmulti`, `defmethod` — these are stateful or complex and always use the interpreter path even in compile mode.
 
-## Stateful forms (interpreter only even in compile mode)
+## deftype in interpreter (eval-list arm)
 
-`defmacro`, `ns`, `deftype`, `defmulti`, `defmethod`, `require`, `in-ns`
+deftype creates a constructor function returning a Janet table with `:jolt/deftype` key (`"ns.TypeName"`). Evaluator `set!` handles `(.-field obj)` field mutation (reader creates `(. -field obj)` array form). `instance?` checks `:jolt/deftype` tag. defrecord macro in core.janet emits `(do (deftype Name [fields]) (def ->Name ...) (def map->Name ...))`.
 
-Note: `def` IS handled by compiler (macros expanded at analyze time).
+## Stateful forms (must use interpreter, NOT compiler)
+
+These forms modify context state and cannot be compiled:
+- `defmacro`, `ns`, `deftype`, `defmulti`, `defmethod`, `require`, `in-ns`
+- `syntax-quote`, `set!`, `var`, `.`, `new`
+
+Note: `def` IS handled by the compiler (compiles to Janet `def`, since macros are expanded at analyze time).
 
 ## eval-string dispatch (compile mode)
 
-Stateful check: `defmacro`, `ns`, `deftype`, `defmulti`, `defmethod`, `require`, `in-ns`, `syntax-quote`, `set!`, `var`, `.`, `new` → interpreter. Everything else → `compile-and-eval`.
+```janet
+(if (or (= head-name "defmacro") (= head-name "ns")
+        (= head-name "deftype") (= head-name "defmulti") (= head-name "defmethod")
+        (= head-name "require") (= head-name "in-ns")
+        (= head-name "syntax-quote") (= head-name "set!")
+        (= head-name "var") (= head-name ".") (= head-name "new"))
+  (eval-form ctx @{} form)     ; interpret
+  (compile-and-eval form ctx)) ; compile
+```
 
 ## Adding a new op
 
-1. Add `analyze-form` match arm
-2. Add `emit-ast` + `emit-expr` match arms
-3. Update `core-renames` + `core-fn-values` if core fn
-4. Add tests in `test/compiler-test.janet`
-
-## Var system (Phase 3)
-
-`var-get`, `var-set`, `var?`, `alter-var-root`, `find-var`, `alter-meta!`, `reset-meta!`, `intern` — all dispatched in evaluator, with Clojure wrappers in `core-bindings`. `find-var` takes a ctx + symbol, must eval args first (NOT pass raw form). `core-meta` handles vars via `var-meta` branch.
-
-## PersistentHashMap (Phase 2)
-
-`src/jolt/phm.janet` — separate module, bucket-based with `:jolt/deftype` tag. `core-binding` macro uses `array-map` (not `hash-map`) to avoid PHM get() incompatibility with `push-thread-bindings`.
+1. Add `analyze-form` match arm for the special form
+2. Add `emit-ast` match arm (source string path)
+3. Add `emit-expr` match arm (data structure path)
+4. Add `core-renames` entry if it's a core fn (name → Janet string name)
+5. Add `core-fn-values` entry (Janet string name → actual fn value)
+6. Add tests in `test/compiler-test.janet`
 
 ## Test files
 
-- `test/compiler-test.janet` — all compiler tests (Phases 0-3)
-- `test/phase6-final.janet` — 47 comprehensive compile-mode tests
+- `test/compiler-test.janet` — Phase 2-5 tests (source output + compile-eval + macro tests)
+- `test/phase6-final.janet` — Phase 6 comprehensive compile-mode tests (47 assertions)
 
-Run: `janet test/compiler-test.janet` or `jpm test`
+Run: `janet test/compiler-test.janet` or `janet test/phase6-final.janet` or `jpm test`