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

Closes #415. Stdlib roadmap item #5 was framed as "cross-file `use`
resolvability from standalone check", but the actual underlying issue
turned out to be **discoverability**: cross-module `use` already works
(both `use Deno::{Json}` and `use prelude::*` resolve from a standalone
single-file check). What trips users is that 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.

This change:

1. Replaces face.ml's `Canonical` branch's `show_resolve_error` (raw
   record dump) with a real per-error-class formatter. Other faces
   were already formatted; only Canonical hadn't been touched here.

2. Adds a `prelude_hint` helper in both face.ml and typecheck.ml that,
   when an undefined name matches a known prelude export, appends:

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

   Covers both the resolve-time path (face.ml) and the typecheck-time
   path (typecheck.ml's UnboundVariable — fires e.g. when a match arm
   references an unbound constructor the resolver missed).

3. Hard-codes the prelude export list as the well-known 20 names
   (Option, Result, Some, None, Ok, Err + the function helpers). A
   missing name here means a worse error message, not incorrect
   behaviour. Comment in both files notes the list must mirror
   `stdlib/prelude.affine`.

Effect for users:

- BEFORE: `Resolution error: (Resolve.UndefinedVariable { Ast.name = "Some"; span = {...} })`
- 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.
  ```

Doesn't auto-import prelude (would revert #138). Doesn't change resolve
behaviour at all — only error rendering.

Test plan:

- [x] codegen-deno suite stays 7/7 green
- [x] Manual reproduction of the idaptik PR #107 case shows the hint
- [x] Non-prelude names (e.g. `nonexistentFn`) still get a clean error
      with NO inappropriate prelude hint
- [x] `dune build bin/main.exe` clean

Updates stdlib roadmap row #5 status `◑` partial → `●` usable in a
follow-up PR (so this PR stays focused on the diagnostic).

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)