feat: implicit argument derivation and structural record synthesis

[Kamirus]

Summary

Extends the Motoko compiler's implicit argument resolution with two new mechanisms:

1. Implicit derivation from functions with inner implicits

The compiler can now resolve implicit arguments by composing them from functions (possibly polymorphic) that themselves have implicit parameters. For example, an implicit compare for [Nat] is automatically derived from Array.compare<Nat> + Nat.compare, eliminating boilerplate wrapper modules. Works transitively (e.g., [[Nat]]). Depth-limited with --implicit-derivation-depth (default: 5).

Before:

module MyArray {
  public func compare(a : [Nat], b : [Nat]) : Order { Array.compare(a, b) };
};
let m = Map.empty<[Nat], Text>();
m.add([1, 2, 3], "abc"); // uses MyArray.compare

After:

let m = Map.empty<[Nat], Text>();
m.add([1, 2, 3], "abc"); // just works — derived from Array.compare<Nat> + Nat.compare

2. Structural derivation for records and tuples

A function whose sole explicit parameter is named __record (typed [(Text, T)] -> R) or __tuple (typed [T] -> R) acts as a structural combiner. When the compiler needs an implicit for a record or tuple type, it automatically decomposes the type, resolves a per-field/per-element implicit (using the same search label), and synthesizes a wrapper. Both unary (X -> R) and binary ((X, X) -> R) hole types are supported.

Example — generic JSON serialization for any record:

import Json "mo:json/Json";
import IntJson "mo:json/IntJson";
import TextJson "mo:json/TextJson";

type Person = { name : Text; age : Int };

let p : Person = { name = "Alice"; age = 30 };
let json = p.toJson();
// #obj([("name", #text "Alice"), ("age", #number 30)])

The Json package defines a single _toJson(__record : [(Text, Json)]) : Json combiner. That's all — the compiler handles every record type automatically, as long as each field type has a _toJson instance.

Resolution order

Direct matches are always preferred over derived ones. Within each tier, the most specific candidate (by subtyping) wins:

1. Direct local values
2. Direct module fields
3. Direct library fields (requires --implicit-package)
4. Derived from local values
5. Derived from module fields
6. Derived from library fields (requires --implicit-package)
7. Structural from local values (__record / __tuple combiner)
8. Structural from module fields
9. Structural from library fields (requires --implicit-package)

Test plan

Run tests

• test/run/implicit-derivation.mo — basic derivation, monomorphic, polymorphic, multiple implicits, priority ordering, subtyping
• test/run/implicit-derivation-transitive.mo — [[Nat]] through two derivation levels
• test/run/implicit-derivation-recursive.mo — single recursion, mutual recursion, recursive trees
• test/run/implicit-derivation-record-variant.mo — real-world record/variant comparison with compareBy
• test/run/implicit-derivation-core.mo — integration with mo:core library (Array, Nat, Int, Text)
• test/run/implicit-derivation-implicit-package.mo — derivation from unimported library modules
• test/run/implicit-derivation-json.mo — structural derivation for JSON serialization (records, tuples, maps, lists)
• test/run/implicit-derivation-structural.mo — basic structural record derivation (unary)
• test/run/implicit-derivation-structural-compare.mo — binary structural derivation for record/tuple comparison
• test/run/implicit-derivation-structural-dispatch.mo — __record vs __tuple dispatch and binary/unary disambiguation

Fail tests (14 files)

• test/fail/implicit-derivation.mo — missing inner implicit, basic derivation errors
• test/fail/implicit-derivation-ambiguous.mo — ambiguous derived candidates at the head level
• test/fail/implicit-derivation-ambiguous-deep.mo — ambiguous inner implicit during derivation
• test/fail/implicit-derivation-bimatch.mo — bi-matching limits during type instantiation
• test/fail/implicit-derivation-deep.mo — derivation chain errors at multiple depths
• test/fail/implicit-derivation-depth.mo — --implicit-derivation-depth limit hit
• test/fail/implicit-derivation-no-backtracking.mo — no backtracking across derivation candidates
• test/fail/implicit-derivation-json.mo — real-world JSON errors: missing leaves, expanded Map types, nested records
• test/fail/implicit-derivation-structural-missing.mo — record with a field type that has no instance
• test/fail/implicit-derivation-structural-ambiguous.mo — two structural combiners in scope
• test/fail/implicit-derivation-structural-hint.mo — structural combiner in an unimported library (import hint)
• test/fail/implicit-derivation-structural-depth.mo — structural derivation depth limit
• test/fail/implicit-derivation-structural-record2-missing.mo — binary record derivation with missing field instance
• test/fail/implicit-derivation-structural-tuple-missing.mo — tuple derivation with missing element instance

Test package

• test/json-stub/ — minimal JSON package used by the structural derivation tests; demonstrates the __record convention and companion per-type modules (IntJson, TextJson, ArrayJson, ListJson, MapJson, Tuple2Json, Tuple3Json)

[github-actions]

Comparing from c8cf79a to 01de41c:
In terms of gas, no changes are observed in 5 tests.
In terms of size, no changes are observed in 5 tests.

[crusso]

Cool, any ideas how handle record and variants, where you don't have a function predefined?

[Kamirus]

Cool, any ideas how handle record and variants, where you don't have a function predefined?

I think that records and variants need an explicit compare function to say

1. Which fields take part in the comparison
2. In which order should the fields be compared

Then we could have helper functions defined in core (or compiler-derived) and use like:

type Foo = {
  name : Text;
  id : Nat;
  subs : List.List<Bar>;
};
module FooCompareByNameAndId {
  public func compare(a : Foo, b : Foo) : Order.Order {
    a.compareBy(b, func (r) { (r.name, r.id) })
    // `compareBy` should be defined in `Order.mo`
  }
};

So that a record/variant comparison could be defined via tuple comparison.
And to support tuple comparison we could either rely on helpers in mo:core in the Tuples module (that would work for tuples up to size N).
Or have the compiler derive those.

[crusso]

| `__variant`    | —  (Nat, Text, () -> R)   | — `Var -> R`  or `(Var, Var) -> R`                                    | Reserved for future extension                  |

Might work for variants.... (Nat is the ordinal of the tag, which, for records, can be inferred from the array index)

Maybe arrays should just be delayed (or use an iterator if ok with forcing the ordering)
[(Text, () -> E)] -> R

[Kamirus]

That's a really good idea to be go with lazy values () -> R, it'd give more flexibility to package authors (and they are the ones who write these __record/tuple/variant functions).
Better than Iter because they can choose which one to evaluate and when, yet still simple enough!

Just for the record: I'd implement variants in another PR. But I'm curious - Why would anyone need the Nat ordinal of the tag? Aren't we sorting tags in a variant anyway so that would make it tricky to preserve, right? Or am I misunderstanding or missing sth?

[crusso]

For efficient compare I would compare the ordinals before comparing the contents when ordinals match. Hash would work too but maybe more arbitrary and implementation specific than the ordinal of the label in the variants (which should be know statically, right?).

[crusso]

dubious promote on negative occurrence?

[crusso]

Ditto: dubious promote on negative occurrence?

[crusso]

Is there any way to present this PR as a diff to part 1 #5966? I tried to open a PR with this branch and the branch of #5966 as a base but it didn't reduce the diff for me.