cknitt · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026
diff --git a/changes/untagged-variants-spec.internal.md b/changes/untagged-variants-spec.internal.md
@@ -0,0 +1 @@
+- Document the rules of untagged variants in `compiler/ml/UntaggedVariants.md`, with tests pinning them.
diff --git a/compiler/ml/README.md b/compiler/ml/README.md
@@ -31,6 +31,10 @@ For module inclusion and signature compatibility, start with
 [`includecore.mli`](includecore.mli), [`includemod.mli`](includemod.mli), and
 [`mtype.mli`](mtype.mli).
 
+[`UntaggedVariants.md`](UntaggedVariants.md) states the rules of untagged
+(`@unboxed`) variants: payload kinds, run-time recognition, well-formedness,
+and the interaction with `option`.
+
 ## Main data and operations
 
 [`types.mli`](types.mli)

diff --git a/compiler/ml/UntaggedVariants.md b/compiler/ml/UntaggedVariants.md
diff --git a/tests/build_tests/super_errors/expected/TaggedDuplicateLiteral.res.expected b/tests/build_tests/super_errors/expected/TaggedDuplicateLiteral.res.expected
@@ -0,0 +1,8 @@
+
+  [1;31mWe've found a bug for you![0m
+  [36m/.../fixtures/TaggedDuplicateLiteral.res[0m:[2m1:23-34[0m
+
+  [1;31m1[0m [2m│[0m type t = | @as("x") A [1;31m| @as("x") B[0m
+  2 [2m│[0m 
+
+  This untagged variant definition is invalid: Duplicate literal x.
diff --git a/tests/build_tests/super_errors/expected/UntaggedAtMostOneString.res.expected b/tests/build_tests/super_errors/expected/UntaggedAtMostOneString.res.expected
@@ -0,0 +1,9 @@
+
+  [1;31mWe've found a bug for you![0m
+  [36m/.../fixtures/UntaggedAtMostOneString.res[0m:[2m2:20-30[0m
+
+  1 [2m│[0m @unboxed
+  [1;31m2[0m [2m│[0m type t = A(string) [1;31m| B(string)[0m
+  3 [2m│[0m 
+
+  This untagged variant definition is invalid: At most one case can be a string type.
diff --git a/tests/build_tests/super_errors/fixtures/TaggedDuplicateLiteral.res b/tests/build_tests/super_errors/fixtures/TaggedDuplicateLiteral.res
@@ -0,0 +1 @@
+type t = | @as("x") A | @as("x") B
diff --git a/tests/build_tests/super_errors/fixtures/UntaggedAtMostOneString.res b/tests/build_tests/super_errors/fixtures/UntaggedAtMostOneString.res
@@ -0,0 +1,2 @@
+@unboxed
+type t = A(string) | B(string)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		- Document the rules of untagged variants in `compiler/ml/UntaggedVariants.md`, with tests pinning them.