feat(diagnostics): prelude-hint for UndefinedVariable / Unbound (stdlib #5) (#427)

Closes #415. Stdlib roadmap item #5 (`docs/stdlib-roadmap.adoc`).

## TL;DR

The original framing of stdlib #5 was *"cross-file \`use\` resolvability
from standalone check"*. Reproducing the bug turned up something
different: cross-module \`use\` **already works** (both \`use
Deno::{Json}\` and \`use prelude::*\` resolve fine from a standalone
single-file check).

What actually trips users is **discoverability** — prelude is NOT
auto-opened (deliberate, per issue #138), and the error when an
unimported \`Some\` is referenced was a raw OCaml record dump with no
hint about the fix.

## Before / after

**Before:**
\`\`\`
Resolution error: (Resolve.UndefinedVariable
   { Ast.name = "Some";
     span = { Span.start_pos = { Span.line = 1; col = 37; ... }; ... }
     })
\`\`\`

**After:**
\`\`\`
Resolution error: undefined value: \`Some\`
  hint: \`Some\` is defined in \`stdlib/prelude.affine\` — add
\`use prelude::{Some};\` (or \`use prelude::*;\`) at the top of the
file.
\`\`\`

## Files

| File | Change |
|---|---|
| \`lib/face.ml\` | Canonical face: replace \`show_resolve_error\` dump
with full per-error-class formatter; add \`prelude_hint\` for
UndefinedVariable + UndefinedType |
| \`lib/typecheck.ml\` | Add same \`prelude_hint\` on
\`UnboundVariable\` (typecheck-time path; fires for match arms whose
constructor reference the resolver missed) |

## What this does NOT do

- Does NOT auto-import prelude (that would revert issue #138 which
intentionally removed the band-aid)
- Does NOT change resolve behaviour at all — only the error message
- Does NOT touch the other faces (Python / Js / Pseudocode / Lucid /
Cafe) — they already had their own formatted hints; just Canonical was
raw-dumping

## Test plan

- [x] codegen-deno suite: 7/7 harnesses green (no behaviour change)
- [x] Manual: idaptik PR #107's case (missing \`Some\`) now shows the
hint
- [x] Manual: non-prelude names (e.g. \`nonexistentFn\`) still get a
clean error with NO inappropriate prelude hint
- [x] \`dune build bin/main.exe\` clean
- [x] \`dune build @runtest\` — 340/342 pass; the 2 failures are
pre-existing E2E Node-CJS Codegen baseline flakes (CLAUDE.md
"Known-failing baseline checks"), unchanged by this PR

## Follow-ups

Once this lands, a follow-up PR updates \`docs/stdlib-roadmap.adoc\` row
#5 status \`◑\` partial → \`●\` usable (kept out of this PR so the diff
stays focused on the diagnostic itself).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

lib/face.ml

@@ -549,10 +549,49 @@ let format_borrow_error (face : face) (err : Borrow.borrow_error) : string =
 
 (* ─── Resolve errors ─────────────────────────────────────────────────── *)
 
+(* Known exports of stdlib/prelude.affine. When an UndefinedVariable /
+   UndefinedType fires with one of these names, the error formatter
+   suggests `use prelude::{...}` — the discoverability gap that issue
+   #138's "no flat builtin seeding" + stdlib roadmap #5 surfaced.
+   Keep this list in sync with stdlib/prelude.affine; a missing name
+   here means a worse error message, not incorrect behaviour. *)
+let prelude_exports = [
+  (* Types *)
+  "Option"; "Result";
+  (* Constructors *)
+  "Some"; "None"; "Ok"; "Err";
+  (* Functions *)
+  "map"; "filter"; "fold"; "contains";
+  "sum"; "product"; "min"; "max"; "clamp";
+  "not"; "all"; "any"; "range"; "repeat";
+]
+
+let prelude_hint (name : string) : string =
+  if List.mem name prelude_exports then
+    Printf.sprintf "\n  hint: `%s` is defined in `stdlib/prelude.affine` — add `use prelude::{%s};` (or `use prelude::*;`) at the top of the file."
+      name name
+  else ""
+
 (** Format a name-resolution error for the given face. *)
 let format_resolve_error (face : face) (err : Resolve.resolve_error) : string =
   match face with
-  | Canonical -> Resolve.show_resolve_error err
+  | Canonical ->
+    (match err with
+     | Resolve.UndefinedVariable id ->
+       Printf.sprintf "undefined value: `%s`%s" id.name (prelude_hint id.name)
+     | Resolve.UndefinedType id ->
+       Printf.sprintf "undefined type: `%s`%s" id.name (prelude_hint id.name)
+     | Resolve.UndefinedEffect id ->
+       Printf.sprintf "undefined effect: `%s`" id.name
+     | Resolve.UndefinedModule id ->
+       Printf.sprintf "undefined module: `%s`\n  hint: add `use %s::{...};` at the top of the file."
+         id.name id.name
+     | Resolve.DuplicateDefinition id ->
+       Printf.sprintf "duplicate definition of `%s`" id.name
+     | Resolve.VisibilityError (id, msg) ->
+       Printf.sprintf "`%s` is not accessible here: %s" id.name msg
+     | Resolve.ImportError msg ->
+       Printf.sprintf "import error: %s" msg)
   | Python ->
     (match err with
     | Resolve.UndefinedVariable id ->

lib/typecheck.ml

@@ -113,9 +113,29 @@ type type_error =
           raised when a row is declared; an undeclared row stays
           permissive under tracking-only v1. *)
 
+(* Known exports of stdlib/prelude.affine. Mirrors the same list in
+   lib/face.ml — when an UnboundVariable fires at type-check time with
+   one of these names, the formatter suggests `use prelude::{...}`.
+   Same discoverability fix as the resolver path; the typechecker has
+   its own miss path (e.g. match arms reference unbound constructors
+   that the resolver missed). Keep in sync with stdlib/prelude.affine. *)
+let prelude_exports = [
+  "Option"; "Result";
+  "Some"; "None"; "Ok"; "Err";
+  "map"; "filter"; "fold"; "contains";
+  "sum"; "product"; "min"; "max"; "clamp";
+  "not"; "all"; "any"; "range"; "repeat";
+]
+
+let prelude_hint (name : string) : string =
+  if List.mem name prelude_exports then
+    Printf.sprintf "\n  hint: `%s` is defined in `stdlib/prelude.affine` — add `use prelude::{%s};` (or `use prelude::*;`) at the top of the file."
+      name name
+  else ""
+
 (** Format a type error for human consumption. *)
 let show_type_error = function
-  | UnboundVariable v -> "Unbound variable: " ^ v
+  | UnboundVariable v -> "Unbound variable: " ^ v ^ prelude_hint v
   | TypeMismatch { expected; got } ->
     Printf.sprintf "Type mismatch: expected %s, got %s"
       (ty_to_string expected) (ty_to_string got)