Record the inlining and unrolling assessment as the dispatch-count lever

INLINING.md grounds the assessment in the profiling numbers: call ceremony is
plausibly ten to twenty percent of dispatched instructions on the http path, an
interpreter pays no instruction-cache penalty for inlining (register pressure is
the real constraint), inlining subsumes the reference-counting contract at
inlined sites (the borrow analysis stays valuable where inlining cannot go), and
the synergy chain of inline then fold then fuse over the rewrite engine is the
path to the next large single-core factor. Whole-program compilation, the static
call graph, and monomorphized IR make it body-splicing. Design questions queued:
thresholds, register-pressure guard, pipeline position before register planning,
span preservation for explain, and counter-driven unrolling scope.

Author: Axmouth

plans/INDEX.md

@@ -23,8 +23,9 @@ Mostly current and self-describing. Grouped by theme.
 - **Modules and stdlib**: MODULES (compile-time AST imports, BUILT v1), HTTP (std.http, BUILT),
   WEB_SERVER_TARGET, ROADMAP_GENERICS_STDLIB, TEST_HARNESS, ASSESSMENTS (the futures ledger).
 - **Performance**: PROFILING (HTTP server profiling method and findings, single-core throughput and
-  memory, the harness in `tools/profiling/`), RC_ELISION (the ownership-oracle model, move elision
-  BUILT, borrow elision PLANNED with the edge-case ledger).
+  memory, the harness in `tools/profiling/`), RC_ELISION (the ownership-oracle model, move and
+  borrow elision BUILT with the edge-case ledger), INLINING (the assessment that inlining plus
+  unrolling plus fusion is the dispatch-count lever, VISION).
 
 ## Runtime foundation (VM side), with build status
 

plans/INLINING.md

@@ -0,0 +1,57 @@
+# Inlining and unrolling: the dispatch-count lever
+
+The assessment that function inlining, with loop unrolling as its sibling, is one of the largest
+levers for overall single-core performance. Grounded in the profiling numbers (PROFILING.md) and
+queued as design, not committed work.
+
+## Why it is the big lever in this VM
+
+A hello-world http request executes about 3,745 dispatched instructions. Every user-function call
+pays pure ceremony before any work happens: the `CallFn` function-table lookup and frame push, one
+register move per argument into R1.., the callee prologue moving parameters back out, the `Return`
+frame pop, and the destination move. That is roughly five to ten instructions per call, and the http
+parse path is a mesh of tiny helpers, with dozens of calls per request. Call ceremony alone is
+plausibly ten to twenty percent of all dispatched instructions, before counting what inlining
+unlocks downstream.
+
+Two properties make inlining better here than in native compilation:
+
+- **Interpreters are unusually friendly to it.** Native inlining pays with instruction-cache
+  pressure. Here a bigger decoded program changes nothing per dispatch, so the classic size penalty
+  mostly does not exist. The genuine constraint is register pressure instead: an inlined body shares
+  the caller's register file, so deep inlining raises live-variable counts and triggers spills. The
+  heuristics watch that, not code size.
+- **It subsumes reference counting at inlined sites.** Inlining a callee dissolves the whole
+  ownership contract at that site: no argument retains, no parameter drops, no marshaling. The
+  parameters become local aliases that the existing intra-block move elision already handles
+  (RC_ELISION.md). The borrow analysis stays valuable exactly where inlining cannot go, large
+  bodies and recursion.
+
+## The synergy chain
+
+Inlining is the enabler for the rest of the optimization stack, not a standalone win:
+
+inline, producing long straight-line runs, then constant-fold across former call boundaries, then
+fuse the runs into single closures (FUSED.md over REWRITE_ENGINE.md), collapsing dispatch count.
+Unrolling is the same story for back-edges: a hot per-character loop spends about a fifth of its
+instructions on the condition and jump, and unrolling both removes that and hands fusion longer
+runs. The chain multiplies, which is why the assessment is that this family, not any single pass,
+is the path to the next large single-core factor.
+
+## Why this compiler is well placed
+
+Whole-program compilation, a static call graph (no first-class functions), and monomorphized typed
+IR make inlining body-splicing with variable renaming, no polymorphism or link-time unknowns. It is
+also backend-neutral: an AOT C transpile (ASSESSMENTS.md) benefits identically from the same IR
+transform, so nothing here bets on the interpreter.
+
+## Design questions for the plan proper
+
+- Heuristics: an instruction-count threshold for inline candidates, leaf-first, no or bounded
+  recursion, and a register-pressure guard tied to the allocator's capacity model.
+- Where in the pipeline: on typed IR before register planning, so the allocator and the elision
+  analyses see the flattened bodies (and the elision report then measures the post-inline world).
+- Interaction with `--explain` and spans: inlined instructions keep their source spans, so the
+  aligned view stays honest across splices.
+- Unrolling scope: small constant trip counts and hot parse loops first, driven by the profiling
+  counters rather than guessed.