Plan borrow elision: the ownership-oracle design and edge-case ledger

RC_ELISION.md is the plan of record for the elision program. It records the
model (Rust's ownership and borrow analysis as an internal oracle, never a gate,
RC as the always-correct fallback), the built move elision with its soundness
review verdict, and the borrow-elision design: per-parameter Owned or Borrowed
modes, an escape analysis seeded by stores, returns, reassignment, spawn capture,
and the builtin table, propagated to fixpoint over the static call graph.

The edge-case ledger covers what the assessment surfaced: returned and reassigned
params stay Owned, spawn targets stay all-Owned (the task outlives the frame),
finalizers already run borrowed-self, yields are safe since the caller's frame
survives them, the two-sided caller-callee contract is structural under
whole-program compilation but must be pinned by report tests, finalizer timing
needs pinned semantics, and separate compilation later needs serialized
summaries. Verified against the code: param reassignment is legal, the callee
drops every ref param except a returned one, and the call graph is static.

Author: Axmouth

plans/INDEX.md

@@ -23,7 +23,8 @@ 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/`).
+  memory, the harness in `tools/profiling/`), RC_ELISION (the ownership-oracle model, move elision
+  BUILT, borrow elision PLANNED with the edge-case ledger).
 
 ## Runtime foundation (VM side), with build status
 

plans/RC_ELISION.md

@@ -0,0 +1,142 @@
+# Reference-count elision: moves, borrows, and the ownership oracle
+
+The plan of record for removing reference-counting work the compiler can prove unnecessary. The
+guiding model: take Rust's ownership and borrow analysis as an internal optimization oracle, never as
+a gate. Where the analysis proves a value's lifetime is clean the reference counting is dropped, and
+where it cannot the reference counting stays, which is always correct. The programmer never sees a
+move, a borrow, or an ownership error, and no program is ever rejected. That is the difference from
+Rust: Rust rejects what it cannot prove, this keeps the refcount. Cycles remain out of scope for RC
+entirely and belong to the future cycle collector (plans/memory/GC.md).
+
+Measurement and the profiling harness live in PROFILING.md. This doc is the design and the edge-case
+ledger.
+
+## Where it stands: move elision (BUILT)
+
+`elidable_moves` in `bytecode_gen.rs` proves a reference-typed variable's last use hands its single
+reference to a consumer (a call argument, a spawn argument, or an aliasing copy), and the lowering
+then skips both the retain at that site and the variable's own drop. Conditions, conservative so it
+can only under-elide: last real use (loop-aware, a loop-carried variable is live across the
+back-edge), exactly one occurrence at the move site (passing a value twice in one call hands over two
+references), and a single drop the move dominates (approximated as no control flow between move and
+drop). The `Drop` instruction itself stays in the IR, only its DecRef emission is skipped, so register
+lifetime bookkeeping is untouched.
+
+Measured on the http hello path: incref 102 to 81 and decref 172 to 151 per request. A soundness
+review traced the refcount balance per consumer kind against the pre-elision build (the residual
+`allocations + incref - decref` must match exactly) and found no imbalance anywhere, including the
+callee-returns-its-param and direct-finalizer cases. The invariant is caller-side pair cancellation:
+a matched retain and drop with the variable provably dead between them cancel regardless of what the
+consumer does.
+
+## The next lever: borrow elision (PLANNED)
+
+Today every reference argument is retained by the caller because the convention is callee-owns: the
+callee's return-path drops release every reference parameter (except a returned one, whose ownership
+moves out through the return value). Move elision only removes the last-use case.
+
+The borrow insight, Rust's shared reference: a parameter the callee only reads needs no ownership
+transfer at all. Give every function a per-parameter mode, Owned or Borrowed. A Borrowed parameter is
+never dropped by the callee and never retained by the caller, who keeps its own drop and thereby
+guarantees the value outlives the synchronous call. Counting the ops for a value passed to k calls:
+the owned convention costs k retains, k callee drops, and one final drop. The borrowed convention
+costs one final drop. Move elision only ever saved one retain and one drop of that total, so borrows
+are the much larger category, and most parameters are read-only in practice (the http parse helpers
+on the hot path are exactly this shape).
+
+### Why this compiler can do it cheaply
+
+- **Whole-program compilation.** The prelude is prepended and imports are AST inclusion, so every
+  caller and callee compile together in one run from one summary map. The two-sided contract (both
+  sides must agree on each parameter's mode) is structural rather than a linking problem.
+- **Static call graph.** There are no first-class functions, every call resolves to a concrete
+  function at compile time, and spawn names its target statically. Escape propagation is an ordinary
+  fixpoint over a finite graph.
+- **Monomorphized typed IR.** Generics are resolved before lowering, so summaries are computed on
+  concrete functions and no polymorphic mode juggling exists.
+- **One chokepoint.** `lower_program` already holds main plus every function and lowers each body. A
+  summary pass runs there before lowering, then `lower_body` consults it on both sides: skip retains
+  for arguments in Borrowed positions, skip param drops for the current function's Borrowed
+  parameters.
+
+### The analysis
+
+A parameter escapes (and is therefore Owned) when any of these applies to it or to any alias of it
+inside the callee:
+
+- stored into a struct field, array or list element, map entry, enum payload, or global cell
+- returned (ownership moves out to the caller through the return value)
+- passed to another call in a position whose parameter is itself Owned (the transitive case, resolved
+  by the fixpoint)
+- passed to a builtin that stores or keeps it, per a curated builtin table (`push`, `set`, map set,
+  global set, spawn keep their value argument, `buf_push`, `write_str`, `str_concat2`, comparisons
+  and reads only read), with unknown treated as escaping
+- captured by spawn (the task outlives the caller's frame)
+- reassigned inside the callee (the end-of-scope drop releases the current value, so skipping the
+  param drop would leak the reassigned value, and param reassignment is verified legal today)
+- the function is a spawn target (the task runtime owns and releases its arguments, and the spawner's
+  frame may be gone before the task runs, so no caller-side lifetime guarantee exists)
+
+Everything else is Borrowed. Seed the direct escapes, propagate through the static call graph until
+stable. Escape facts only grow, the graph is finite, so the fixpoint terminates, and recursion and
+mutual recursion need no special case.
+
+### Interaction with move elision
+
+A Borrowed position no longer consumes, so arguments passed there leave the move-candidate set (a
+move into a non-consuming position would leak: nobody would drop the value). Owned positions keep
+today's move logic unchanged. For a last-use temporary the two come out equal (one RC op either way),
+everywhere else the borrow wins, so the composition is strictly better and never double-elides.
+
+## Edge cases and issues (the ledger)
+
+- **Returned params stay Owned.** The callee already skips the drop for a returned parameter and
+  ownership transfers to the caller. A Borrowed-and-returned parameter would hand the caller a
+  reference it never owned: one count, two eventual drops.
+- **Reassigned params stay Owned.** As above, the reassigned value needs the end-of-scope drop.
+- **Spawn targets get all-Owned params.** Statically detectable since spawn sites name the function.
+  This costs some hot-path wins (`http_conn_task` is a spawn target) and is the price of the frame
+  lifetime argument. A later refinement can split a task entry wrapper from the borrowable body.
+- **Finalizers are precedent, not a problem.** The runtime already invokes `Delete` without a retain
+  and the finalizer does not drop `self`, which is exactly a borrowed-self convention. Keep the
+  existing special case untouched.
+- **Green-thread yields are safe.** A callee that parks mid-call suspends the caller's frame with it,
+  so the caller's reference survives the yield and the lifetime guarantee holds. Spawn is the only
+  way a callee outlives its caller and is excluded above.
+- **Aliases inside the callee.** `let q = p` then `q` escapes means `p` escapes. First cut: any
+  aliasing of a parameter marks it Owned, refine to alias-tracking later.
+- **Finalizer timing shifts.** Elision moves the instant a count reaches zero (a borrowed argument
+  now dies at the caller's scope end rather than inside the callee). Pin the semantics: a finalizer
+  runs no later than the end of the owning scope, and no elision may extend a value's life past what
+  the unoptimized program would observe at scope ends. Record this in the language docs when the
+  surface stabilizes.
+- **Callee-side skipping is per variable, all paths.** Param drops appear on every return path plus
+  the fall-through. Borrowed mode skips all of them, the opposite polarity of the caller-side
+  per-site retain rule. Cheap, since the mode is per parameter.
+- **The two-sided contract is the sharpest risk.** Caller and callee must agree on every parameter's
+  mode. One summary map drives both sides in one compilation, and `--rc-report` should print each
+  function's modes so tests can pin them (the same oracle pattern the move elision used).
+- **Separate compilation later.** Bytecode-level linking (IMPORT.md) must serialize summaries into
+  the module format, or boundaries fall back to all-Owned. Whole-program holds today.
+- **Multicore later.** A borrow is valid only within the frame-synchronous world. Cross-core sends
+  are moves of `Owned<T>` (DESIGN_NOTES), and a send is an escape, so the models compose.
+- **Closures later.** If first-class functions ever land, a capture is an escape. The static call
+  graph assumption is load-bearing and must be revisited then.
+- **Testing oracle.** The decisive equivalence test is residual matching: `allocations + incref -
+  decref` on the optimized build must equal the unoptimized build for the same program (residuals are
+  compared rather than required to be zero because top-level values are reclaimed by VM teardown
+  rather than dropped). Plus the leak suite, byte-identical goldens in both fold modes, and pinned
+  per-mode tests: a read-only param is Borrowed, a stored or returned or reassigned param is Owned, a
+  spawn target is all-Owned.
+
+## Order of execution
+
+1. **Summaries plus report, no codegen change.** Compute per-function parameter modes with the
+   fixpoint, extend `--rc-report` to print them, pin the classification with tests (the measure-first
+   pattern that caught the loop-carried bug in move elision).
+2. **Flip codegen on both sides.** Skip caller retains into Borrowed positions and callee drops of
+   Borrowed params. Exclude Borrowed positions from move candidates. Prove with residual equivalence,
+   the full suites, goldens, and the vm-counters delta on the http path.
+3. **Refine.** Alias-aware escape inside callees, a task-entry wrapper so spawn targets can borrow,
+   dominance-based move elision, return-value moves, and the orphan-temp direct free that attacks
+   the per-request allocation count.