Fix #14: an overload member's signature is fixed at its definition

[assapir]

What was broken

Verified on main before writing code (finding 12 taught us premises go stale — this one does not). An overload member's return type defaulted to Num when the definition omitted it and was corrected only after the member's body was checked, so what a call saw depended on where it sat relative to the definition. Four distinct symptoms, all live:

Program	Before
Forward call, unannotated member, stale Num matches a real member	check passes, run → ❌ Overload not found: g$N
Forward call, unannotated member, no Num member exists	bogus No overload of 'g' matches (Num). Candidates: (Text), (Bool)
Caller annotated -> Text	bogus Type mismatch: expected Text, got Num — a type nobody wrote
Self- or mutually recursive unannotated member returning non-Num	unwritable at all

And a second half of the same finding, independent of annotations: members were registered in a pre-pass, so a call could resolve against a definition further down the file that codegen then had no symbol for. A fully annotated program:

even = (n :: Num) -> Bool => n == 0 ? true : odd(n - 1)   ~ odd defined below
odd  = (n :: Num) -> Bool => n == 0 ? false : even(n - 1)

→ check passes, run → ❌ Overload not found: odd$N. That is the checker/codegen contract break the finding names, and the source of the error string it quotes.

What changed (maintainer's decisions)

1. A member must annotate its return type, as it already had to annotate every parameter. Overload::ret is now Option<Type> — omitted means unknown, not Num, so the placeholder cannot answer a call — and the omission is reported where it bites:

• at the call that needed the result type: cannot call 'g': its overload member (Num) has no return type annotation — annotate it, since exact dispatch needs the full signature
• at the definition when nothing calls it: overload member 'g' (Num) has no return type annotation — …

The post-hoc refinement from the body is gone: adopting the inferred body type would make a member's signature depend on where a call sits, which is the disease. Annotating fixes it, and a recursive member becomes expressible (p = (n :: Num) -> Text => n == 0 ? "done" : p(n - 1) now compiles and runs).

2. No hoisting. A member joins its set as its definition is reached, so a call resolves only against the members above it — the rule plain functions already followed (^ = () -> Num => later() has always been Undefined variable 'later'). A forward call now says so: cannot call 'odd' before its definition — Quilon resolves names top to bottom; move the definition above this call. A definition is still in scope for its own body, so self-recursion is unaffected. Mutual recursion between top-level functions is not expressible — it never worked, it only looked type-checked.

Consequences worth flagging: an unannotated comparison-operator overload (==, <=, …) now asks for the annotation instead of reporting that it must return Bool (the actionable message wins); and Overload::builtin was deleted, since the refinement pass was its only reader.

Coverage

• 8 checker tests: call-site and definition-site anchoring, refinement never rescuing an unannotated member, recursion rejected-then-working, forward call rejected, mutual recursion rejected, a call resolving against only the members above it, and the comparison-operator case.
• 2 JIT exit-code tests: a recursive annotated member runs; a call uses the member defined above it.
• examples/overload_dispatch.ql extended (self-asserting, in the examples gate): a member defined above its caller, and a recursive member reaching itself.
• Docs: LANGUAGE.md gains a "Names resolve top to bottom" section (stating the rule for plain functions and members, and that mutual recursion is therefore not expressible) plus the return-annotation requirement in the overloading section; CLAUDE.md's overloading bullet updated; CHANGELOG under Unreleased.

Notes

• Nothing in corelib/, examples/, or the test suite relied on either behavior — the whole suite was green before I added a line of test.
• main moved twice during this work (Source-level debugging (Phase 1): DWARF line info + quilon build --debug #102/Validate & prune Known Limitations #107, then Prepare 0.9.1 release #103's tagged v0.9.1 and Fix watermark follow-ups: false strip claim, issue refs, test/polish cleanups #110). Merged both. The v0.9.1 merge folded my changelog entries into the released 0.9.1 section; since v0.9.1 is tagged and pushed, I moved them to a fresh Unreleased instead of editing release history. Fold them into 0.9.1 only if you consider that section still open.
• Out of scope per the maintainer: making plain top-level functions callable before their definition (i.e. hoisting) — explicitly rejected as a direction, and now documented as a language rule instead.

Gate

cargo fmt --all -- --check, cargo clippy --all-targets --all-features -- -D warnings, and the full suite under RUSTFLAGS=-D warnings are clean (-- --test-threads=1; under default parallelism tail_call_test hits the pre-existing #98 GC abort, reproducible on unmodified main).

🤖 Generated with Claude Code