Borrow elision step 2: flip codegen on both sides of the contract

A caller no longer retains an argument passed to a Borrowed parameter position
and keeps its own drop, which guarantees the value outlives the synchronous
call. A callee no longer drops its Borrowed parameters. One summary map computed
in lower_program drives both decisions, so the two-sided contract cannot
disagree. Borrowed positions leave the move-candidate set (a move into a
non-consuming position would leak), and the current function's own Borrowed
parameters are excluded from move candidacy defensively, though the escape
fixpoint already forces anything they alias, spawn, or hand to an Owned position
to be Owned itself.

Measured per http request: incref falls from 81 to 43 (102 before any elision)
and decref from 151 to 113, with the per-request residual identical between
builds at 23.70, preserving the reference balance. All suites and goldens green
in both fold modes. One pinned finalizer test changed as intended: a value
passed to two read-only callees now finalizes at the owner's scope end rather
than at the consuming call, the documented borrow timing.

Author: Axmouth

plans/RC_ELISION.md

@@ -174,10 +174,17 @@ assumption, and the melding is three layers, from safest to most optimized:
    owned). First measurement on the http hello server: 61 of 83 reference parameters are borrowable,
    including the whole parse path (`self` receivers, `Connection.write` data, `Request.header`
    name), while `unwrap_or`'s fallback correctly stays owned since it can be returned.
-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. This is the
-   soundness-critical step and gets the same two-angle review the move elision got.
+2. **Flip codegen on both sides. DONE.** One summary map computed in `lower_program` drives both
+   sides, so the two-sided contract is agreed by construction: the caller skips the retain into a
+   Borrowed position and keeps its own drop, the callee skips the drop of a Borrowed parameter, and
+   Borrowed positions leave the move-candidate set (with the current function's own Borrowed
+   parameters excluded from candidacy defensively, though the fixpoint already forces anything they
+   alias, spawn, or hand to an Owned position to be Owned). Measured per http request: incref 102 to
+   81 to 43 across no-elision, move-elision, and borrow-elision builds, decref 172 to 151 to 113,
+   and the per-request residual `allocations + incref - decref` is identical between the move and
+   borrow builds at 23.70, so the balance is preserved. All suites and goldens green in both fold
+   modes. One pinned test changed as intended: a value passed to two read-only callees now finalizes
+   at the owner's scope end rather than at the consuming call, the documented borrow timing.
 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.

solid-snake-compiler/src/bytecode_gen.rs

