Update public docs for v0.4.0 release

- README: 1130+ vars, pprint 26/26, zone architecture, Linux verified
- ARCHITECTURE: zone overview, file paths updated to engine/lang/app
- DIFFERENCES: spec/reducers/pprint now fully implemented, 55 skipped
- CHANGELOG: v0.4.0 entry (HAMT, zone arch, coverage, CI)
- NOTICE: 68 upstream test files
- docs/compatibility: 68 upstream tests, 83 total namespaces
- docs/wasm-ffi: Wasm 3.0, 523 opcodes, zwasm JIT

Author: chaploud

.dev/memo.md

@@ -25,11 +25,11 @@ CW is a complete, optimized Zig implementation with behavioral Clojure compatibi
 
 ## Current Task
 
-None — awaiting user direction.
+v0.4.0 release — all docs updated, ready for tag.
 
 ## Previous Task
 
-Zone Cleanup Task 4: Isolate test-only imports in engine/ (12 → 0 violations).
+HAMT crash fix + CI benchmark timeout fix + full doc update for v0.4.0.
 
 ## Task Queue
 

ARCHITECTURE.md

@@ -2,6 +2,22 @@
 
 This document describes the internal architecture of ClojureWasm.
 
+## Zone Architecture
+
+CW uses a strict 4-zone layered architecture. Lower layers never import
+from higher layers. Zone dependencies are enforced by CI (0 violations).
+
+```
+Layer 0: src/runtime/   — Value, collections, GC, environment
+Layer 1: src/engine/    — Reader, Analyzer, Compiler, VM, TreeWalk
+Layer 2: src/lang/      — Built-in functions, interop, lib namespaces
+Layer 3: src/app/       — CLI, REPL, deps.edn, Wasm bridge
+```
+
+When a lower layer needs to call a higher layer, the vtable pattern
+is used (`runtime/dispatch.zig`): the lower layer defines function
+pointers that the higher layer sets during initialization.
+
 ## Pipeline Overview
 
 ClojureWasm processes Clojure source code through a four-stage pipeline:
@@ -43,7 +59,7 @@ by `EvalEngine.compare()` tests.
 
 ## Reader
 
-**Files**: `src/reader/reader.zig`, `src/reader/tokenizer.zig`, `src/reader/form.zig`
+**Files**: `src/engine/reader/reader.zig`, `src/engine/reader/tokenizer.zig`, `src/engine/reader/form.zig`
 
 The reader converts source text into a Form tree (a syntax tree before
 semantic analysis). It handles:
@@ -57,7 +73,7 @@ semantic analysis). It handles:
 
 ## Analyzer
 
-**Files**: `src/analyzer/analyzer.zig`, `src/analyzer/node.zig`
+**Files**: `src/engine/analyzer/analyzer.zig`, `src/engine/analyzer/node.zig`
 
 The analyzer transforms Forms into Nodes (an executable AST). It resolves
 variable bindings, expands macros, and compiles regex patterns at analysis
@@ -71,8 +87,8 @@ Key responsibilities:
 
 ## Compiler + VM
 
-**Files**: `src/compiler/compiler.zig`, `src/compiler/opcodes.zig`,
-`src/compiler/chunk.zig`, `src/vm/vm.zig`
+**Files**: `src/engine/compiler/compiler.zig`, `src/engine/compiler/opcodes.zig`,
+`src/engine/compiler/chunk.zig`, `src/engine/vm/vm.zig`
 
 The compiler transforms Nodes into bytecode stored in Chunks. Each
 instruction is a fixed 3-byte format: u8 opcode + u16 operand.
@@ -110,7 +126,7 @@ The VM is a stack-based machine with:
 
 ### ARM64 JIT
 
-**File**: `src/vm/jit.zig`
+**File**: `src/engine/vm/jit.zig`
 
 A proof-of-concept JIT compiler for hot integer loops on ARM64.
 
@@ -122,7 +138,7 @@ A proof-of-concept JIT compiler for hot integer loops on ARM64.
 
 ## TreeWalk Interpreter
 
-**File**: `src/evaluator/tree_walk.zig`
+**File**: `src/engine/evaluator/tree_walk.zig`
 
 The TreeWalk interpreter evaluates Nodes directly without compilation.
 It maintains a local binding stack (256 slots) and closure capture.
@@ -173,7 +189,7 @@ allocations are cached (up to 4096 blocks per pool) for O(1) reuse.
 
 ## Bootstrap
 
-**File**: `src/runtime/bootstrap.zig`
+**File**: `src/engine/bootstrap.zig`
 
 ClojureWasm uses a two-phase bootstrap:
 
@@ -193,11 +209,11 @@ in ~4ms by skipping the parse/analyze/eval cycle for core.clj.
 
 ## Wasm Runtime
 
