Finish chapter numbering, retire combined chapter 24, and update documentation

5 files changed, 187 insertions, 0 deletions

diff --git a/docs/appendices/README.md b/docs/appendices/README.md
new file mode 100644
index 00000000..d7803c97
--- /dev/null
+++ b/docs/appendices/README.md
@@ -0,0 +1,15 @@
+# Appendices
+
+These notes supplement the numbered compiler snapshots; they do not introduce
+another compiler directory.
+
+- [Native library construction](native-libraries.md): bundled `sys`, native
+  symbols and thunks, runtime support, and executable examples in Chapter 28b.
+- [Optimizer and backend tuning](optimizer-tuning.md): spill ranking,
+  rematerialization, inlining, and historical measurements from the split's
+  original snapshots. [Measurement methods](../regalloc-spills.md) describe
+  what those numbers include.
+
+The [roadmap](../roadmap.md), [incremental build design](../incremental-builds.md),
+and [review queue](../chapter-backports.md) distinguish future work from current
+behavior. The [stage audit](../stage-audit.md) records known limits and cleanup.
diff --git a/docs/appendices/current-spill-matrix.md b/docs/appendices/current-spill-matrix.md
new file mode 100644
index 00000000..df253a46
--- /dev/null
+++ b/docs/appendices/current-spill-matrix.md
@@ -0,0 +1,14 @@
+# Current allocator comparison
+
+`make spill-stats` measures Chapters 20, 21, 22, 23, 24b, and 28b against the
+historical test cohorts. Cohort IDs and test names retain their old numbers;
+column headings identify the current compiler directories.
+
+These are separate from the dated [pre-split measurements](../regalloc-spills.md).
+After a successful run, `python build-support/spill-matrix.py --reuse --update-docs`
+updates only this table. Fresh logs use 24b/28b names so old 24/25 results cannot
+silently become measurements of new compiler snapshots.
+
+<!-- spill-matrix:start -->
+No post-split measurement has been published yet.
+<!-- spill-matrix:end -->
diff --git a/docs/appendices/native-libraries.md b/docs/appendices/native-libraries.md
new file mode 100644
index 00000000..14cf0c6b
--- /dev/null
+++ b/docs/appendices/native-libraries.md
@@ -0,0 +1,67 @@
+# Native library construction
+
+The complete compiler is [Chapter 28b](../../chapter28b/README.md). This appendix
+collects the library and native support that accompanied the old combined
+Chapter 25. The split preserves that functionality in Chapter 28b.
+
+## Building the library
+
+From `chapter28b`, run:
+
+```sh
+make lib release
+```
+
+Make builds `build/release/Simple.jar` and, under the selected CPU/ABI directory,
+`sys.o` and `simple_crt.o`. The default CPU is x86-64; the default calling
+convention is win64 on Windows and SystemV elsewhere. Rebuild serialized
+objects after changing the compiler or object format.
+
+`src/main/smp/sys.smp` exposes child units for native libc bindings, I/O,
+characters, scanners, arrays, growable buffers, and bitsets. These compile into
+one `sys.o`. Clients import its declarations and ideal IR and link calls that
+remain out of line. Currently selecting that object loads all its saved IR;
+member-selective loading and reliable incremental rebuilding remain future work.
+
+The `simple.sh`, `simple.ps1`, and `simple.bat` launchers set `SIMPLE_HOME` so
+the compiler can find the release library. The CLI accepts `-L` for additional
+Simple objects or search directories. The chapter README gives an explicit
+library/client example that needs no library source in the client root.
+
+## Native symbols and pointer sizes
+
+Native function calls and numeric native data symbols have ELF relocations.
+The historical `Chapter25Test.testExternDataEncoding` and `testExternDataImports`
+exercise native data; `StaticDataTest` covers addresses
+and static images. A data symbol names storage, whereas a function symbol names
+callable code; loading the former and calling the latter require different IR.
+
+Simple function pointers currently occupy four bytes. On AMD64, a native
+function address names a low-address tail-jump thunk, which can reach native
+code outside that range. A weak symbol gives static fields and computed
+addresses the same entry across objects; direct calls can still use the native
+PLT. This preserves constant initialization of function fields without storing
+an eight-byte native address in a four-byte slot. The native linker must place
+these Simple entries in the representable address range.
+
+Data pointers still occupy eight bytes. Compact code/data arenas and distinct
+full-width native pointer types are [future designs](../roadmap.md#compact-code-and-data-arenas).
+
+## Runtime and examples
+
+`src/main/c/simple_crt.c` supplies the errno accessor and converts native process
+arguments to Simple byte arrays for an exported `simple_main` function. This
+explicit function entry is distinct from the language's class initializer:
+the selected initializer still receives the integer `arg`. General class
+initializer argument arrays remain a roadmap item.
+
+The executable examples live in
+[`src/test/smp/examples`](../../chapter28b/src/test/smp/examples): Hello World,
+Bubble Sort, Capitalize, Dijkstra, and FileIO. The existing Chapter25Test tests
+compile and link them through the native harness. `make tests` builds the
+library/runtime prerequisites and runs those checks; a Java-only build does
+not produce the native prerequisites.
+
+The compiler's in-memory evaluator and the native driver have different entry
+interfaces. Use the matching harness when comparing their results, especially
+for programs taking an argument array or performing I/O.
diff --git a/docs/appendices/optimizer-tuning.ja.md b/docs/appendices/optimizer-tuning.ja.md
new file mode 100644
index 00000000..96c1b130
--- /dev/null
+++ b/docs/appendices/optimizer-tuning.ja.md
@@ -0,0 +1,26 @@
+# 最適化とバックエンドの調整
+
+These measurements are from the numbered snapshots before the 2026-10 split.
+In this historical table, Ch 24 means the retired combined SCCP snapshot and
+Ch 25 means the retired combined modules/constructor/import snapshot.
+They are not new measurements of the extracted chapters. The implementation
+continues in [Separate Compilation](../../chapter28b/README.md).
+
+## RegAlloc の改良: 生存区間の面積と分割コスト
+
+第24章はループ Phi の高頻度辺を分割する前に、低頻度のコピーを試しました。この章ではさらに、スピルがスケジュール済みコードのどれだけをレジスタ圧力から解放するかを推定し、新しいコピーの推定コストで割ります。callee-save 区間は関数全体を覆います。複製可能な定数は使用の近くで再構築できます。ループ内のコピーは高コストなので、`8^loopDepth` で重み付けします。特に多数の使用を持つ値については、低コストな近似です。
+
+複数の固定レジスタ使用を直接分割する規則や、一部の複数定義区間をより深く分割する規則など、第25章のほかの衝突処理はここに残します。サイズのしきい値はヒューリスティックであり、最初の割り当て器へバックポートすべき一般的不変条件ではありません。共有される合法性修正は、引き続き最も早い該当章から始めます。最終監査は第20〜25章の固定隣接ノードの色バイアス、第20〜21章の狭いストアマスク、第21〜25章の ARM レジスタバンク／浮動小数点メモリエンコーディングを修正しました。
+
+第21章の隣接コピー転送も引き継ぎます。次の命令だけで使うコピーは、オペランドがコピー元レジスタを受け入れ、命令の結果に結び付けられていなければ除去します。
+
+現在の比較は、固定したテスト群を行、コンパイラの章を列にした
+[英語版の測定表](optimizer-tuning.md#regalloc-improvements-live-range-area-and-split-cost) を参照してください。
+各セルは ARM/RISC-V の実行命令数、そのうち割り当て器が生成したコピーなどの命令数、
+x86 のループ重み付き移動数を示します。これらは異なる指標です。
+対象、入力、除外項目は [測定方法](../regalloc-spills.md) にあります。
+古い測定群の集計値と混ぜて比較しないでください。
+
+クラス初期化、インライン化、エスケープ解析、ライブラリの変更もグラフを変えます。
+章をまたぐ差を割り当て器だけの品質差と解釈せず、同じ入力とコンパイラで
+ヒューリスティックを比較してください。
diff --git a/docs/appendices/optimizer-tuning.md b/docs/appendices/optimizer-tuning.md
new file mode 100644
index 00000000..11dbcdf3
--- /dev/null
+++ b/docs/appendices/optimizer-tuning.md
@@ -0,0 +1,65 @@
+# Optimizer and backend tuning
+
+These measurements are from the numbered snapshots before the 2026-10 split.
+In this historical table, Ch 24 means the retired combined SCCP snapshot and
+Ch 25 means the retired combined modules/constructor/import snapshot.
+They are not new measurements of the extracted chapters. The implementation
+continues in [Separate Compilation](../../chapter28b/README.md).
+
+## RegAlloc improvements: try cold loop splits first
+
+A loop Phi and its backedge can belong to one live range even though their
+values must coexist at some instruction.  This self-conflict requires splitting
+the range.  Chapter 23 split the Phi's definition and incoming values right away.
+This chapter first leaves the hot definition/backedge alone and tries the
+outside-loop copies.  If coloring succeeds, it avoids moves on every iteration.
+Other conflicts, including two-address operations, keep their existing handling.
+
+The allocator remembers which Phis have had this chance.  If the same Phi
+self-conflicts again, the next attempt uses the ordinary aggressive splitting.
+The record uses Phi identity because live ranges are rebuilt each round.  It
+also covers a backedge-only conflict where the first attempt inserts no copy:
+that attempt must still consume the one permitted delay.  A regression checks
+both the cheaper first attempt and the mandatory fallback.
+
+## RegAlloc improvements: live-range area and split cost
+
+Chapter 24 tried cold copies before splitting a loop Phi's hot edges.  This
+chapter also estimates how much scheduled code a spill frees from register
+pressure, divided by the estimated cost of the new copies.  Callee-save ranges
+cover a whole function.  Cloneable constants can be rebuilt nearer their uses.
+Copies inside loops cost more: the estimate weights them by `8^loopDepth`.
+These are inexpensive approximations, especially for values with many uses.
+
+A single-use function address in the same block gets priority for
+rematerialization when it is separated from its use.  Moving that address
+calculation next to the use adds no instruction and avoids preserving a
+callee-save register merely to hold the constant.  Adjacent uses and multi-use
+addresses retain the area/cost ranking.
+
+Rows are fixed test cohorts; columns are compiler chapters. Each cell gives
+**Ops / RA / X**: executed ARM+RISC-V instructions, the subset emitted for
+allocator copies/rematerializations, and x86's loop-weighted split-move estimate.
+**Cases D / X** counts measured dynamic program/target cases and x86 compilations;
+membership and inputs stay fixed across columns. Native-library work is excluded.
+Chapter 20 has no encoder, hence no dynamic counts. Lower is better within each
+metric; see the [measurement details](../regalloc-spills.md) for coverage.
+
+<!-- spill-matrix:start -->
+| Test cohort | Cases D / X | Ch 20: Ops / RA / X | Ch 21: Ops / RA / X | Ch 22: Ops / RA / X | Ch 23: Ops / RA / X | Ch 24: Ops / RA / X | Ch 25: Ops / RA / X |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| Ch 20 | 22 / 13 | — / — / 161 | 55,173 / 5,407 / 174 | 58,751 / 9,099 / 175 | 58,736 / 9,084 / 184 | 58,720 / 9,068 / 183 | 58,965 / 9,076 / 208 |
+| Ch 21 | 20 / 18 |  | 6,207 / 261 / 461 | 6,324 / 379 / 475 | 6,326 / 381 / 475 | 6,325 / 380 / 470 | 6,196 / 219 / 534 |
+| Ch 22 | 14 / 8 |  |  | 198 / 60 / 7 | 194 / 56 / 7 | 194 / 56 / 7 | 252 / 92 / 11 |
+| Ch 23 | 14 / 8 |  |  |  | 630 / 160 / 36 | 630 / 160 / 36 | 864 / 358 / 36 |
+| Ch 24 | 36 / 20 |  |  |  |  | 4,923 / 1,341 / 790 | 4,646 / 1,335 / 609 |
+| Ch 25 | 2 / 12 |  |  |  |  |  | 20 / 0 / 1,856 |
+<!-- spill-matrix:end -->
+
+
+Chapter 25 introduces several features, which when run on the older tests
+generate a lot more code, which in turn generates more spills.
+
+Class initialization, inlining, escape analysis, and library adaptations
+all change the graphs.  To help with this, we adjust the inlining
+heuristics to try to inline and optimize the boilerplate.