Borrow analysis step 1: per-function parameter modes, report, and tests

analyze_param_modes classifies every function's reference parameters as Borrowed
(the callee only reads them, so a caller could skip the retain and keep its own
drop) or Owned (escaping). Escape seeds: returned, stored into a field or
aggregate or collection or global, reassigned, aliased (the conservative first
cut), captured by spawn, or the function being a spawn target (resolved through
the function id the spawn lowering assigns, degrading to all-Owned when
unresolvable). A parameter forwarded to another function's parameter position
becomes a dependency edge, propagated to fixpoint over the static call graph, so
recursion needs no special case. The builtin escape table is exhaustive with no
wildcard, so adding a builtin forces a decision here rather than silently
classifying it read-only.

Report and analysis only, no codegen consults it yet. --rc-report now prints each
function's modes plus the aggregate. Eight tests pin the classification per
category. First measurement on the http hello server: 61 of 83 reference
parameters are borrowable, including the whole parse path, and unwrap_or's
fallback correctly stays owned since it can be returned.

Author: Axmouth

plans/RC_ELISION.md

@@ -164,12 +164,20 @@ assumption, and the melding is three layers, from safest to most optimized:
 
 ## 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).
+1. **Summaries plus report, no codegen change. DONE.** `analyze_param_modes` computes per-function
+   parameter modes with the escape fixpoint (seeds from returns, stores, reassignment, aliasing,
+   spawn capture, and an exhaustive per-builtin escape table with no wildcard, so a new builtin
+   forces a decision rather than silently reading as read-only). `--rc-report` prints every
+   function's modes, and eight tests pin the classification per category (read-only borrowed,
+   returned owned, field-stored owned, reassigned owned, list-pushed owned beside buf-pushed
+   borrowed, transitive escape and transitive borrow, recursion staying borrowed, spawn target
+   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.
+   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.
 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

@@ -777,6 +777,234 @@ pub fn analyze_rc_elision(ir: &[TypedIRInstruction]) -> RcElisionReport {
     r
 }
 
