feat(resolve): INT-01 — wire qualified-value path use Mod; Mod.fn(x) (Refs #178) (#253)

The INT-01 follow-up recorded after #244: `use Mod;` + qualified *value*
call `Mod.fn(x)` failed with Resolve.UndefinedVariable on the qualifier.

Root cause: `use Mod;` (ImportSimple) flat-imports Mod's public symbols
(import_resolved_symbols) but binds no module namespace; the parser yields
ExprField(ExprVar Mod, fn) (ExprSpan-wrapped), and resolve.ml's ExprField
case drops the field and resolves the base ExprVar Mod -> undefined. So
`Mod.fn` could never resolve even though `fn` was in scope flat.

Fix: a pure, idempotent, total parse-boundary lowering
`Resolve.lower_qualified_value_paths : program -> program` that rewrites
`ExprField(ExprVar m, fld)` -> `ExprVar fld` when `m` is an ImportSimple
qualifier (alias preferred; ImportList/ImportGlob bind no qualifier).
Span-peels the base; genuine record access `r.f` is untouched (`r` is not
an import qualifier). This is the value-expression analogue of #241/ADR-014
(qualified type/effect paths in the grammar). Applied once in
`parse_with_face` so resolve/typecheck/borrow/quantity/codegen all see the
lowered form uniformly; the formatter uses a separate path
(Formatter.format_file) so `fmt` preserves source `Mod.fn`. Embedders that
bypass parse_with_face call the exposed function (as the tests do) —
boundary documented in INT-01.

Verified (oracle): `use CrossCallee; CrossCallee.consume(42)` and
`use CrossCallee as CC; CC.consume(7)` -> Type checking passed;
`use CrossCallee::{consume}; consume(42)` still passes (no regression);
genuine `p.x` preserved. Full gate 275/275 (was 271; +4 hermetic
"E2E Qualified Value #178" regression tests + 2 fixtures).

Scope (honest): the `.`-qualified value path (the recorded gap) is closed.
`Mod::fn(x)` in *expression* position remains a parse error — a DISTINCT
parser gap (`::` is reserved for Type::Variant in expr position), not the
resolver; tracked as a separate follow-up. Refs #178 (not Closes).

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

Author: hyperpolymath

bin/main.ml

@@ -101,13 +101,20 @@ let resolve_face ?(quiet = false) face path =
 
 (** Parse a file using the requested face. *)
 let parse_with_face (face : Affinescript.Face.face) path =
-  match face with
-  | Affinescript.Face.Canonical   -> Affinescript.Parse_driver.parse_file path
-  | Affinescript.Face.Python      -> Affinescript.Python_face.parse_file_python path
-  | Affinescript.Face.Js          -> Affinescript.Js_face.parse_file_js path
-  | Affinescript.Face.Pseudocode  -> Affinescript.Pseudocode_face.parse_file_pseudocode path
-  | Affinescript.Face.Lucid       -> Affinescript.Lucid_face.parse_file_lucid path
-  | Affinescript.Face.Cafe        -> Affinescript.Cafe_face.parse_file_cafe path
+  let prog =
+    match face with
+    | Affinescript.Face.Canonical   -> Affinescript.Parse_driver.parse_file path
+    | Affinescript.Face.Python      -> Affinescript.Python_face.parse_file_python path
+    | Affinescript.Face.Js          -> Affinescript.Js_face.parse_file_js path
+    | Affinescript.Face.Pseudocode  -> Affinescript.Pseudocode_face.parse_file_pseudocode path
+    | Affinescript.Face.Lucid       -> Affinescript.Lucid_face.parse_file_lucid path
+    | Affinescript.Face.Cafe        -> Affinescript.Cafe_face.parse_file_cafe path
+  in
+  (* #178 INT-01: lower `use Mod;` + qualified value path `Mod.fn` to the
+     flat-imported `fn` so resolve/typecheck/codegen see it uniformly. The
+     formatter uses a separate path (Formatter.format_file) and is unaffected,
+     so source `Mod.fn` is preserved on `fmt`. *)
+  Affinescript.Resolve.lower_qualified_value_paths prog
 
 (** Preview the Python-face text transform (debug tool). *)
 let preview_python_transform path =

docs/ECOSYSTEM.adoc

@@ -181,8 +181,9 @@ link:TECH-DEBT.adoc[TECH-DEBT.adoc].
 |ID |Item |Issue |Status
 
 |INT-01 |Cross-module WASM import emission (the substrate) |#178 |
-`use Mod::{fn}`/`::*` PROVEN+locked (271 gate + deno link harness);
-`use Mod;`+qualified-value-call resolver gap remains (distinct)
+`use Mod::{fn}`/`::*` PROVEN+locked (deno link harness); `use Mod;`/`as`
++ `Mod.fn(x)` qualified-value path WIRED+locked (parse-boundary lowering;
+4 hermetic tests). Distinct parser follow-up: `Mod::fn(x)` in expr position
 |INT-02 |Host-agnostic loader bridge (`affinescript-dom-loader`) |#179 |loader
 landed in `packages/affine-js` (SAT-02 fixed; Deno/Node/browser parity,
 multi-namespace import object, ownership-section accessor). S1; unblocks

docs/TECH-DEBT.adoc

@@ -145,10 +145,17 @@ indices line up: *PROVEN end-to-end* (two separately-compiled `.wasm`
 link + execute, cross-call = 42) and regression-locked — hermetic
 structural test in the gate (271/271) + reproducible deno harness
 `tests/modules/xmod-link/`. Multi-file libraries via `use Mod::{…}` are
-shippable. *Remaining (distinct, NOT emission):* `use Mod;` + qualified
-value call `Mod.fn(x)` hits a resolution error (post-#228 qualified-value
-resolution unwired) — own follow-up. |S1 |`use ::{}`/`::*` DONE (PR Refs
-#178); qualified-value-call resolver gap open #178
+shippable. *Qualified-value path now wired:* `use Mod;` (or `use Mod as M;`)
++ `Mod.fn(x)` resolves+typechecks — pure parse-boundary lowering
+`Resolve.lower_qualified_value_paths` (applied in `parse_with_face`;
+embedders bypassing it call it directly — the formatter is unaffected, so
+source `Mod.fn` is preserved on `fmt`); regression-locked (4 hermetic
+tests, "E2E Qualified Value #178"). *Remaining (distinct, NOT this unit —
+a parser gap, not the resolver):* `Mod::fn(x)` in *expression* position is
+a parse error (`::`-in-value-expr unwired; `::` reserved for
+`Type::Variant`). |S1 |`use ::{}`/`::*` + `use Mod;`/`as`-qualified
+`Mod.fn(x)` DONE (PR Refs #178); `::`-in-expression a separate parser
+follow-up
 |INT-02 |Host-agnostic loader bridge |S1 |open #179 (blocks INT-05/08/11)
 |INT-03 |WASI preview2 / host I/O |S1 |#180 ADR-015 accepted (full
 Component-Model re-target, staged S1..S6); S3+ hard-gated on S2

lib/resolve.ml

@@ -831,6 +831,133 @@ let resolve_program_with_imports (program : program) : (context, resolve_error *
   | Error e -> Error e
 
 (** Resolve a complete program with module loader support *)
+(* ---- #178 INT-01: lower module-qualified value paths --------------------
+   `use Mod;` (ImportSimple) flat-imports Mod's public symbols (see
+   [import_resolved_symbols]), so a qualified *value* reference `Mod.fn` /
+   `Mod.fn(x)` denotes the same flat symbol `fn`. The parser yields
+   `ExprField (ExprVar Mod, fn)` (optionally ExprSpan-wrapped); rewrite it to
+   `ExprVar fn` when `Mod` is a bound module qualifier from [prog_imports].
+   This is the value-expression analogue of #241/ADR-014 (which handled
+   qualified *type/effect* paths in the grammar). Pure; applied once on the
+   parsed program before resolve/typecheck/codegen so every backend sees the
+   lowered form uniformly. Genuine record access `r.f` is untouched (`r` is
+   not an import qualifier). Only ImportSimple binds a qualifier; ImportList
+   / ImportGlob bring names unqualified and bind no module name. *)
+let import_qualifiers (imports : import_decl list) : (string, unit) Hashtbl.t =
+  let h = Hashtbl.create 8 in
+  List.iter (fun imp -> match imp with
+    | ImportSimple (path, alias) ->
+      let name = match alias with
+        | Some id -> id.name
+        | None -> (match List.rev path with id :: _ -> id.name | [] -> "")
+      in
+      if name <> "" then Hashtbl.replace h name ()
+    | ImportList _ | ImportGlob _ -> ()
+  ) imports;
+  h
+
+let rec strip_span (e : expr) : expr =
+  match e with ExprSpan (e', _) -> strip_span e' | e -> e
+
+let rec lower_expr quals (e : expr) : expr =
+  match e with
+  | ExprField (base, fld) ->
+    (match strip_span base with
+     | ExprVar m when Hashtbl.mem quals m.name -> ExprVar fld
+     | _ -> ExprField (lower_expr quals base, fld))
+  | ExprSpan (e', sp) -> ExprSpan (lower_expr quals e', sp)
+  | ExprLit _ | ExprVar _ | ExprVariant _ -> e
+  | ExprLet r ->
+    ExprLet { r with el_value = lower_expr quals r.el_value;
+                     el_body = Option.map (lower_expr quals) r.el_body }
+  | ExprIf r ->
+    ExprIf { ei_cond = lower_expr quals r.ei_cond;
+             ei_then = lower_expr quals r.ei_then;
+             ei_else = Option.map (lower_expr quals) r.ei_else }
+  | ExprMatch r ->
+    ExprMatch { em_scrutinee = lower_expr quals r.em_scrutinee;
+                em_arms = List.map (lower_arm quals) r.em_arms }
+  | ExprLambda r -> ExprLambda { r with elam_body = lower_expr quals r.elam_body }
+  | ExprApp (f, args) ->
+    ExprApp (lower_expr quals f, List.map (lower_expr quals) args)
+  | ExprTupleIndex (e1, i) -> ExprTupleIndex (lower_expr quals e1, i)
+  | ExprIndex (a, i) -> ExprIndex (lower_expr quals a, lower_expr quals i)
+  | ExprTuple es -> ExprTuple (List.map (lower_expr quals) es)
+  | ExprArray es -> ExprArray (List.map (lower_expr quals) es)
+  | ExprRecord r ->
+    ExprRecord
+      { er_fields =
+          List.map (fun (id, eo) -> (id, Option.map (lower_expr quals) eo))
+            r.er_fields;
+        er_spread = Option.map (lower_expr quals) r.er_spread }
+  | ExprRowRestrict (e1, id) -> ExprRowRestrict (lower_expr quals e1, id)
+  | ExprBinary (l, op, r) -> ExprBinary (lower_expr quals l, op, lower_expr quals r)
+  | ExprUnary (op, e1) -> ExprUnary (op, lower_expr quals e1)
+  | ExprBlock b -> ExprBlock (lower_block quals b)
+  | ExprReturn eo -> ExprReturn (Option.map (lower_expr quals) eo)
+  | ExprTry r ->
+    ExprTry { et_body = lower_block quals r.et_body;
+              et_catch = Option.map (List.map (lower_arm quals)) r.et_catch;
+              et_finally = Option.map (lower_block quals) r.et_finally }
+  | ExprHandle r ->
+    ExprHandle { eh_body = lower_expr quals r.eh_body;
+                 eh_handlers = List.map (lower_handler quals) r.eh_handlers }
+  | ExprResume eo -> ExprResume (Option.map (lower_expr quals) eo)
+  | ExprUnsafe ops -> ExprUnsafe (List.map (lower_unsafe quals) ops)
+
+and lower_arm quals a =
+  { a with ma_guard = Option.map (lower_expr quals) a.ma_guard;
+           ma_body = lower_expr quals a.ma_body }
+
+and lower_handler quals = function
+  | HandlerReturn (p, e) -> HandlerReturn (p, lower_expr quals e)
+  | HandlerOp (id, ps, e) -> HandlerOp (id, ps, lower_expr quals e)
+
+and lower_unsafe quals = function
+  | UnsafeRead e -> UnsafeRead (lower_expr quals e)
+  | UnsafeWrite (a, b) -> UnsafeWrite (lower_expr quals a, lower_expr quals b)
+  | UnsafeOffset (a, b) -> UnsafeOffset (lower_expr quals a, lower_expr quals b)
+  | UnsafeTransmute (t1, t2, e) -> UnsafeTransmute (t1, t2, lower_expr quals e)
+  | UnsafeForget e -> UnsafeForget (lower_expr quals e)
+
+and lower_block quals b =
+  { blk_stmts = List.map (lower_stmt quals) b.blk_stmts;
+    blk_expr = Option.map (lower_expr quals) b.blk_expr }
+
+and lower_stmt quals = function
+  | StmtLet r -> StmtLet { r with sl_value = lower_expr quals r.sl_value }
+  | StmtExpr e -> StmtExpr (lower_expr quals e)
+  | StmtAssign (a, op, b) ->
+    StmtAssign (lower_expr quals a, op, lower_expr quals b)
+  | StmtWhile (e, b) -> StmtWhile (lower_expr quals e, lower_block quals b)
+  | StmtFor (p, e, b) -> StmtFor (p, lower_expr quals e, lower_block quals b)
+
+let lower_fn_body quals = function
+  | FnBlock b -> FnBlock (lower_block quals b)
+  | FnExpr e -> FnExpr (lower_expr quals e)
+  | FnExtern -> FnExtern
+
+let lower_top quals = function
+  | TopFn fd -> TopFn { fd with fd_body = lower_fn_body quals fd.fd_body }
+  | TopConst r -> TopConst { r with tc_value = lower_expr quals r.tc_value }
+  | TopImpl ib ->
+    TopImpl { ib with ib_items = List.map (function
+      | ImplFn fd -> ImplFn { fd with fd_body = lower_fn_body quals fd.fd_body }
+      | ImplType _ as it -> it) ib.ib_items }
+  | TopTrait td ->
+    TopTrait { td with trd_items = List.map (function
+      | TraitFnDefault fd ->
+        TraitFnDefault { fd with fd_body = lower_fn_body quals fd.fd_body }
+      | other -> other) td.trd_items }
+  | (TopType _ | TopEffect _ | TopExternType _ | TopExternFn _) as t -> t
+
+(** #178: lower module-qualified value paths. Idempotent, pure. *)
+let lower_qualified_value_paths (program : program) : program =
+  let quals = import_qualifiers program.prog_imports in
+  if Hashtbl.length quals = 0 then program
+  else { program with
+         prog_decls = List.map (lower_top quals) program.prog_decls }
+
 let resolve_program_with_loader
     (program : program)
     (loader : Module_loader.t) : (context * Typecheck.context) result =

test/e2e/fixtures/cross_caller_qualified.affine

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell
+//
+// #178 INT-01: `use Mod;` + qualified *value* call `Mod.fn(x)`. Before the
+// qualified-value lowering this failed with Resolve.UndefinedVariable on the
+// module qualifier (it parsed as field access on an undefined variable).
+
+use CrossCallee;
+
+pub fn main() -> Int {
+  return CrossCallee.consume(42);
+}

test/e2e/fixtures/cross_caller_qualified_alias.affine

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell
+//
+// #178 INT-01: aliased qualifier — `use CrossCallee as CC;` + `CC.consume(x)`.
+// The alias is the bound qualifier (import_qualifiers prefers the alias).
+
+use CrossCallee as CC;
+
+pub fn main() -> Int {
+  return CC.consume(7);
+}

test/test_e2e.ml

@@ -3346,6 +3346,69 @@ let qualified_path_tests = [
   Alcotest.test_case "bare unqualified forms unaffected"  `Quick test_qual_unqualified_still_parses;
 ]
 
+(* ---- #178 INT-01: qualified *value* path  use Mod; Mod.fn(x) ----------
+   The companion to #228 (qualified type/effect paths). Mirrors the CLI's
+   parse→lower→resolve→typecheck (the lowering is applied at the parse
+   boundary by `parse_with_face`; embedders bypassing it call the exposed
+   `Resolve.lower_qualified_value_paths` — exactly as here). Hermetic. *)
+let qualval_frontend_ok path : bool =
+  let loader = Module_loader.create {
+    Module_loader.stdlib_path = "stdlib";
+    search_paths = [];
+    current_dir = fixture_dir;
+  } in
+  match parse_fixture path with
+  | Error _ -> false
+  | Ok raw ->
+    let prog = Resolve.lower_qualified_value_paths raw in
+    (match Resolve.resolve_program_with_loader prog loader with
+     | Error _ -> false
+     | Ok (resolve_ctx, import_type_ctx) ->
+       (match Typecheck.check_program
+                ~import_types:import_type_ctx.Typecheck.name_types
+                resolve_ctx.symbols prog with
+        | Error _ -> false
+        | Ok _ -> true))
+
+let test_qualval_dot_call () =
+  Alcotest.(check bool)
+    "use CrossCallee; CrossCallee.consume(42) resolves+typechecks" true
+    (qualval_frontend_ok (fixture "cross_caller_qualified.affine"))
+
+let test_qualval_alias_call () =
+  Alcotest.(check bool)
+    "use CrossCallee as CC; CC.consume(7) resolves+typechecks" true
+    (qualval_frontend_ok (fixture "cross_caller_qualified_alias.affine"))
+
+let test_qualval_item_import_regression () =
+  Alcotest.(check bool)
+    "use CrossCallee::{consume}; consume(42) still works (no regression)" true
+    (qualval_frontend_ok (fixture "cross_caller_ok.affine"))
+
+let test_qualval_record_access_unaffected () =
+  (* Genuine record projection must NOT be rewritten: `p` is a value, not an
+     import qualifier, so `p.x` stays field access. *)
+  let src = {|module RecGuard;
+struct P { x: Int, y: Int }
+fn getx(p: P) -> Int { return p.x; }|} in
+  let prog = Resolve.lower_qualified_value_paths
+      (Parse_driver.parse_string ~file:"<test>" src) in
+  let loader = Module_loader.create (Module_loader.default_config ()) in
+  Alcotest.(check bool) "p.x preserved (not lowered)" true
+    (match Resolve.resolve_program_with_loader prog loader with
+     | Ok (rc, itc) ->
+       (match Typecheck.check_program
+                ~import_types:itc.Typecheck.name_types rc.symbols prog with
+        | Ok _ -> true | Error _ -> false)
+     | Error _ -> false)
+
+let qualified_value_tests = [
+  Alcotest.test_case "use Mod; Mod.fn(x) resolves (#178)"       `Quick test_qualval_dot_call;
+  Alcotest.test_case "use Mod as M; M.fn(x) resolves (#178)"    `Quick test_qualval_alias_call;
+  Alcotest.test_case "use Mod::{fn}; fn(x) no regression"       `Quick test_qualval_item_import_regression;
+  Alcotest.test_case "genuine record access p.x unaffected"     `Quick test_qualval_record_access_unaffected;
+]
+
 (* ---- Type-syntax sugars: fn(...) -> T, Option<T>, (A, B) -> C ---- *)
 
 let parse_check_passes src : bool =
@@ -3743,6 +3806,7 @@ let tests =
     ("E2E Vscode Bindings",      vscode_bindings_tests);
     ("E2E Array Type Sugar",     array_type_tests);
     ("E2E Qualified Paths #228",  qualified_path_tests);
+    ("E2E Qualified Value #178",  qualified_value_tests);
     ("E2E WasmGC PatCon Destructure", wasm_gc_patcon_tests);
     ("E2E Type Syntax Sugar",         type_syntax_sugar_tests);
   ]