Issue #1028: Decision: does a method lend a by-value data parameter (ADR-277 D17), for trait methods only or for every method?

ready · opened 2026-10-31 · updated 2026-11-03 · 2 comments

The question

ADR-277 D17 (#1012, option E) says a trait method’s keeps column covers every by-value parameter, code or data, and that “by value no longer means kept”. Brief b1012c was meant to build the data half. It stopped (Result: blocked, docs/briefs/b1012c-trait-column-data.md.report.md) because the column is not what refuses the lending:

lends_with (crates/nikaia-std/src/tools/lends.nika:51) only lends a by-value parameter when !signature.takes_a_receiver() || (own && a_function_value(ty)). So no method (inherent or trait) lends a by-value data parameter, whatever its keeps says.
emit_arg_only_read (tools/emit_core_args.nika:192) returns false for any callee that takes a receiver.
The comment above lends_in gives the reason: “A method’s inferred lending waits on the emitter knowing which entry a call goes to (ADR-288)”. No ADR refuses it. This is a build gap that was left open, so it is kind 2 (not decided).

Probe (an inherent method with an empty keeps), refused with NK2105:

struct Count { base: i64 }
impl Count { fn size(ref self, text: String) -> i64 sync { return self.base + text.len() } }
fn main() { let c = Count { base: 1 }; let own = f"{c.base}x"; println(c.size(own)); println(own) }

The same probe under a trait bound is refused the same way. With the keeps.rs seed removed, the ledger column of Measure::size becomes empty, but nothing lowers differently.

Alternatives

1. Lift the exclusion for trait methods and their impls only.

For: it is what D17 literally covers, and it unblocks #1012 (the k3a2 host trait).
Against:
- FnContract has no trait flag today, so one has to be added. The checker, the emitter and the Rust host impls follow.
- An inherent method and a trait method with the same body would then lend differently. That is a rule that exists for no reason of its own.

2. Lift it for every method.

For:
- ADR-094 D2 reads the body of any callee, so this is the plain reading.
- It needs no trait flag.
- It removes the exclusion and its comment, and leaves one rule.
Against:
- It is wider. Every inherent method of tools/*.nika whose body only reads a by-value parameter changes its lowering (&T / &str instead of T). Its Rust callers then have to lend, so lowered files and hand-written callers change in one go.
- The emitter has to resolve a method call to its entry. The ADR-288 concern in the comment has to be shown to be met: is the receiver’s type known at every call site?

3. Neither for now. D17 then holds for code parameters only, and gets amended to say so.

Against: it goes back on a decision taken two days ago, and it leaves k3a2’s data callbacks paying a copy.

Recommendation

2, built in two steps:

Trait methods and impls first, behind the existing receiver check: the column decides, so #1012 can go on.
Inherent methods next, as their own brief, with the lowered-file churn in one commit.

The end state is one rule for every callee, as ADR-094 D2 says. Option 1 as the end state would write a distinction into the language that only the build history explains.

After the decision

An amendment line in ADR-277 D17 (and ADR-094 D2 if 2), and a To build list on #1012 (and a new issue for the inherent step if 2). b1012c is out of the batch until then.

Comments

keywan-ghadami, 2026-10-31

Answers to the four follow-up questions

I checked each answer against today’s code on develop. A probe was run where the code alone did not settle the question.

1. Resolving the method target: is the contract known before lending is decided?

The checker resolves every method call statically and writes the result down. The emitter decides lending later, from that record.

Inherent method, x.m(a). check_core_call_on takes the name of the receiver’s type and looks up resolve_method(world, "{Type}::m") (check_scope.nika:142). That function tries the program’s own contracts first, then the library’s, then the key without its module. When it finds the method, check_core_call_on_described stores the key in facts.method_callees, keyed by the receiver’s node. The emitter reads that into walk.method_callee (emit_core_calls.nika:1202). It already uses it to decide kept code and kept bytes per position (#842: self is position 0). Known: yes.
Trait method on a concrete type. This is the same path. The impl’s method is in the ledger under the type’s key, so the call resolves to that contract. Known: yes. The one thing to watch is in question 2.
Through a generic bound, [T: H], t.m(a). Looking up T::m fails, so check_core_call_on_undescribed asks bound_that_answers (check_decls.nika:48). That function returns the trait H that declares m, and the call is resolved again on H. The recorded contract is therefore the trait’s, which is exactly where ADR-277 D17 puts the union of the keeps column. Known: yes, and it is the trait’s contract. An unbounded T reaching a method is already refused (NK1126).
UFCS. Nikaia has no qualified call that passes the receiver as an argument. A probe confirms this: Box::take(b, s) on fn take(ref self, s: String) is refused with NK1101 (“takes 1 argument”), because the path form does not take self. So no third route has to be covered.
When nothing resolves. An Unknown receiver or a refused call records nothing in method_callees. Such a call stays as it is today: nothing is lent, because lends_with needs a contract.

2. Do an inherent method and a trait method with the same behaviour lend the same way? Special cases?

The rule is the same, but which column decides differs, and that difference is the point of D17.

Inherent method. Only its own body decides: a parameter moves, the ledger does not copy it, it is not mut, and it is not in the method’s keeps.
Trait method. The decision has to be the trait’s, made once from D17’s union and applied to every impl the same way. Rust requires every impl H for X to match the trait’s signature exactly. If one impl lent &str while the trait said String, the generated code would not compile. So an impl whose own body would allow lending still takes String when another impl keeps the value. A direct call x.m(a) on the concrete type must therefore read lending from the trait’s column, not from X::m’s own. This is the one place that needs care when this is built. Behaviour does not differ: the same program means the same thing, and only the lowered signature follows the trait.
Dynamic dispatch. None exists. Part I says “a trait is not a type: there is no dyn and no fn f(x: Summarize)”. A call through a bound becomes a Rust generic, so every target is known when the program is compiled. The dyn Fn the emitter writes in one place (emit_function.nika:589) is a closure parameter on a recursive cycle, not a trait object, and lending a method does not touch it.
Function values. A method cannot be handed over as a value. Only a free function named by Expr::Variable becomes a named function value (#757), and emit_arg_lent_params already returns nothing for a contract with a receiver. A function value inside a method’s parameter list is already lent today for the program’s own methods (lends_in_own). That stays as it is.

3. Rust lowering: are the references right, and can Rust host callers and existing packages cope?

References. The emitter already writes everything this needs for free functions: &str, &[T] or &T in the signature, & at the call site (emit_arg_passing), and a closure adapter where a lent function is handed over as a value. For methods, the call-site side keys on method_callee (the same key #842 uses). The signature side is the existing parameter code in emit_function. Two things are new:
- lends_with and emit_arg_only_read stop excluding receivers;
- for trait methods, both sides take the decision from the trait’s column (question 2).
Rust host callers. In the toolchain, every caller of a lowered method in tools/*.nika is itself lowered. A search of all hand-written Rust under crates/ outside lowered/ and rs2nika found no call to any of the affected methods. So lowering again with lower-std brings every caller along. For a program’s own Rust (extern or host code that calls a Nikaia method), the signature changes from String to &str. Rust’s type checker finds every such caller when the program is compiled; nothing breaks silently.
Existing packages. A package’s ledger records the lent signature (ref String). After the change, the ledgers of packages/json and packages/yaml and the examples have to be written again, and --locked refuses a stale one. Run 2701 showed exactly this for a free function (examples/json, unescape). Today neither packages/json nor packages/yaml has a method with a by-value, moving, non-kept parameter in its ledger, so I expect no change to their method signatures there. If one appears later, it raises only that package’s own version (ADR-344 D1).

4. Regressions: which methods change their calling convention, and can it be tested completely?

How many. I counted methods that take a receiver and have a by-value String, Vec, Bytes or collection parameter that is neither ref nor mut. This is the upper bound before the keeps filter, which removes every parameter the body stores:
- 27 parameters in 22 methods in crates/nikaia-std/src/tools/*.nika and packages/*. Examples: fold_bound::{whole_fields, field_type, methods_of, sum_of_both}, emit_entry::emit_held_struct (5), emit_types::boxed_ty, emit_core_calls::emit_call_required, project_members::crate_root, modules::parse_unit;
- 0 in every ledger under examples/ and packages/;
- 41 in crates/rs2nika/convert. That is the converter, which does not raise the version.
Only the methods that keep nothing actually change. Those are the ones that copy text today without needing to.
Can it be tested completely? Yes for whether it compiles, and yes for behaviour as far as the suite covers it. These are separate checks:
1. Signatures and callers. lower-std --check writes all of lowered/*.rs again, and cargo build with clippy -D warnings type-checks every caller. A missed &, a mismatch between trait and impl, or a caller on the old convention cannot pass this. The check is complete because Rust checks it.
2. Ledgers. nikaia test --locked on every package and example refuses any ledger the change makes stale (as run 2701 showed).
3. Behaviour. Lending does not change what a program means: a value that is only read is lent instead of copied. New .nika tests with their .stdout cover the cases:
  - an inherent method that lends;
  - an inherent method that keeps, which does not lend;
  - a trait whose impls disagree, where nothing is lent in any of them;
  - a trait whose impls all only read, where every impl lends;
  - a call through [T: H];
  - a function value inside a method’s parameters.
  The rest of the suite in CI shows that the existing programs still print the same output.
4. The two steps of the recommendation (option 2) keep each push small. Trait methods come first, because D17 already provides their column. Inherent methods follow with their own lowering run.

The recommendation does not change: option 2, built in two steps.

Generated by Claude Code

keywan-ghadami, 2026-10-31

Decided (owner, 2026-10-31): option 2, with additional tests.

Every method lends a by-value data parameter its body only reads, as every free function does (ADR-094 D2). The receiver exclusion in lends_with / emit_arg_only_read and the comment that justifies it go away. In the end there is one rule for every callee.

Built in two steps, as recommended:

Trait methods and their impls. The trait’s keeps column decides for every impl, because an impl must match the trait’s Rust signature. This unblocks b1012c / #1012.
Inherent methods, as their own issue and brief. The lowered-file churn goes in one commit: up to 27 parameters in 22 methods in tools/, none in examples or package ledgers.

Additional tests (owner’s condition). Each step brings its own tests/compiler/ programs. As a minimum:

the probe above (an inherent method, by-value String, the caller uses own after the call), and the same through a trait bound and through a generic T: Trait;
a trait whose column keeps the parameter: an impl that only reads it still takes it by value, and the caller moves;
a method that does keep the parameter (stores it in self or returns it): no lending, and a use after the call is still refused;
a method call reached through a field, an index and a chained call, so the receiver’s type is known at each call site (the ADR-288 concern);
a method value passed on: a lambda that wraps a lending method;
a mix of code and data parameters on one method;
a trait method of another package with a lending column, called from this package (NK1264 / NK1265 stay as they are).

Next: an amendment line in ADR-277 D17 and ADR-094 D2, the To build list for step 1 on #1012, and a new issue for step 2 (label ready). b1012c goes back into the batch after that.

Generated by Claude Code

Back to Open Issues