commit 8a62b039948dd58bcedd08fe1e1c654900c39154
parent f74017622a562616c2b1993be427593e9a227220
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Wed, 22 Apr 2026 01:33:56 -0700
LISP-GC.md: add "Remaining work" checklist
Captures the outstanding items so the next pass at this code picks
them up without re-deriving: doc sync with LISP.md / P1.md, the two
stress tests still missing from the doc's step-5 set (vector-churn
exercises the >128-byte coalesce path, mixed exercises concurrent
pair+obj GC), a mark-stack-overflow test, and the explicitly
deferred items (heap size bump, tail rewind, precise-GC upgrade)
plus leak-rate instrumentation to turn the "conservative fallback
is cheap in practice" claim from assumption into measurement.
Diffstat:
| M | docs/LISP-GC.md | | | 69 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 69 insertions(+), 0 deletions(-)
diff --git a/docs/LISP-GC.md b/docs/LISP-GC.md
@@ -467,3 +467,72 @@ Rough total: ~700 P1 LOC + ~150 Py LOC + 5 test files.
can overwrite a live object with a free-list link. Mitigation:
stress tests `17` and `21` allocate + read back; any corruption
surfaces as a crash or wrong checksum.
+
+## Remaining work
+
+Tracked here so the next pass at this code can pick them up without
+re-deriving the list.
+
+### Doc sync (blocks "step 13 complete")
+
+- [ ] `docs/LISP.md` decision 11: rewrite from "single bitmap over
+ whole heap" to "pair-arena bitmap + object `gc-flags` byte;
+ two segregated arenas."
+- [ ] `docs/LISP.md` §Heap layout: replace the single-arena
+ description with the pair/obj split and the runtime-aligned
+ `:pair_heap_base` / `:obj_heap_base` snapshots.
+- [ ] `docs/LISP.md` §GC §Roots: drop the conservative-stack-filter
+ language; replace with the fp-chain walker + bounded-
+ conservative-on-stack description (cross-ref §"Why
+ mostly-precise" here).
+- [ ] `docs/LISP.md` §GC §Algorithm: replace the single-walk
+ description with the per-arena sweep (bitmap-driven pair
+ sweep, header-stride object sweep, free-list population,
+ coalescing).
+- [ ] `docs/P1.md` §Semantics prologue/epilogue/TAIL: new frame
+ shape with `saved_fp` at `[sp+8]` and `k` at `[sp+16]`;
+ updated frame-size formula; note that PROLOGUE_Nk zeros
+ each slot (cross-ref LISP-GC.md §"Per-arch implementation").
+ Flag the aarch64 MOVZ-over-ADD detail as a load-bearing
+ encoding gotcha.
+
+### Stress tests to reach the doc's step-5 set
+
+- [ ] Rename current `19-gc-closure-churn.scm` → `20-gc-closure-
+ churn.scm` so numbering matches the plan in §Implementation
+ sequence.
+- [ ] Add `19-gc-vector-churn.scm`. Currently the `>128`-byte
+ coalescing path in `gc_sweep_obj` has *zero* test coverage;
+ a loop that allocates and drops vectors of varying sizes
+ (including some `>128` bytes) would hit it.
+- [ ] Add `21-gc-mixed.scm`. Interleaves pair/vector/string/closure
+ allocations so pair and obj GC cycles overlap.
+- [ ] Rework `18-gc-deep-list.scm` (or add a companion test) to
+ force the mark-stack-overflow recursive-`CALL mark_value`
+ fallback. The current test is tail-recursive so the mark
+ stack stays shallow; a non-tail-recursive build of a deep
+ reachable list would actually exercise the overflow path.
+
+### Deferred by explicit decision (revisit under load)
+
+- [ ] Grow heap from the current bring-up 32 KB + 32 KB to the
+ decision-4 size of 1 MB (pair) + 400 KB (obj), and
+ eventually 20 MB total once the C-compiler workload lands.
+ Keep the tiny bring-up sizes until then so GC stays cheap
+ to trigger in tests.
+- [ ] Optional tail-rewind of `pair_heap_next` / `obj_heap_next`
+ during sweep. Marked optional; only land if fragmentation
+ shows up under load.
+- [ ] Upgrade mostly-precise → fully precise via two slot counts
+ per frame (`k_tagged` + `k_raw`). Documented in §"Why
+ mostly-precise" as the upgrade path; only land if leak
+ measurement (next item) shows the conservative fallback
+ pinning real memory.
+
+### Unmeasured invariants
+
+- [ ] Instrument leak rate: count live pairs / objects retained
+ after each sweep over a churn workload. Today's claim that
+ "false marks from the bounded-conservative stack scan are
+ rare in practice" is unverified; a single counter would
+ either close the concern or trigger the precise upgrade.