-**Files**: `src/wasm/*.zig`
+**Files**: `src/app/wasm/*.zig`, `src/runtime/wasm_types.zig`
 
-A built-in WebAssembly interpreter supporting 461 opcodes (225 core + 236
-SIMD). Clojure code can load and call Wasm modules via the `cljw.wasm`
-namespace.
+The Wasm runtime is powered by [zwasm](https://github.com/clojurewasm/zwasm),
+supporting 523 opcodes (236 core + 256 SIMD + 31 GC). Clojure code can load
+and call Wasm modules via the `cljw.wasm` namespace.
 
 Key components:
 - **Module parser**: Decodes Wasm binary format (types, functions, tables,
@@ -207,13 +223,11 @@ Key components:
 - **VM**: Stack-based interpreter with switch dispatch over predecoded IR
 - **WASI**: File I/O, clock, random, args, environ
 - **Multi-module linking**: Cross-module function imports
-- **SIMD**: v128 type with 236 SIMD opcodes
+- **SIMD**: v128 type with 256 SIMD opcodes
+- **GC proposal**: 31 GC opcodes (struct, array, ref types)
 
-Performance: The interpreter is ~10-30x slower than wasmtime (JIT compiler)
-for compute-heavy modules. This is the fundamental interpreter-vs-JIT gap —
-wasmtime compiles Wasm to native machine code via Cranelift, while ClojureWasm
-dispatches predecoded instructions one at a time. Module load time is faster
-(~4ms vs ~5ms) since no compilation step is needed.
+Performance: zwasm uses Register IR with ARM64/x86_64 JIT compilation,
+winning 14/23 benchmarks against wasmtime with a ~43x smaller binary.
 
 ## Regex Engine
 
@@ -225,7 +239,7 @@ at runtime.
 
 ## nREPL Server
 
-**Files**: `src/repl/nrepl.zig`, `src/repl/bencode.zig`
+**Files**: `src/app/repl/nrepl.zig`, `src/app/repl/bencode.zig`
 
 A CIDER-compatible nREPL server supporting 14 operations: eval, load-file,
 complete, info, lookup, stacktrace, clone, close, describe, ls-sessions,

CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## v0.4.0 (2026-02-25)
+
+### Architecture
+- 4-zone layered architecture (D109): runtime → engine → lang → app
+- Zone dependencies enforced by CI gate (0 violations, down from 126)
+- Vtable pattern for dependency inversion (runtime/dispatch.zig)
+- HAMT (Hash Array Mapped Trie) for persistent hash maps with collision nodes
+
+### Coverage
+- 1,130/1,243 vars implemented (90.9%), 651/706 clojure.core (92.2%)
+- clojure.pprint: 26/26 (was 22/26), full cl-format support
+- clojure.spec.alpha: 87/87, clojure.spec.gen.alpha: 54/54
+- clojure.core.reducers: 22/22, clojure.datafy: 2/2, clojure.instant: 3/5
+
+### Testing
+- 83 Clojure test namespaces (68 upstream ports), all passing
+- Full Mac/Linux test symmetry (macOS aarch64 + Linux x86_64)
+- 6 e2e tests, 14 deps.edn e2e tests
+
+### Bug Fixes
+- HAMT crash when function values used as map keys (>8 entries promote to HashMap)
+- Identity hash (splitmix64) for function types replacing constant hash
+- HAMT collision node support for full 32-bit hash collisions
+
+### Performance
+- Binary: 4.76MB (ReleaseSafe)
+- Startup: ~4ms
+- RSS: ~7.6MB
+
+### CI
+- Cross-platform CI: macOS 14 + Ubuntu 24.04 + 4 cross-compile targets
+- Benchmark smoke tests with portable timeout (perl alarm)
+
 ## v0.3.0 (2026-02-20)
 
 ### Architecture v2

DIFFERENCES.md

@@ -42,41 +42,41 @@ Java standard library functionality is replaced with Zig equivalents:
 
 ## Namespaces
 
-### Not Implemented
+### Not Implemented (JVM-only)
 
 | Namespace                | Reason                               |
 |--------------------------|--------------------------------------|
-| clojure.spec.alpha       | Complexity; out of scope for alpha   |
-| clojure.spec.gen.alpha   | Depends on spec                      |
-| clojure.core.specs.alpha | Depends on spec                      |
-| clojure.core.reducers    | Requires reify + ForkJoin            |
-| clojure.core.server      | Socket REPL (nREPL used instead)     |
 | clojure.reflect          | JVM reflection                       |
 | clojure.inspector        | JVM Swing UI                         |
-| clojure.java.browse      | JVM Desktop class                    |
 | clojure.java.javadoc     | JVM-specific                         |
-| clojure.main             | JVM entry point                      |
-| clojure.instant          | JVM Date/Timestamp                   |
-| clojure.datafy           | Requires protocols not yet available |
+| clojure.test.junit       | JUnit integration                    |
 
 ### Partially Implemented
 
-| Namespace      | Done | Total | Notes                       |
-|----------------|------|-------|-----------------------------|
-| clojure.core   | 637  | 706   | 90% — see skip list below   |
-| clojure.test   | 32   | 39    | No spec integration         |
-| clojure.pprint | 9    | 26    | Core pprint + print-table   |
-| clojure.repl   | 11   | 13    | No spec, no Java reflection |
-| clojure.edn    | 1    | 2     | read-string only (no read)  |
-| clojure.data   | 3    | 5     | No protocol-based dispatch  |
+| Namespace             | Done | Total | Notes                       |
+|-----------------------|------|-------|-----------------------------|
+| clojure.core          | 651  | 706   | 92% — see skip list below   |
+| clojure.core.protocols| 10   | 11    | CollReduce, IKVReduce       |
+| clojure.core.server   | 7    | 11    | No socket REPL              |
+| clojure.instant       | 3    | 5     | No Calendar/Timestamp       |
+| clojure.java.process  | 5    | 9     | No async process            |
+| clojure.main          | 16   | 20    | REPL, script loading        |
+| clojure.repl          | 11   | 13    | No Java reflection          |
+| clojure.test          | 38   | 39    | No spec integration         |
+| clojure.xml           | 7    | 9     | Pure Clojure parser         |
 
 ### Fully Implemented
 
-clojure.string (21), clojure.set (12), clojure.math (45), clojure.walk (10),
-clojure.zip (28), clojure.template (2), clojure.stacktrace (6),
-clojure.java.io (7), clojure.java.shell (5), cljw.http (6).
+clojure.core.reducers (22), clojure.core.specs.alpha (1),
+clojure.data (5), clojure.datafy (2), clojure.edn (2),
+clojure.java.browse (2), clojure.java.io (19), clojure.java.shell (5),
+clojure.math (45), clojure.pprint (26), clojure.repl.deps (3),
+clojure.set (12), clojure.spec.alpha (87), clojure.spec.gen.alpha (54),
+clojure.stacktrace (6), clojure.string (21), clojure.template (2),
+clojure.test.tap (7), clojure.walk (10), clojure.zip (28),
+cljw.wasm (17), cljw.http (6).
 
-## Skipped clojure.core Vars (71 of 706)
+## Skipped clojure.core Vars (55 of 706)
 
 ### JVM Class System (~25 vars)
 
@@ -177,7 +177,7 @@ etc.) is not replicated; use `Exception` for general catches.
 
 ## Platform
 
-- **Verified**: macOS Apple Silicon (aarch64-macos)
-- **CI passes**: Linux x86_64, Linux aarch64
+- **Verified**: macOS Apple Silicon (aarch64-macos), Linux x86_64
+- **Cross-compiles**: Linux aarch64, macOS x86_64
 - **Not tested**: Windows, other architectures
 - **ARM64 JIT**: Only active on aarch64; no-op on other architectures

NOTICE

@@ -11,7 +11,7 @@ Clojure
   The following components are derived from upstream Clojure:
   - src/clj/ — Clojure standard library (core, set, walk, test, etc.)
     with UPSTREAM-DIFF modifications for the Zig runtime
-  - test/upstream/clojure/ — Ported test suite (39 files)
+  - test/upstream/ — Ported test suite (68 files)
 
 SCI (Small Clojure Interpreter)
   Copyright (c) Michiel Borkent. All rights reserved.

README.md

@@ -11,8 +11,8 @@
 > behavioral differences from reference Clojure. Bugs and rough edges are
 > expected. See [DIFFERENCES.md](DIFFERENCES.md) for details.
 >
-> **Verified on**: macOS (Apple Silicon / aarch64). Linux x86_64 and
-> aarch64 builds pass CI but have not been extensively tested.
+> **Verified on**: macOS (Apple Silicon / aarch64) and Linux (x86_64).
+> Cross-compiles to aarch64-linux. All test suites pass on both platforms.
 
 A Clojure runtime written from scratch in Zig. No JVM, no transpilation —
 a native implementation targeting behavioral compatibility with Clojure.
@@ -25,7 +25,7 @@ a native implementation targeting behavioral compatibility with Clojure.
 - **Wasm FFI** — call WebAssembly modules from Clojure (523 opcodes including SIMD + GC)
 - **Dual backend** — bytecode VM (default) + TreeWalk interpreter (reference)
 - **deps.edn compatible** — Clojure CLI subset (-A/-M/-X/-P, git deps, local deps)
-- **1100+ vars** across 30+ namespaces (651/706 clojure.core)
+- **1130+ vars** across 30+ namespaces (651/706 clojure.core)
 
 ## Getting Started
 
@@ -131,7 +131,7 @@ Known divergences are documented in [DIFFERENCES.md](DIFFERENCES.md).
 | clojure.test       | 38/39  | Test framework                 |
 | clojure.test.tap   | 7/7    | TAP output formatter           |
 | clojure.repl       | 11/13  | doc, dir, apropos, source, pst |
-| clojure.pprint     | 22/26  | Pretty printing, print-table   |
+| clojure.pprint     | 26/26  | Pretty printing, print-table   |
 | clojure.stacktrace | 6/6    | Stack trace utilities          |
 | clojure.main       | 16/20  | REPL, script loading, ex-triage|
 
@@ -220,25 +220,26 @@ src/
 │   ├── core.clj                Core library (~2400 lines)
 │   └── string.clj, set.clj... Standard library namespaces
 │
-├── reader/                     Stage 1: Source → Form
-├── analyzer/                   Stage 2: Form → Node
-├── compiler/                   Stage 3: Node → Bytecode
-├── vm/                         Stage 4a: Bytecode execution (+ JIT)
-├── evaluator/                  Stage 4b: TreeWalk interpreter
-│
-├── runtime/                    Core types, GC, environment
-├── builtins/                   Built-in functions (27 modules)
-├── regex/                      Regex engine
-├── repl/                       nREPL server, line editor
-└── wasm/                       WebAssembly runtime (523 opcodes)
+├── runtime/                    Layer 0: Value, collections, GC, environment
+├── engine/                     Layer 1: Reader, Analyzer, Compiler, VM, TreeWalk
+│   ├── reader/                   Source → Form
+│   ├── analyzer/                 Form → Node
+│   ├── compiler/                 Node → Bytecode
+│   ├── vm/                       Bytecode execution (+ ARM64 JIT)
+│   └── evaluator/                TreeWalk interpreter
+├── lang/                       Layer 2: Built-in functions, interop, lib namespaces
+├── app/                        Layer 3: CLI, REPL, deps.edn, Wasm bridge
+└── regex/                      Regex engine
 
 bench/                          31 benchmarks, multi-language
-test/                           81 Clojure test files (54 upstream ports)
+test/                           83 Clojure test namespaces (54 upstream ports)
 ```
 
+Strict 4-zone layered architecture: lower layers never import from higher layers.
+Zone dependencies enforced by CI gate (0 violations).
+
 The [`.dev/`](.dev/) directory contains design decisions, optimization logs,
-and development notes. Some may be outdated, but may interest those curious
-about how the project evolved.
+and development notes.
 
 ## Benchmarks
 
@@ -260,14 +261,14 @@ bash test/e2e/run_e2e.sh       # End-to-end tests (6 wasm)
 bash test/e2e/deps/run_deps_e2e.sh  # deps.edn E2E tests (14)
 ```
 
-81 Clojure test files including 54 upstream test ports with 600+ deftests.
+83 Clojure test namespaces including 54 upstream test ports with 600+ deftests.
 All tests verified on both VM and TreeWalk backends.
 
 ## Future Plans
 
 - **JIT expansion** — float operations, function calls, broader loop patterns
 - **Generational GC** — nursery/tenured generations for throughput
-- **Persistent data structures** — HAMT/RRB-Tree implementations
+- **Persistent data structures** — RRB-Tree for vectors (HAMT for maps: done)
 - **wasm_rt** — compile Clojure to run *inside* WebAssembly
 
 ## Potential Use Cases

docs/compatibility.md

@@ -107,7 +107,8 @@ Vars that are defined but have limited or no-op behavior:
 
 ## Upstream Test Coverage
 
-63 upstream test files (62 passing, 1 failing: test_fixtures.clj).
+68 upstream test files, all passing.
+83 Clojure test namespaces total (68 upstream + 15 CW-specific).
 146 differential test expressions (CW vs JVM), all passing.
 6 core e2e tests, 14 deps.edn e2e tests.
 

docs/wasm-ffi.md

@@ -237,7 +237,8 @@ are caught and reported as CW runtime errors:
 
 ## Wasm Engine
 
-CW uses [zwasm](https://github.com/clojurewasm/zwasm) v1.1.0 as its Wasm runtime:
-- WebAssembly 2.0 (100% spec compliance, 62K tests)
-- ARM64 and x86_64 JIT compilation
+CW uses [zwasm](https://github.com/clojurewasm/zwasm) as its Wasm runtime:
+- Full Wasm 3.0 support (all 9 proposals including GC, function references, SIMD, exception handling)
+- 523 opcodes (236 core + 256 SIMD + 31 GC)
+- Register IR with ARM64/x86_64 JIT compilation
 - WASI preview1 support