+/// A function parameter's ownership mode under the borrow analysis (plans/RC_ELISION.md). Borrowed
+/// means the callee only reads the parameter, so a caller could pass it without a retain and keep
+/// its own drop. Owned means the parameter escapes (stored, returned, reassigned, spawned, aliased,
+/// or handed to an Owned position elsewhere) and keeps the callee-owns convention. Non-reference
+/// parameters carry no count and report as Borrowed trivially. This is analysis and report only, no
+/// codegen consults it yet.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ParamMode {
+    Borrowed,
+    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
+/// function id escapes into the task.
+fn builtin_escaping_positions(builtin: &Builtin) -> &'static [usize] {
+    match builtin {
+        Builtin::Push => &[1],
+        Builtin::Set => &[2],
+        Builtin::MapSet => &[1, 2],
+        Builtin::GlobalSet | Builtin::GlobalSetList => &[1],
+        Builtin::CtxNew => &[],
+        Builtin::Print
+        | Builtin::ReadLine
+        | Builtin::ReadInt
+        | Builtin::Len
+        | Builtin::ArrayGet
+        | Builtin::ListGet
+        | Builtin::Pop
+        | Builtin::IntToStr
+        | Builtin::FloatToStr
+        | Builtin::BoolToStr
+        | Builtin::MapNew
+        | Builtin::MapGet
+        | Builtin::MapHas
+        | Builtin::MapLen
+        | Builtin::WriteStr
+        | Builtin::WriteByte
+        | Builtin::ByteAt
+        | Builtin::BufNew
+        | Builtin::BufPush
+        | Builtin::BufPushByte
+        | Builtin::BufToStr
+        | Builtin::BufLen
+        | Builtin::ArrayClone
+        | Builtin::StrConcat2
+        | Builtin::Substring
+        | Builtin::ParseInt
+        | Builtin::Status
+        | Builtin::FileOpen
+        | Builtin::FileRead
+        | Builtin::FileWrite
+        | Builtin::FileClose
+        | Builtin::FileExists
+        | Builtin::Poll
+        | Builtin::LastOp
+        | Builtin::OpResultStr
+        | Builtin::OpResultInt
+        | Builtin::TcpListen
+        | Builtin::TcpAccept
+        | Builtin::TcpRecv
+        | Builtin::TcpSend
+        | Builtin::TcpClose
+        | Builtin::CtxSwitch
+        | Builtin::CtxLive
+        | Builtin::GlobalGet
+        | Builtin::GlobalGetList => &[],
+    }
+}
+
+/// Classify every function's parameters as Borrowed or Owned (plans/RC_ELISION.md). Seeds each
+/// parameter's escape from its own body (returned, stored into an aggregate or collection or global,
+/// reassigned, aliased under the conservative first cut, spawned), records a dependency edge when a
+/// parameter is passed on to another function's parameter position, marks spawn-target functions
+/// all-Owned (the task outlives the spawner's frame, so no caller lifetime guarantee exists), and
+/// 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>> {
+    // 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
+        .iter()
+        .map(|f| (f.name.clone(), vec![false; f.params.len()]))
+        .collect();
+    // (dependent function, param index) escapes when (callee, callee param index) does.
+    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))
+        .collect();
+
+    for f in ir_functions {
+        let param_index: HashMap<usize, usize> = f
+            .params
+            .iter()
+            .enumerate()
+            .map(|(i, p)| (p.id, i))
+            .collect();
+        let mut escape = |escapes: &mut HashMap<String, Vec<bool>>, var: usize| {
+            if let Some(&i) = param_index.get(&var) {
+                escapes.get_mut(&f.name).expect("seeded above")[i] = true;
+            }
+        };
+        for (idx, instr) in f.body.iter().enumerate() {
+            match &instr.kind {
+                TypedIRStmt::Assign { target, value } => {
+                    // Reassigning a param means its end-of-scope drop releases the new value, and
+                    // aliasing a param is the conservative first cut for alias-tracked escape.
+                    escape(&mut escapes, target.id());
+                    if let TypedIRExpr::Var(src) = value {
+                        escape(&mut escapes, src.id());
+                    }
+                }
+                TypedIRStmt::Return { value: Some(v) } => escape(&mut escapes, v.id()),
+                TypedIRStmt::FieldSet { value, .. } => escape(&mut escapes, value.id()),
+                TypedIRStmt::StructNew { args, .. } => {
+                    for a in args {
+                        escape(&mut escapes, a.id());
+                    }
+                }
+                TypedIRStmt::ArrayNew { elements, .. } => {
+                    for e in elements {
+                        escape(&mut escapes, e.id());
+                    }
+                }
+                TypedIRStmt::Call { function_name, args, .. } => {
+                    for (j, a) in args.iter().enumerate() {
+                        if let Some(&i) = param_index.get(&a.id()) {
+                            if escapes.contains_key(function_name) {
+                                deps.push(((f.name.clone(), i), (function_name.clone(), j)));
+                            } else {
+                                escapes.get_mut(&f.name).expect("seeded above")[i] = true;
+                            }
+                        }
+                    }
+                }
+                TypedIRStmt::CallBuiltin { builtin, args, .. } => {
+                    if *builtin == Builtin::CtxNew {
+                        // Every argument past the function id escapes into the task, and the target
+                        // function itself must keep owned params (the task runtime drops them and
+                        // the spawner's frame may be gone before the task runs).
+                        for a in args.iter().skip(1) {
+                            escape(&mut escapes, a.id());
+                        }
+                        let target_fid = args.first().and_then(|a| {
+                            f.body[..idx].iter().rev().find_map(|prev| match &prev.kind {
+                                TypedIRStmt::Assign {
+                                    target,
+                                    value: TypedIRExpr::Int(k),
+                                } if target.id() == a.id() => Some(*k as u64),
+                                _ => None,
+                            })
+                        });
+                        match target_fid.and_then(|fid| by_raw_id.get(&fid)) {
+                            Some(task) => {
+                                if let Some(flags) = escapes.get_mut(&task.name) {
+                                    flags.iter_mut().for_each(|e| *e = true);
+                                }
+                            }
+                            None => {
+                                // Unresolvable spawn target: every function might be the task, so
+                                // everything degrades to Owned rather than guessing.
+                                for flags in escapes.values_mut() {
+                                    flags.iter_mut().for_each(|e| *e = true);
+                                }
+                            }
+                        }
+                    } else {
+                        for &pos in builtin_escaping_positions(builtin) {
+                            if let Some(a) = args.get(pos) {
+                                escape(&mut escapes, a.id());
+                            }
+                        }
+                    }
+                }
+                TypedIRStmt::Drop { .. }
+                | TypedIRStmt::Jump { .. }
+                | TypedIRStmt::JumpIf { .. }
+                | TypedIRStmt::JumpIfNot { .. }
+                | TypedIRStmt::Label(_)
+                | TypedIRStmt::FieldGet { .. }
+                | TypedIRStmt::Return { value: None } => {}
+            }
+        }
+    }
+
+    // Propagate escapes through the call graph until stable.
+    let mut changed = true;
+    while changed {
+        changed = false;
+        for ((fname, i), (gname, j)) in &deps {
+            let callee_escapes = escapes
+                .get(gname)
+                .and_then(|flags| flags.get(*j).copied())
+                .unwrap_or(true);
+            if callee_escapes {
+                let flags = escapes.get_mut(fname).expect("seeded above");
+                if !flags[*i] {
+                    flags[*i] = true;
+                    changed = true;
+                }
+            }
+        }
+    }
+
+    ir_functions
+        .iter()
+        .map(|f| {
+            let flags = &escapes[&f.name];
+            let modes = f
+                .params
+                .iter()
+                .zip(flags)
+                .map(|(p, &esc)| {
+                    if is_rc(&p.typ) && esc {
+                        ParamMode::Owned
+                    } else {
+                        ParamMode::Borrowed
+                    }
+                })
+                .collect();
+            (f.name.clone(), modes)
+        })
+        .collect()
+}
+
 /// The variable a statement defines (writes a fresh value into a variable), if any. Used to emit a
 /// store-back when that variable is memory-resident. Statements that only read (drops, jumps,
 /// returns) or write into an object field rather than a variable define nothing.