@@ -583,8 +583,16 @@ fn for_each_stmt_read(stmt: &TypedIRStmt, f: &mut impl FnMut(usize)) {
 /// is elided (it was consumed). Conservative and sound: the move must dominate the drop, approximated
 /// by a single drop with no control flow between the move and it (a straight-line consumed value), and
 /// it is loop-aware (a variable carried into a loop is live across the back-edge, never a move). When
-/// it cannot prove a move it keeps the reference counting. See plans/PROFILING.md.
-fn elidable_moves(ir: &[TypedIRInstruction]) -> HashMap<usize, usize> {
+/// it cannot prove a move it keeps the reference counting. Borrowed call positions are not move
+/// candidates (the callee no longer consumes there, so a move would leak), and the current
+/// function's own Borrowed parameters are excluded defensively (a function cannot give away a
+/// reference it only borrows, and the escape fixpoint already forces anything it aliases, spawns,
+/// or hands to an Owned position to be Owned itself). See plans/PROFILING.md and RC_ELISION.md.
+fn elidable_moves(
+    ir: &[TypedIRInstruction],
+    modes: &HashMap<String, Vec<ParamMode>>,
+    own_borrowed: &std::collections::HashSet<usize>,
+) -> HashMap<usize, usize> {
     let last = last_real_use(ir);
     let loops = loop_ranges(ir);
     let mut defs: HashMap<usize, Vec<usize>> = HashMap::new();
@@ -638,9 +646,11 @@ fn elidable_moves(ir: &[TypedIRInstruction]) -> HashMap<usize, usize> {
                 value: TypedIRExpr::Var(src),
                 ..
             } => candidates.push((src.id(), is_rc(src.typ()), i)),
-            TypedIRStmt::Call { args, .. } => {
-                for a in args {
-                    candidates.push((a.id(), is_rc(a.typ()), i));
+            TypedIRStmt::Call { function_name, args, .. } => {
+                for (j, a) in args.iter().enumerate() {
+                    if param_mode(modes, function_name, j) == ParamMode::Owned {
+                        candidates.push((a.id(), is_rc(a.typ()), i));
+                    }
                 }
             }
             TypedIRStmt::CallBuiltin {
@@ -668,7 +678,11 @@ fn elidable_moves(ir: &[TypedIRInstruction]) -> HashMap<usize, usize> {
 
     let mut elidable: HashMap<usize, usize> = HashMap::new();
     for (v, is_rc_v, i) in candidates {
-        if !is_rc_v || occurrences.get(&(v, i)) != Some(&1) || !is_movable(v, i) {
+        if !is_rc_v
+            || own_borrowed.contains(&v)
+            || occurrences.get(&(v, i)) != Some(&1)
+            || !is_movable(v, i)
+        {
             continue;
         }
         if let Some(ds) = drops.get(&v) {
@@ -789,6 +803,20 @@ pub enum ParamMode {
     Owned,
 }
 
+/// A callee parameter's mode at a call position, defaulting to Owned for an unknown callee so
+/// everything unknown keeps the retain-and-callee-drops convention.
+fn param_mode(
+    modes: &HashMap<String, Vec<ParamMode>>,
+    function_name: &str,
+    position: usize,
+) -> ParamMode {
+    modes
+        .get(function_name)
+        .and_then(|m| m.get(position))
+        .copied()
+        .unwrap_or(ParamMode::Owned)
+}
+
 /// The argument positions a builtin stores or keeps, making the value escape. Exhaustive over the
 /// `Builtin` enum with no wildcard, so adding a builtin forces a decision here rather than silently
 /// classifying it as read-only. `CtxNew` is handled at its call site since every argument past the
@@ -856,7 +884,7 @@ fn builtin_escaping_positions(builtin: &Builtin) -> &'static [usize] {
 /// propagates escapes over the static call graph to a fixpoint. Escape facts only grow and the graph
 /// is finite, so it terminates, and recursion needs no special case. Unknown callees and unresolvable
 /// spawn targets degrade conservatively to Owned.
-pub fn analyze_param_modes(ir_functions: &[TypedIrFunction]) -> HashMap<String, Vec<ParamMode>> {
+pub fn analyze_param_modes(ir_functions: &[&TypedIrFunction]) -> HashMap<String, Vec<ParamMode>> {
     // Escape flags per function, indexed like its params. Only reference-typed params matter, the
     // rest stay false and report Borrowed trivially.
     let mut escapes: HashMap<String, Vec<bool>> = ir_functions
@@ -867,10 +895,10 @@ pub fn analyze_param_modes(ir_functions: &[TypedIrFunction]) -> HashMap<String,
     let mut deps: Vec<((String, usize), (String, usize))> = Vec::new();
     let by_raw_id: HashMap<u64, &TypedIrFunction> = ir_functions
         .iter()
-        .map(|f| (f.id.raw() as u64, f))
+        .map(|f| (f.id.raw() as u64, *f))
         .collect();
 
-    for f in ir_functions {
+    for &f in ir_functions {
         let param_index: HashMap<usize, usize> = f
             .params
             .iter()
@@ -1298,6 +1326,8 @@ fn lower_body(
     constants: &mut Vec<Vec<u8>>,
     func_ids: &HashMap<String, u64>,
     has_spill_table: bool,
+    modes: &HashMap<String, Vec<ParamMode>>,
+    borrowed_params: &std::collections::HashSet<usize>,
 ) -> Result<Vec<UnprocessedInstruction>, CompileError> {
     let mut instructions = Vec::with_capacity(ir.len());
 
@@ -1315,7 +1345,7 @@ fn lower_body(
     }
 
     // Variables whose reference is moved into a consumer, so their retain and drop are both elided.
-    let elidable = elidable_moves(ir);
+    let elidable = elidable_moves(ir, modes, borrowed_params);
 
     for (idx, ir_instr) in ir.iter().enumerate() {
         match &ir_instr.kind {
@@ -1336,8 +1366,12 @@ fn lower_body(
             TypedIRStmt::Drop { target, .. } => {
                 // Releasing a reference at end of life, freeing the object at zero. A moved variable
                 // was consumed at its last use, so its reference is already gone and its drop is elided
-                // (the register is still freed below).
-                if is_rc(target.typ()) && !elidable.contains_key(&target.id()) {
+                // (the register is still freed below). A Borrowed parameter of this function is never
+                // dropped by it: the caller kept ownership and its own drop.
+                if is_rc(target.typ())
+                    && !elidable.contains_key(&target.id())
+                    && !borrowed_params.contains(&target.id())
+                {
                     let (reg, instrs) = get_var_register(target.id(), reg_alloc)?;
                     instructions.extend_from_slice(&instrs);
                     emit_release(target.typ(), reg, &mut instructions);
@@ -1390,11 +1424,16 @@ fn lower_body(
                     let arg_reg = (i as u8) + 1;
                     instructions
                         .push(UnprocessedInstruction::MoveU64((arg_reg.into(), reg.into())));
-                    // The callee owns its parameters and drops them, so an argument gets an extra
-                    // reference here to balance that drop, unless the argument is moved into the call
-                    // (its last use), in which case the caller hands over its reference and skips both
-                    // this retain and the argument's drop.
-                    if elidable.get(&arg.id()) != Some(&idx) {
+                    // An Owned parameter keeps the callee-owns convention: the callee drops it, so
+                    // the argument gets an extra reference here to balance that drop, unless it is
+                    // moved into the call (its last use), where the caller hands over its reference
+                    // and skips both this retain and the argument's drop. A Borrowed parameter is
+                    // only read by the callee and never dropped there, so the caller passes it with
+                    // no retain and keeps its own drop, which guarantees the value outlives the
+                    // synchronous call.
+                    if param_mode(modes, function_name, i) == ParamMode::Owned
+                        && elidable.get(&arg.id()) != Some(&idx)
+                    {
                         emit_retain(arg.typ(), reg, &mut instructions);
                     }
                 }
@@ -1795,13 +1834,38 @@ pub fn lower_program(
         func_ids.insert(f.name.clone(), f.id.raw() as u64);
     }
 
+    // The borrow analysis over the whole program: one summary map drives the caller side (skip the
+    // retain into a Borrowed position) and the callee side (skip the drop of a Borrowed parameter),
+    // so the two-sided contract is agreed by construction. See plans/RC_ELISION.md.
+    let mut all_funcs: Vec<&TypedIrFunction> = Vec::with_capacity(functions.len() + 1);
+    all_funcs.push(main);
+    all_funcs.extend(functions.iter());
+    let modes = analyze_param_modes(&all_funcs);
+    let borrowed_of = |f: &TypedIrFunction| -> std::collections::HashSet<usize> {
+        f.params
+            .iter()
+            .zip(modes.get(&f.name).map(Vec::as_slice).unwrap_or(&[]))
+            .filter(|(_, m)| **m == ParamMode::Borrowed)
+            .map(|(p, _)| p.id)
+            .collect()
+    };
+
     // Main, at byte offset 0. Main runs once and ends in Halt, so its spill table (if any) is
     // reclaimed at VM teardown rather than per call, and needs no explicit free.
     {
         let mut reg_alloc = RegisterAllocator::new(MAX_REGISTERS);
         reg_alloc.plan(&main.body, &[]);
         program.extend(maybe_spillage_table_init(&mut reg_alloc)?);
-        program.extend(lower_body(&main.body, &mut reg_alloc, &mut constants, &func_ids, false)?);
+        let no_params = std::collections::HashSet::new();
+        program.extend(lower_body(
+            &main.body,
+            &mut reg_alloc,
+            &mut constants,
+            &func_ids,
+            false,
+            &modes,
+            &no_params,
+        )?);
         program.push(UnprocessedInstruction::Halt((0,)));
     }
 
@@ -1826,12 +1890,15 @@ pub fn lower_program(
             reg_alloc.end_statement();
         }
 
+        let borrowed_params = borrowed_of(f);
         program.extend(lower_body(
             &f.body,
             &mut reg_alloc,
             &mut constants,
             &func_ids,
             has_spill_table,
+            &modes,
+            &borrowed_params,
         )?);
         // Fallthrough terminator for functions whose control reaches the end without a return,
         // freeing the spill table on that path too.
@@ -2198,7 +2265,9 @@ mod codegen_tests {
         assert!(!ctx.errors().is_fatal(), "compile errors: {:?}", ctx.errors());
         let mut ir_functions = vec![ctx.main_function()];
         ir_functions.extend(ctx.functions().to_vec());
-        let modes = super::analyze_param_modes(&ir_functions);
+        let func_refs: Vec<&crate::intermediate_pass1::TypedIrFunction> =
+            ir_functions.iter().collect();
+        let modes = super::analyze_param_modes(&func_refs);
         let mangled = format!("{fn_name}$");
         let name = ir_functions
             .iter()
@@ -2336,14 +2405,14 @@ mod codegen_tests {
     }
 
     #[test]
-    fn rc_two_calls_retain_stays_at_the_first() {
-        // Passed to two calls: the retain must stay at the first (the value is still live), and only
-        // the second is a move. The finalizer fires once, at the consuming call, before the print
-        // that follows it.
+    fn rc_two_calls_frees_exactly_once_at_scope_end() {
+        // Both callees only read their parameter, so the borrow analysis marks it Borrowed: neither
+        // call retains or consumes, the caller keeps the one reference, and the finalizer fires at
+        // the owner's scope end after both calls. Exactly one free either way is the invariant.
         let (_, out) = run_src(&format!(
             "{RES_TYPE}def peek(r: Res) -> Int:\n    return r.id\n\ndef consume(r: Res) -> Int:\n    return r.id\n\nlet r = Res(5)\nlet a = peek(r)\nlet b = consume(r)\nprint(\"ab\", a, b)\n"
         ));
-        assert_eq!(out, "D 5\nab 5 5\n");
+        assert_eq!(out, "ab 5 5\nD 5\n");
     }
 
     #[test]

solid-snake-compiler/src/runner.rs

@@ -267,7 +267,8 @@ pub fn rc_report(ir_functions: &[TypedIrFunction]) -> String {
 
     // The borrow analysis: per-function parameter modes, listed for every function with at least one
     // reference parameter, sorted for a stable report. See plans/RC_ELISION.md.
-    let modes = analyze_param_modes(ir_functions);
+    let func_refs: Vec<&TypedIrFunction> = ir_functions.iter().collect();
+    let modes = analyze_param_modes(&func_refs);
     let mut ref_params = 0usize;
     let mut borrowed = 0usize;
     let mut lines: Vec<String> = Vec::new();