hyperpolymath · hyperpolymath · May 19, 2026 · May 19, 2026
diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml
@@ -872,3 +872,69 @@ references = [
   "stdlib/Vscode.affine + packages/affine-vscode/mod.js (#205 thenableThen)",
   "typed-wasm ADR-004 (convergence / aggregate library; Ephapax)",
 ]
+
+[[adr]]
+id = "ADR-014"
+status = "accepted"
+date = "2026-05-19"
+title = "Module-qualified type/effect path separator: both `.` and `::`, `::` canonical"
+context = """
+The type/effect grammar had NO module-qualified path production: a
+qualified reference such as `Externs.Res` or `Externs.Net` was
+unrepresentable in any type or effect position and failed with
+`parse error` at the `.` (issue #228). An audit of the estate `.affine`
+corpus (compiler-as-oracle, origin/main) found this the SINGLE dominant
+fault estate-wide: 525 of ~1177 files fail to parse, qualified-path the
+leading cause in every hand-written Frontier-playbook TS-port. ADR-011
+already settled "real modules with qualified paths"; the consequence was
+unspeakable because the grammar could not name a module-qualified
+entity. Per ADR-012 (grammar changes are correctness assertions),
+closing this is asserting a settled truth, not adding sugar. The
+separator was the open, escalated language-design call: `module_path`
+(parser.mly) uses DOT; `use`/value paths use COLONCOLON (ADR-011
+`Result::unwrap`, `use option::{…}`); the estate corpus uses `.` for
+qualified types.
+"""
+decision = """
+Accept BOTH `.` and `::` (mixed permitted) as the module-qualified
+type/effect path separator. `Pkg::Type` is the CANONICAL form
+(consistent with ADR-011 value paths — one canonical separator
+estate-wide long-term). `.` is tolerated and normalised to `::`.
+
+Implementation (parser.mly, conflict-neutral):
+- New `qualified_type_name` (>=2 `upper_ident` segments, right-recursive,
+  `qsep = DOT | COLONCOLON`), folded into a single canonical `::`-joined
+  ident string. Added to `type_expr_primary` (TyCon / TyApp via `[ ]`
+  and `< >`) and `effect_term` (EffVar / EffCon).
+- Because the qualified name is folded to one ident, downstream
+  (resolve/typecheck/all codegens) sees a single ident and needs no
+  change; the formatter prints the stored `::` form, so `.`→`::`
+  normalisation is automatic with NO formatter change.
+- Conflict-neutral by construction: it only adds DOT/COLONCOLON as
+  lookahead after a type/effect-position `upper_ident`, where no reduce
+  action previously existed (that void is precisely the
+  `parse error at .` #228 reports). Measured: Menhir conflict states
+  unchanged at 21 S/R + 1 R/R; item counts unchanged at 68 S/R / 7 R/R.
+- Resolution of the qualified name against a real module is a separate
+  concern (the parse gap is what #228 names); the grammar PR unblocks
+  parsing — most of the 525 estate parse failures clear with zero
+  consumer churn. Genuine ReScript-surface residue (#229) is tracked
+  separately.
+"""
+consequences = """
+- The estate `.affine` corpus parses without rewriting `.`→`::`; the
+  formatter migrates to the `::` canonical form opportunistically.
+- No estate consumer porting was needed for the grammar gap (rejected
+  alternative: rewriting hundreds of files entrenches a workaround
+  against the Frontier playbook).
+- This decision is settled; do not reopen without amending this ADR.
+  CORE-03 in docs/TECH-DEBT.adoc.
+"""
+references = [
+  "https://github.com/hyperpolymath/affinescript/issues/228",
+  "https://github.com/hyperpolymath/affinescript/issues/229",
+  "lib/parser.mly (qualified_type_name; type_expr_primary; effect_term)",
+  "docs/specs/SETTLED-DECISIONS.adoc (ADR-014 section)",
+  "META.a2ml [[adr]] ADR-011 (real modules / qualified paths)",
+  "META.a2ml [[adr]] ADR-012 (grammar changes are correctness assertions)",
+]
diff --git a/docs/specs/SETTLED-DECISIONS.adoc b/docs/specs/SETTLED-DECISIONS.adoc
@@ -243,3 +243,30 @@ agreed async ABI for the typed-wasm convergence layer; Ephapax is a
 co-stakeholder (typed-wasm ADR-004). Delivered as 4 incremental,
 gated PRs. Full design in `docs/specs/async-on-wasm-cps.adoc`; full ADR
 in `.machine_readable/6a2/META.a2ml` (ADR-013).
