M2: Explicit ad-hoc overloading (operators + Text comparison)

[assapir]

Summary

Adds explicit ad-hoc overloading as Quilon's only polymorphism (no generics): multiple same-named top-level definitions, each with full parameter type annotations, form an overload set resolved at every call site by exact static argument types (no implicit coercion). Ambiguity / no-match are clear file:line:col diagnostics that list the candidates.

• Operators are user-overloadable (+ - * / % == != < <= > >=) — an operator is just a named overload set. The standard built-ins (+ on Num/Text, the comparisons, print/eprint over Num/Text/Bool) are now visible overloads routed through the same mechanism, not compiler special cases (behavior preserved; all prior tests pass).
• Text comparison (the gating deliverable): ==/!= (equality) and </<=/>/>= (lexicographic) over Text, via a new __text_cmp runtime intrinsic — typecheck + codegen + tests, end-to-end (JIT + native AOT).
• < / > vs < > blocks: a > is the block close only when it is the last token on its line; otherwise it is the greater-than operator, so a > b works everywhere.
• Ok/NotOk over every built-in payload (Num/Text/Bool/$) construct and tag-dispatch.

Pipeline

• Lexer: line-final > reclassification → new Gt token.
• Parser: operator-symbol-named definitions; </Gt as comparison operators; binary-op loops stop at a top-level operator definition (op =).
• Typechecker: overload-set registry keyed by name (functions AND operator symbols); built-in operator/print overloads; exact-type dispatch; NoMatchingOverload / AmbiguousOverload / OverloadMissingAnnotation errors.
• Codegen: each overload member mangled to a distinct symbol; calls/operators lowered to the resolved member; Text comparisons via __text_cmp; records GC-allocated so a record returned from a function/operator survives its frame; Bool ==/!= lowered as integer compares; match payload bindings carry their declared type so an overloaded call on a concrete sum payload dispatches by that type.

Example (mandatory, wired into the gate)

examples/overloading.ql — a user function overload set + a user operator overload (== on a record) + Text comparison; ^ exit code 161. Listed in tests/examples_test.rs (compiles + runs under JIT and native AOT, both linkers) and referenced from LANGUAGE.md.

Tests

Unit + integration + negative coverage: overload resolution by type, operator overload on a user type, Text ==/</> ordering, Bool ==, Ok($)/Ok(Text)/Ok(Num) dispatch, a user sum's concrete (Num and Bool) payload dispatching an overload, and negative cases (ambiguous / no-match / missing annotation → compile error; the > footguns → parse error).

Review fixes included

Found via /code-review: codegen now reads each non-overloaded function's declared return type so a call result feeding an overloaded operator mangles correctly (BUG1); the parser no longer absorbs a following operator definition into the previous expression body (BUG2); loop-variable and sum-payload bindings carry their concrete type for overloaded dispatch (BUG4 + the Bool-payload miscompile). /simplify: shared is_operator_symbol + FunctionDecl::is_inert_io_placeholder in the AST crate; lazy error-candidate construction.

Deferred (separate PR)

Concrete sum-payload typing: a non-numeric Result payload (Ok("x")) routed through an overload is part of the existing non-numeric-payload limitation (documented in LANGUAGE.md). A Result payload resolves deterministically as Num for overloads (numeric payloads work end-to-end). User sum types' concrete payloads dispatch correctly.

🤖 Generated with Claude Code