@@ -1029,7 +1257,7 @@ fn lower_expr_to_bytecode_stage_one(
 /// Whether a value of this type is a reference-counted heap object: nominal structs, strings, and
 /// arrays/lists. All carry the shared object header and are managed by IncRef/DecRef, and a
 /// container's descriptor traces its elements on free.
-fn is_rc(typ: &ProcessedType) -> bool {
+pub fn is_rc(typ: &ProcessedType) -> bool {
     matches!(
         typ,
         ProcessedType::Custom { .. }
@@ -1964,6 +2192,96 @@ mod codegen_tests {
 
     const RC_SINK: &str = "def sink(s: String) -> Int:\n    return len(s)\n\n";
 
+    /// The borrow analysis's parameter modes for one function (mangled names match by prefix).
+    fn param_modes_for(src: &str, fn_name: &str) -> Vec<super::ParamMode> {
+        let ctx = analyze_source(src);
+        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 mangled = format!("{fn_name}$");
+        let name = ir_functions
+            .iter()
+            .map(|f| f.name.clone())
+            .find(|n| n == fn_name || n.starts_with(&mangled))
+            .unwrap_or_else(|| panic!("no function named {fn_name}"));
+        modes[&name].clone()
+    }
+
+    use super::ParamMode::{Borrowed, Owned};
+
+    #[test]
+    fn borrow_read_only_param_is_borrowed() {
+        let m = param_modes_for("def f(s: String) -> Int:\n    return len(s)\n", "f");
+        assert_eq!(m, vec![Borrowed]);
+    }
+
+    #[test]
+    fn borrow_returned_param_is_owned() {
+        // Ownership rides out on the return, so the caller cannot keep the only reference.
+        let m = param_modes_for("def f(s: String) -> String:\n    return s\n", "f");
+        assert_eq!(m, vec![Owned]);
+    }
+
+    #[test]
+    fn borrow_field_stored_param_is_owned() {
+        let m = param_modes_for(
+            "type Box:\n    v: String\n\ndef f(b: Box, s: String):\n    b.v = s\n",
+            "f",
+        );
+        assert_eq!(m, vec![Borrowed, Owned], "the box is read, the stored value escapes");
+    }
+
+    #[test]
+    fn borrow_reassigned_param_is_owned() {
+        // The end-of-scope drop releases the reassigned value, so the param cannot be borrowed.
+        let m = param_modes_for(
+            "def f(s: String) -> Int:\n    s = \"other\"\n    return len(s)\n",
+            "f",
+        );
+        assert_eq!(m, vec![Owned]);
+    }
+
+    #[test]
+    fn borrow_list_pushed_param_is_owned_buf_pushed_is_borrowed() {
+        // The list stores its element (escape), the buffer only copies bytes out (read).
+        let m = param_modes_for(
+            "def f(xs: List[String], s: String, b: StrBuf, t: String):\n    push(xs, s)\n    buf_push(b, t)\n",
+            "f",
+        );
+        assert_eq!(m, vec![Borrowed, Owned, Borrowed, Borrowed]);
+    }
+
+    #[test]
+    fn borrow_escape_propagates_transitively() {
+        // g stores its param, f only forwards to g, so f's param is owned through the fixpoint,
+        // while a forward to a read-only callee stays borrowed.
+        let src = "type Box:\n    v: String\n\ndef store(b: Box, s: String):\n    b.v = s\n\ndef f(b: Box, s: String):\n    store(b, s)\n\ndef peek(s: String) -> Int:\n    return len(s)\n\ndef g(s: String) -> Int:\n    return peek(s)\n";
+        assert_eq!(param_modes_for(src, "f"), vec![Borrowed, Owned]);
+        assert_eq!(param_modes_for(src, "g"), vec![Borrowed]);
+    }
+
+    #[test]
+    fn borrow_recursive_read_only_param_stays_borrowed() {
+        // The fixpoint terminates on the self-edge with no escape seed, so recursion alone does not
+        // pessimize.
+        let m = param_modes_for(
+            "def f(s: String, n: Int) -> Int:\n    if n <= 0:\n        return len(s)\n    return f(s, n - 1)\n",
+            "f",
+        );
+        assert_eq!(m, vec![Borrowed, Borrowed], "the string param and the trivially non-ref Int");
+    }
+
+    #[test]
+    fn borrow_spawn_target_params_are_owned() {
+        // The task outlives the spawner's frame, so no caller lifetime guarantee exists.
+        let m = param_modes_for(
+            "def worker(s: String):\n    print(s)\n\nlet x = \"hi\"\nspawn worker(x)\nscheduler_run()\n",
+            "worker",
+        );
+        assert_eq!(m, vec![Owned]);
+    }
+
     #[test]
     fn rc_call_arg_last_use_is_movable() {
         // `x`'s only use is the call, so passing it is a move: the retain is elidable.