+
+== Module-Qualified Type/Effect Path Separator (ADR-014)
+
+The type/effect grammar had no module-qualified path production, so a
+qualified reference like `Externs.Res` was *unrepresentable* in any type
+or effect position (`parse error` at the `.`). An estate audit
+(compiler-as-oracle) found this the single dominant fault: 525 of ~1177
+`.affine` files fail to parse, qualified-path the leading cause. ADR-011
+already settled real modules with qualified paths; this consequence was
+simply unspeakable. The separator was the escalated, owner-decided
+question (`module_path` uses `.`; `use`/value paths use `::`; the corpus
+uses `.` for types).
+
+Decision: accept *both* `.` and `::` (mixed permitted); *`Pkg::Type` is
+canonical* (consistent with ADR-011 value paths); `.` is tolerated and
+normalised to `::`. The parser folds a qualified name into one canonical
+`::`-joined ident, so resolve/typecheck/codegen need no change and the
+formatter prints the canonical form for free. Conflict-neutral by
+construction (it only adds `.`/`::` lookahead where no reduce action
+existed — exactly the parse-error void): measured Menhir conflict states
+unchanged at 21 S/R + 1 R/R, item counts unchanged at 68 S/R / 7 R/R.
+The grammar PR unblocks *parsing*; most estate parse failures clear with
+zero consumer churn (genuine ReScript-surface residue is #229).
+
+This decision is settled; do not reopen without amending the ADR. Full
+ADR in `.machine_readable/6a2/META.a2ml` (ADR-014); ledger CORE-03 in
+`docs/TECH-DEBT.adoc`.
diff --git a/lib/parser.mly b/lib/parser.mly
@@ -137,6 +137,29 @@ module_path:
   | id = ident { [id] }
   | path = module_path DOT id = ident { path @ [id] }
 
+/* ADR-014 (#228): module-qualified type/effect path. Separator is `.` or
+   `::` (mixed permitted); `::` is canonical (consistent with ADR-011 value
+   paths). A qualified name is >=2 `upper_ident` segments; it is folded to a
+   single canonical `::`-joined string so downstream (resolve/typecheck/all
+   codegens, formatter) sees one ident and needs no change — the formatter
+   prints the stored `::` form, normalising any `.` input for free.
+   Right-recursive + restricted to `upper_ident` so it only adds
+   `DOT`/`COLONCOLON` lookahead after a type/effect-position `upper_ident`
+   (no prior reduce action there — that void is the `parse error at .`
+   #228 reports), introducing zero new LR conflicts. */
+%inline qsep:
+  | DOT        { () }
+  | COLONCOLON { () }
+
+qualified_type_name:
+  | head = upper_ident qsep rest = qualified_type_name_rest
+    { head ^ "::" ^ rest }
+
+qualified_type_name_rest:
+  | name = upper_ident { name }
+  | name = upper_ident qsep rest = qualified_type_name_rest
+    { name ^ "::" ^ rest }
+
 /* ========== Imports ========== */
 
 import_decl:
@@ -450,6 +473,20 @@ type_expr_primary:
   | MUT ty = type_expr_primary { TyMut ty }
   | name = lower_ident { TyVar (mk_ident name $startpos $endpos) }
   | name = upper_ident { TyCon (mk_ident name $startpos $endpos) }
+  /* ADR-014 (#228): module-qualified type name. `Pkg.Type` and
+     `Pkg::Type` (and deeper, `A.B.C` / `A::B::C`, mixed separators) are
+     accepted; the segments are folded into a single canonical name joined
+     by `::`, so `::` is the canonical form on print with no formatter
+     change and `.` is silently normalised. Conflict-safe: this only adds
+     `DOT`/`COLONCOLON` as lookahead after a type-position `upper_ident`,
+     where no reduce action previously existed (that absence is exactly the
+     `parse error at .` #228 reports), so it introduces no new LR conflict.
+     Resolution treats the `::`-joined name as a qualified reference. */
+  | name = qualified_type_name { TyCon (mk_ident name $startpos $endpos) }
+  | name = qualified_type_name LBRACKET args = separated_nonempty_list(COMMA, type_arg) RBRACKET
+    { TyApp (mk_ident name $startpos $endpos, args) }
+  | name = qualified_type_name LT args = separated_nonempty_list(COMMA, type_arg) GT
+    { TyApp (mk_ident name $startpos $endpos, args) }
   | name = upper_ident LBRACKET args = separated_nonempty_list(COMMA, type_arg) RBRACKET
     { TyApp (mk_ident name $startpos(name) $endpos(name), args) }
   /* Angle-bracket alias for type application: `Option<T>` ≡ `Option[T]`,
@@ -569,6 +606,12 @@ effect_term:
   | name = ident { EffVar name }
   | name = ident LBRACKET args = separated_list(COMMA, type_arg) RBRACKET
     { EffCon (name, args) }
+  /* ADR-014 (#228): module-qualified effect, e.g. `-{Externs.Net}->` /
+     `-{Externs::Net}->`. Same canonical `::`-fold as qualified types. */
+  | name = qualified_type_name
+    { EffVar (mk_ident name $startpos $endpos) }
+  | name = qualified_type_name LBRACKET args = separated_list(COMMA, type_arg) RBRACKET
+    { EffCon (mk_ident name $startpos $endpos, args) }
 
 /* ========== Traits ========== */
 

diff --git a/test/test_e2e.ml b/test/test_e2e.ml
@@ -3262,6 +3262,63 @@ let array_type_tests = [
   Alcotest.test_case "[T] in struct field parses + typechecks" `Quick test_array_type_parses_in_struct_field;
 ]
 
+(* ---- ADR-014 / #228: module-qualified type & effect paths ----
+   The #228 fault is a *parse error at the `.`* — these assert the
+   construct now PARSES (resolution of the qualified name against a real
+   module is a separate concern, deliberately not asserted here). Both the
+   `.` and the canonical `::` separators, in every position the estate
+   corpus uses, plus the #228 evidence-table cases. *)
+
+let parses_ok src : bool =
+  match (try Some (Parse_driver.parse_string ~file:"<test>" src)
+         with _ -> None) with
+  | Some prog -> List.length prog.prog_decls > 0
+  | None -> false
+
+let test_qual_type_param_dot () =
+  Alcotest.(check bool) "fn(x: Bar.Baz) parses" true
+    (parses_ok {|fn f(x: Bar.Baz) -> Int { return 0; }|})
+
+let test_qual_type_param_coloncolon () =
+  Alcotest.(check bool) "fn(x: Bar::Baz) parses" true
+    (parses_ok {|fn f(x: Bar::Baz) -> Int { return 0; }|})
+
+let test_qual_type_struct_field () =
+  Alcotest.(check bool) "struct { a: Bar.Baz } parses" true
+    (parses_ok {|struct R { a: Bar.Baz } fn m() -> Int { return 0; }|})
+
+let test_qual_type_app () =
+  Alcotest.(check bool) "Pkg::Opt[Int] / Pkg.Opt<Int> parse" true
+    (parses_ok {|fn f(x: Pkg::Opt[Int]) -> Int { return 0; }|}
+     && parses_ok {|fn g(x: Pkg.Opt<Int>) -> Int { return 0; }|})
+
+let test_qual_type_deep_mixed () =
+  Alcotest.(check bool) "A.B.C and A::B::C deep paths parse" true
+    (parses_ok {|fn f(x: A.B.C) -> Int { return 0; }|}
+     && parses_ok {|fn g(x: A::B::C) -> Int { return 0; }|})
+
+let test_qual_effect_dot_and_colons () =
+  Alcotest.(check bool) "-{Bar.Baz}-> and -{Bar::Baz}-> parse" true
+    (parses_ok {|fn f() -{Bar.Baz}-> Int { return 0; }|}
+     && parses_ok {|fn g() -{Bar::Baz}-> Int { return 0; }|})
+
+let test_qual_unqualified_still_parses () =
+  (* Guard: the bare (unqualified) forms must be unaffected. *)
+  Alcotest.(check bool) "bare Type / Type[T] / -{Eff}-> still parse" true
+    (parses_ok {|fn f(x: Baz) -> Int { return 0; }|}
+     && parses_ok {|fn g(x: Opt[Int]) -> Int { return 0; }|}
+     && parses_ok {|fn h() -{Net}-> Int { return 0; }|})
+
+let qualified_path_tests = [
+  Alcotest.test_case "qualified type in param (.)"        `Quick test_qual_type_param_dot;
+  Alcotest.test_case "qualified type in param (::)"       `Quick test_qual_type_param_coloncolon;
+  Alcotest.test_case "qualified type in struct field"     `Quick test_qual_type_struct_field;
+  Alcotest.test_case "qualified type application [ ]/< >"  `Quick test_qual_type_app;
+  Alcotest.test_case "deep + mixed-separator paths"       `Quick test_qual_type_deep_mixed;
+  Alcotest.test_case "qualified effect (. and ::)"        `Quick test_qual_effect_dot_and_colons;
+  Alcotest.test_case "bare unqualified forms unaffected"  `Quick test_qual_unqualified_still_parses;
+]
+
 (* ---- Type-syntax sugars: fn(...) -> T, Option<T>, (A, B) -> C ---- *)
 
 let parse_check_passes src : bool =
@@ -3627,6 +3684,7 @@ let tests =
     ("E2E Externs",              extern_tests);
     ("E2E Vscode Bindings",      vscode_bindings_tests);
     ("E2E Array Type Sugar",     array_type_tests);
+    ("E2E Qualified Paths #228",  qualified_path_tests);
     ("E2E WasmGC PatCon Destructure", wasm_gc_patcon_tests);
     ("E2E Type Syntax Sugar",         type_syntax_sugar_tests);
   ]