C64-dev/newLang/planning/claims/E05-S01.md

---

story: E05-S01 owner: e05_heap status: done started: 2026-11-09 depends-on: [E04-S05, E01-S05]

E05-S01 Claim

Intended change

Add a deterministic free-list heap for generated programs. heap_init accepts an explicit page-aligned base and page count, so heap placement remains independent of the still-open generated-program map. Blocks use a four-byte header (total size with bit 15 allocated, and a next pointer that is a magic value while allocated), two-byte payload alignment, first-fit allocation with splitting, payload zeroing, address-ordered free insertion, and coalescing. heap_free validates range, size, the used magic, and double-free; validation is always on rather than a separately compiled debug build. A bounded x128 fixture exercises allocation, zeroing, splitting, coalescing, a multi-block stress pass, double-free and corrupt-header detection, and exhaustion without damaging live allocations. The fixture maps exhaustion to stable R005 through flt_report; wiring new to the heap is E05-S03.

File area

• src/runtime/heap.s, src/common/heap.inc (new)
• tests/runtime/heap-test.s (new)
• scripts/build-heap-test.ps1, scripts/verify-heap-test.ps1 (new)
• docs/decisions.md, docs/architecture.md, docs/memory-map.md
• planning/claims/E05-S01.md
• generated files under build/heap-test/

Acceptance evidence

• Allocates, zeroes, frees, splits, and coalesces blocks deterministically.
• Heap exhaustion faults without corrupting allocated blocks.
• Debug mode detects representative double-free/corrupt-header cases.
• Stress test returns the heap to its initial free capacity.

Coordination notes

• E04-S05 and E01-S05 are complete; E04-S04/S05 remain uncommitted and are not discarded or modified.
• The generated-program heap location is still open. This story supplies the allocator and a test instance at bank-0 $4000-$4FFF under CR $0E, not a final generated-program map.
• D133 records the provisional block/API contract. The allocator returns HEAP_ERR_* on exhaustion; the test calls flt_report to demonstrate the stable R005 path, while E05-S03 owns new integration.

Work log

• Selected E05-S01 as the next dependency-complete story after E04-S05.
• Added heap.s/heap.inc with an explicit page-granular region, first-fit splitting, payload zeroing, sorted free insertion, coalescing, and always-on validation.
• Added the 4K x128 fixture at $4000-$4FFF; code ends at $28C4.
• First build exposed ca65 range errors on the far error paths; converted them to inverted short branches plus JMP.
• The first run failed phase 2 because heap_zero branched to its tail path before loading A=0, so payload bytes were not zeroed. Fixed by loading A=0 at the tail entry, then reran successfully.

Completion

• Tests run:
  • scripts/build-heap-test.ps1 (link ends at $28C4)
  • scripts/verify-heap-test.ps1 (x128 3.10)
  • git diff --check
• Results: the fixture reports producer 3, status $FA, code 5, address $4000, and all eight phase flags 01; the screen shows NOVA128 HEAP TEST, HEAP OK, RUNTIME FAULT R005. It verified allocation, zeroing, first-fit splitting, sorted insertion, repeated coalescing, the 16-block stress/free cycle, double-free rejection, corrupt-magic rejection, exhaustion without damaging live patterns, and return to 4096 free bytes.
• Files changed: src/runtime/heap.s, src/common/heap.inc, tests/runtime/heap-test.s, scripts/build-heap-test.ps1, scripts/verify-heap-test.ps1, docs/decisions.md, docs/architecture.md, docs/memory-map.md, this claim.
• Remaining risks: production generated-program heap placement is still open; the canonical region is 4K and uses 15-bit block sizes; validation is always on (no release/debug toggle); fragmentation is solved by first-fit plus coalescing but no worst-case performance bound is measured. HEAP_ERR_OOM is returned to the caller, not automatically reported; E05-S03 owns the new/R005 integration. Banked heaps remain deferred.