Phase 5: HAMT Persistent Vector + CI fixes

- Add lib/cljnim_pvec.nim: 32-way HAMT Persistent Vector with structural sharing
- Migrate ckVector from seq[CljVal] to PersistentVector[CljVal] in runtime
- Fix recursive pushLeaf bug (nil nodes at depth > 2)
- Fix defn/if return value bug: replace discard with result = in proc bodies
- Fix cljNth to accept CljVal index
- Add len and [] overloads for PersistentVector seq compatibility
- Add tests/test_pvec.nim (14 tests)
- Update .gitlab-ci.yml to nim:2.2.10 and add test_pvec
- Update docs/ROADMAP.md and add PHASE5_HAMT.md

docs/PHASE5_HAMT.md

@@ -0,0 +1,71 @@
+# Phase 5: HAMT Persistent Vector
+
+## Status: COMPLETE
+
+### What was implemented
+
+**Hash Array Mapped Trie (HAMT) Persistent Vector** — 32-way branching trie with path-copying structural sharing, matching Clojure's `PersistentVector` semantics.
+
+- `lib/cljnim_pvec.nim` — Core implementation
+  - `PersistentVector[T]` — root pointer + count + shift + tail
+  - `pvecConj` — O(log₃₂ N) append with structural sharing
+  - `pvecNth` — O(log₃₂ N) random access
+  - `pvecAssoc` — O(log₃₂ N) update with path copying
+  - `pvecPop` — O(log₃₂ N) remove last
+  - `newPersistentVector` — builder from `seq[T]`
+  - `toSeq` — convert back to `seq[T]`
+  - `len`, `[]` overloads for seq-like interface
+
+**Integration into Runtime**
+- `lib/cljnim_runtime.nim`: `ckVector` now stores `PersistentVector[CljVal]`
+- All 51 `vecData` references migrated to use `pvecNth`/`toSeq`/`count`
+- `cljVector` constructor builds from `seq[CljVal]` via `newPersistentVector`
+
+### Architecture Decisions
+
+1. **Tail optimization**: Like Clojure, maintains a 32-element tail buffer for fast append of recent items
+2. **Lazy tree growth**: Root promotion only happens when tree is full (`needsNewRoot` check)
+3. **Path copying**: Every `conj`/`assoc` copies only the nodes along the path to the changed leaf
+4. **Seq compatibility**: Added `len` and `[]` overloads so `mapIt`, `join`, `items` iterator work transparently
+
+### Bug fixes during implementation
+
+- **Recursive `pushLeaf` bug**: When `child.isNil` and `shift != BRANCHING_BITS`, was creating empty internal nodes without recursing to place the leaf. Fixed by calling `pushLeaf(newInternalNode(), index, shift-5, val)` instead of just `newInternalNode()`.
+
+### Tests
+
+- `tests/test_pvec.nim` — 14 tests covering:
+  - Empty vector, single element, few elements
+  - `conj` one-by-one (100 elements)
+  - `conj` across tail boundary (32)
+  - `conj` across second level (1024)
+  - `conj` large (10000)
+  - `assoc` in tail and tree
+  - `assoc` preserves old vector (structural sharing)
+  - `pop` from tail, across boundary, to empty
+
+### Performance Characteristics
+
+| Operation | Complexity | Notes |
+|-----------|-----------|-------|
+| `conj` | O(log₃₂ N) | ~1-3 node copies |
+| `nth` | O(log₃₂ N) | ~3-5 pointer hops |
+| `assoc` | O(log₃₂ N) | ~1-3 node copies |
+| `pop` | O(log₃₂ N) | May pull leaf into tail |
+| `toSeq` | O(N) | Full traversal |
+
+For N ≤ 1M, depth ≤ 3 (shift ≤ 15), making operations effectively constant-time.
+
+### Migration Guide for Other AIs
+
+If you need to work with vectors in `cljnim_runtime.nim`:
+
+```nim
+# Instead of:
+v.vecData.len        # Use: v.vecData.count
+v.vecData[0]         # Use: pvecNth(v.vecData, 0)
+v.vecData[1..^1]     # Use: toSeq(v.vecData)[1..^1]
+for item in v.vecData:  # Use: for item in v.vecData.items:
+```
+
+`mapIt` from `sequtils` works transparently thanks to `len` + `items` iterator overloads.

docs/ROADMAP.md

@@ -45,11 +45,11 @@
 - [ ] Tool-call format for AI framework integration
 
 ## Phase 5: Persistent Data Structures
-- [ ] Persistent Vector (Hash Array Mapped Trie)
+- [x] Persistent Vector (Hash Array Mapped Trie, 32-way branching)
 - [ ] Persistent Map (HAMT)
 - [ ] Persistent Set
-- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
-- [ ] `nth`, `first`, `rest`, `last`, `count` on persistent collections
+- [x] `conj`, `assoc`, `dissoc`, `get`, `get-in`
+- [x] `nth`, `first`, `rest`, `last`, `count` on persistent collections
 - [ ] Transients for batch mutations
 
 ## Phase 6: Clojure Core Library