Master list of all known bugs, workarounds, stubs, and design concerns. Ordered by resolution priority. Referenced from roadmap.md and memo.md.
- P0 (Block): User-facing bugs. Fix before any new feature work.
- P1 (High): Development infrastructure. Fix to prevent future regressions.
- P2 (Medium): Correctness gaps. Fix during related phase work.
- P3 (Low): Design debt. Address in dedicated cleanup phases.
Resolution: Fresh Env per test file in handleTestCommand (88C.1).
Each file gets: shutdownGlobalPool() → resetLoadedLibs() → Env.init() → bootstrapFromCache().
Also fixed missing (ns ...) forms in clojure_walk.clj, sci/core_test.clj, sci/hierarchies_test.clj
that relied on leaked state.
Resolution: Already fixed — code uses @truncate (not @intCast), which
naturally applies & 0x3f masking. Verified: (bit-shift-left 1 64) → 1, no panic.
Resolution: CW behavior was correct (JVM: (char 65) → \A, not "A").
Test expectations in numbers.clj were wrong — fixed to compare with char literals.
Also fixed (char \A) → identity (was erroring "Cannot cast char to char").
Resolution: Created test/run_all.sh — runs all 5 suites (zig test, release build,
cljw test, e2e, deps e2e) with unified summary. CLAUDE.md commit gate updated.
Resolution: Changed all 5 catch {} in runTry to catch |fe| return fe,
propagating finally-block exceptions per JVM semantics. If finally throws,
its exception replaces the original (matching Java/JVM Clojure behavior).
Files: src/engine/evaluator/tree_walk.zig (runTry function)
Resolution: Validator now propagates UserException (JVM re-throws RuntimeException); other errors still convert to InvalidState. Watch callbacks in atom.zig, stm.zig, and agent error handler in thread_pool.zig documented as matching JVM behavior (Atom.java/ARef.java catch silently).
Files: src/lang/builtins/atom.zig, src/runtime/stm.zig, src/runtime/thread_pool.zig
Resolution: The catch {} instances in bootstrap.zig were eliminated during
earlier refactoring (R5/R6 bootstrap decomposition). The bootstrap module no longer
contains silent catch {} for refer operations.
Resolution: Added meta_value: ?Value field to Form struct for carrying metadata
through valueToForm → transform → formToValue roundtrips. valueToForm now preserves
metadata from symbols and lists. formToValue re-attaches metadata. threadForm in
macro_transforms.zig preserves meta_value on new list Forms. 8/8 macros tests now pass.
Symptom: r/fold falls back to sequential reduce. No parallel folding.
ForkJoin stubs (fjtask/fjfork/fjjoin) are all no-ops.
Fix: Implement a thread-pool-based fold (CW has thread_pool.zig). Replace ForkJoin stubs with actual parallel execution.
Phase: Phase B.13 (reducers → Zig) or Phase 89 (Performance)
Symptom: Core spec ops work (valid?, conform, def, and, or, keys)
but fdef, instrument, generators, and most complex specs fail.
Fix: Complete spec implementation during Phase B.15 (spec → Zig).
Phase: Phase B.15
Resolution: Replaced @intCast with @bitCast for both store
(@intFromPtr → i64) and load (asInteger → usize) in all 4 interop
class files. Prevents panic on high-bit pointers.
Files: src/lang/interop/classes/{string_writer,pushback_reader,string_builder,buffered_writer}.zig
Resolution: Replaced double @intCast with @truncate for i32 narrowing
in wasm bridge (valueToWasm and callback return). @truncate wraps instead of
panicking, matching wasm's wrapping semantics for i32.
Files: src/app/wasm/types.zig
Symptom: Each marker represents a behavioral deviation from JVM Clojure. Categories:
- Java exception → ex-info rewrites (zip, spec, test): ~30
- Java stream/IO → CW native (io, main, pprint): ~40
- Java type system → cond/predicate dispatch (data, walk): ~15
- ForkJoin → sequential (reducers): ~12
- Java class interop → stubs (server, repl.deps): ~10
- pprint Writer proxy → atom-based (pprint): ~30
- spec JVM-specific → simplified (spec): ~30
Resolution: Most will be resolved organically during Phase B (each .clj → Zig). Markers in F94 (checklist.md) track the "R" category that requires infrastructure.
Symptom: Vars marked done in vars.yaml but are actually stubs (return nil
or throw). Examples: *err*, *in*, *out*, start-server, add-lib.
Fix: Either implement properly or change status to skip with clear note.
*err*/*in*/*out* need CW I/O stream design (Phase 89 or dedicated phase).
Symptom: clojure.core.server and clojure.repl.deps throw on every call.
Resolution: server requires Zig networking (Phase 93 LSP or dedicated). repl.deps requires runtime deps loading (low priority for CW).
Symptom: Current transform system only handles clojure.core macros.
Non-core .clj macros (test/do-template, main/with-bindings) need defmacro.
Phase B must either:
(a) Implement namespace-scoped transforms, or
(b) Convert defmacros to Zig builtin functions with setMacro(true)
Resolution: Design decision needed at Phase B start.
Symptom: initDeferredCacheState copies strings to smp_allocator to
prevent GC collection. This is a workaround for the real issue (GC doesn't
know about deferred cache roots).
Resolution: Will be eliminated in Phase C (bootstrap pipeline removal).
| Issue | When to Fix | Phase |
|---|---|---|
| I-001 | 88C.1 | |
| I-002 | pre-88C | |
| I-003 | 88C.3 | |
| I-010 | 88C.4 | |
| I-011 | R12 | |
| I-012 | R12 | |
| I-013 | R5/R6 | |
| I-020 | B.3 hotfix | |
| I-021 | Phase B.13 or 89 | B.13 / 89 |
| I-022 | Phase B.15 | B.15 |
| I-023 | R12 | |
| I-024 | R12 | |
| I-030 | Phase B (organically) | B |
| I-031 | Phase B + Phase 89 | B / 89 |
| I-032 | Phase 93 / never | 93 |
| I-033 | Phase B start | B.0 (design decision) |
| I-034 | Phase C | C |