reject builtin-named user functions at parse time

[danieljohnmorris]

Summary

Defining a user function whose name collides with a builtin (lst, sum, clamp, avg, …) used to fail with a misleading ILO-T006 arity error from the builtin's signature. Personas had no signal their name was already taken and debugged the arity error down the wrong path.

This extends the existing ILO-P011 reserved-name precedent (parse_stmt already does this for fld=5/cnt=/brk= bindings) into parse_fn_decl. One-location fix in the parser, so tree/VM/Cranelift all surface the same friendly diagnostic before any engine dispatch runs.

Manifesto framing: replaces a silent shadow + misleading error with an explicit named, fixable error the first time round. Less retry tax, less debugging into the wrong codepath.

Repro

Before:

$ ilo 'lst>n;42
main>n;lst()' main
{"code":"ILO-T006","message":"arity mismatch: 'lst' expects 3 args, got 0", ...}

After:

$ ilo 'lst>n;42
main>n;lst()' main
{"code":"ILO-P011","message":"`lst` is a builtin and cannot be used as a function name",
 "suggestion":"rename to something like `mylst` or `lstof` — builtins shadow user functions in calls, so reusing the name silently breaks dispatch"}

Renaming to anything non-builtin (e.g. show) compiles and runs cleanly.

What's in the diff

• f51735e parser: check Builtin::is_builtin(&name) right after expect_ident() in parse_fn_decl, emit ILO-P011 with a rename hint. Also updates two graph.rs unit tests that had used inv and sum as fixture function names (both are builtins); renamed to not and total.
• 4e8fe44 tests: new tests/regression_builtin_fn_name.rs covering ten builtin names (lst, hd, tl, slc, cat, has, len, str, num, map) across tree/VM/Cranelift, plus the original repro asserting ILO-P011 precedes any downstream ILO-T006 cascade, plus a rename-still-works sanity test, plus a lst builtin call sanity test. New examples/builtin-fn-name-rename.ilo gives agents an in-context demo of the correct pattern.
• 1a21e67 docs: renamed three stock examples that previously taught the wrong pattern (examples/arithmetic.ilo avg→mean3, examples/builtins.ilo and examples/guards.ilo clamp→clmp), and the same shape in SPEC.md's multi-function-files section. ai.txt regenerates from SPEC.md.

Test plan

• cargo test --release --features cranelift full suite green (2866 lib + all integration)
• cargo fmt --check clean
• cargo clippy --release --features cranelift --all-targets -- -D warnings clean
• New regression suite covers tree/VM/Cranelift for 10 builtin names + the original lst() repro
• New example file examples/builtin-fn-name-rename.ilo runs to 42 on every engine via tests/examples_engines.rs
• All updated stock examples still pass tests/examples.rs
• fld=5 reserved-name precedent (tests/regression_fld_reserved.rs) still green

Follow-ups

None tracked. The rename hint is intentionally generic (my{name} / {name}of) to cover any builtin without a hand-curated dictionary; could be made name-specific later if persona feedback shows the generic form isn't sticky enough.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!