illegalstudio · mirchaemanuel · Jul 7, 2026 · Jul 7, 2026 · Jul 8, 2026 · Jul 8, 2026
diff --git a/docs/internals/builtins/array/count.md b/docs/internals/builtins/array/count.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/array/count.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/array/count.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:439](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L439) (`lower_count`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:442](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L442) (`lower_count`)
 - **Function symbol**: `lower_count()`
 
 

diff --git a/docs/internals/builtins/class/class_exists.md b/docs/internals/builtins/class/class_exists.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/callables/class_exists.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/callables/class_exists.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:293](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L293) (`lower_class_like_exists`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:296](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L296) (`lower_class_like_exists`)
 - **Function symbol**: `lower_class_like_exists()`
 
 

diff --git a/docs/internals/builtins/class/enum_exists.md b/docs/internals/builtins/class/enum_exists.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/callables/enum_exists.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/callables/enum_exists.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:293](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L293) (`lower_class_like_exists`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:296](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L296) (`lower_class_like_exists`)
 - **Function symbol**: `lower_class_like_exists()`
 
 

diff --git a/docs/internals/builtins/class/function_exists.md b/docs/internals/builtins/class/function_exists.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/callables/function_exists.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/callables/function_exists.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:276](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L276) (`lower_function_exists`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:279](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L279) (`lower_function_exists`)
 - **Function symbol**: `lower_function_exists()`
 
 

diff --git a/docs/internals/builtins/class/interface_exists.md b/docs/internals/builtins/class/interface_exists.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/callables/interface_exists.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/callables/interface_exists.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:293](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L293) (`lower_class_like_exists`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:296](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L296) (`lower_class_like_exists`)
 - **Function symbol**: `lower_class_like_exists()`
 
 

diff --git a/docs/internals/builtins/class/trait_exists.md b/docs/internals/builtins/class/trait_exists.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/callables/trait_exists.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/callables/trait_exists.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:293](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L293) (`lower_class_like_exists`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:296](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L296) (`lower_class_like_exists`)
 - **Function symbol**: `lower_class_like_exists()`
 
 

diff --git a/docs/internals/builtins/misc/defined.md b/docs/internals/builtins/misc/defined.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/system/defined.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/system/defined.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:261](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L261) (`lower_defined`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:264](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L264) (`lower_defined`)
 - **Function symbol**: `lower_defined()`
 
 

diff --git a/docs/internals/builtins/misc/empty.md b/docs/internals/builtins/misc/empty.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/types/signatures.rs`](https://github.com/illegalstudio/elephc/blob/main/src/types/signatures.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:618](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L618) (`lower_empty`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:621](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L621) (`lower_empty`)
 - **Function symbol**: `lower_empty()`
 
 

diff --git a/docs/internals/builtins/misc/phpversion.md b/docs/internals/builtins/misc/phpversion.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/system/phpversion.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/system/phpversion.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:251](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L251) (`lower_phpversion`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:254](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L254) (`lower_phpversion`)
 - **Function symbol**: `lower_phpversion()`
 
 

diff --git a/docs/internals/builtins/string/strlen.md b/docs/internals/builtins/string/strlen.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/string/strlen.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/string/strlen.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:493](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L493) (`lower_strlen`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:496](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L496) (`lower_strlen`)
 - **Function symbol**: `lower_strlen()`
 
 

diff --git a/docs/internals/builtins/type/boolval.md b/docs/internals/builtins/type/boolval.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/boolval.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/boolval.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:586](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L586) (`lower_boolval`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:589](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L589) (`lower_boolval`)
 - **Function symbol**: `lower_boolval()`
 
 

diff --git a/docs/internals/builtins/type/floatval.md b/docs/internals/builtins/type/floatval.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/floatval.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/floatval.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:556](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L556) (`lower_floatval`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:559](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L559) (`lower_floatval`)
 - **Function symbol**: `lower_floatval()`
 
 

diff --git a/docs/internals/builtins/type/intval.md b/docs/internals/builtins/type/intval.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/intval.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/intval.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:523](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L523) (`lower_intval`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:526](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L526) (`lower_intval`)
 - **Function symbol**: `lower_intval()`
 
 

diff --git a/docs/internals/builtins/type/is_array.md b/docs/internals/builtins/type/is_array.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_array.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_array.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:1002](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L1002) (`lower_is_array`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:1005](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L1005) (`lower_is_array`)
 - **Function symbol**: `lower_is_array()`
 
 

diff --git a/docs/internals/builtins/type/is_bool.md b/docs/internals/builtins/type/is_bool.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_bool.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_bool.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:736](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L736) (`lower_static_type_predicate`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:739](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L739) (`lower_static_type_predicate`)
 - **Function symbol**: `lower_static_type_predicate()`
 
 

diff --git a/docs/internals/builtins/type/is_callable.md b/docs/internals/builtins/type/is_callable.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_callable.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_callable.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:319](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L319) (`lower_is_callable`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:322](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L322) (`lower_is_callable`)
 - **Function symbol**: `lower_is_callable()`
 
 

diff --git a/docs/internals/builtins/type/is_float.md b/docs/internals/builtins/type/is_float.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_float.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_float.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:736](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L736) (`lower_static_type_predicate`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:739](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L739) (`lower_static_type_predicate`)
 - **Function symbol**: `lower_static_type_predicate()`
 
 

diff --git a/docs/internals/builtins/type/is_int.md b/docs/internals/builtins/type/is_int.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_int.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_int.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:736](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L736) (`lower_static_type_predicate`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:739](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L739) (`lower_static_type_predicate`)
 - **Function symbol**: `lower_static_type_predicate()`
 
 

diff --git a/docs/internals/builtins/type/is_iterable.md b/docs/internals/builtins/type/is_iterable.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_iterable.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_iterable.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:794](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L794) (`lower_is_iterable`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:797](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L797) (`lower_is_iterable`)
 - **Function symbol**: `lower_is_iterable()`
 
 

diff --git a/docs/internals/builtins/type/is_null.md b/docs/internals/builtins/type/is_null.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_null.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_null.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:992](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L992) (`lower_is_null_builtin`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:995](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L995) (`lower_is_null_builtin`)
 - **Function symbol**: `lower_is_null_builtin()`
 
 

diff --git a/docs/internals/builtins/type/is_object.md b/docs/internals/builtins/type/is_object.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_object.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_object.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:1017](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L1017) (`lower_is_object`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:1020](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L1020) (`lower_is_object`)
 - **Function symbol**: `lower_is_object()`
 
 

diff --git a/docs/internals/builtins/type/is_scalar.md b/docs/internals/builtins/type/is_scalar.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_scalar.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_scalar.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:1033](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L1033) (`lower_is_scalar`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:1036](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L1036) (`lower_is_scalar`)
 - **Function symbol**: `lower_is_scalar()`
 
 

diff --git a/docs/internals/builtins/type/is_string.md b/docs/internals/builtins/type/is_string.md
@@ -10,7 +10,7 @@ sidebar:
 ## Where it lives
 
 - **Signature**: [`src/builtins/types/is_string.rs`](https://github.com/illegalstudio/elephc/blob/main/src/builtins/types/is_string.rs)
-- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:736](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L736) (`lower_static_type_predicate`)
+- **Lowering**: [`src/codegen/lower_inst/builtins.rs`:739](https://github.com/illegalstudio/elephc/blob/main/src/codegen/lower_inst/builtins.rs#L739) (`lower_static_type_predicate`)
 - **Function symbol**: `lower_static_type_predicate()`
 
 

diff --git a/docs/php/control-structures.md b/docs/php/control-structures.md
@@ -205,6 +205,16 @@ echo $result; // two
 
 If no arm matches and there is no `default`, elephc aborts with a fatal runtime error.
 
+Arms may produce values of different types (objects, arrays, strings, ints, `null`),
+and an arm may be a `throw` expression. When the arm types are heterogeneous, the
+result is stored as a boxed `mixed` value and each value-producing arm keeps its
+own runtime type, matching PHP; a `null` arm keeps the merged result nullable, so
+returning such a match from a function with an inferred return type preserves the
+null. Exception: arms whose types share one runtime representation (two array
+types with different element types, or `int` and `bool`) merge to that
+representation, which can change an arm value's observable type — see
+[Known incompatibilities with PHP](types.md#known-incompatibilities-with-php).
+
 ## try / catch / finally / throw
 
 ```php

diff --git a/docs/php/types.md b/docs/php/types.md
@@ -240,6 +240,7 @@ Narrowing applies to function and method parameters. A parameter whose call site
 - Plain array numeric casts (`(int)$array`, `(float)$array`) follow elephc's existing array cast semantics (return the element count rather than PHP's `0`/`1`). Direct `iterable` numeric casts use PHP's empty/non-empty `0`/`1` semantics.
 - `__destruct` runs when an object's refcount reaches zero (scope exit, reassignment, `unset`, program end), matching PHP's timing, but **object resurrection is not supported**: re-storing `$this` so the object would outlive the destructor does not keep it alive — the object is still freed once `__destruct` returns.
 - Under the compatibility `--null-repr=sentinel` opt-out, the integer `9223372036854775806` (`PHP_INT_MAX - 1`) collides with elephc's internal null marker in unboxed scalar slots and is misread as `null` by `echo`, `var_dump()`, `is_null()`, `??`, and related null checks. The default tagged null representation does not have this collision: the full 64-bit integer range round-trips.
+- `match` (and ternary) arms whose types share one runtime representation merge to it instead of each arm keeping its own type: an `int` arm together with a `bool` arm collapses to one representation (`match($n) { 1 => 42, default => true }` yields `bool(true)` where PHP keeps `int(42)`), and two indexed-array arms with different element types merge to one element type (`match($n) { 1 => [1, 2], default => ["a", "b"] }` reads the int-array arm's elements through the string-array type). Arms of otherwise distinct types — object, array, string, int, float, `null` — each keep their own runtime type, matching PHP.
 - Variable variables (`$$name`, `${$expr}`) are not supported. elephc allocates each local to a fixed compile-time stack slot and keeps no per-frame variable-name table, so a variable whose name is computed at runtime cannot be resolved. Use an array keyed by the dynamic name instead.
 - `serialize()`/`unserialize()` cover scalars, arrays, and objects (including the `__serialize`/`__unserialize`/`__sleep`/`__wakeup` magic methods and `r:`/`R:` object back-references) byte-for-byte compatibly with PHP. Remaining gaps: a cyclic reference inside an object's own properties resolves to `null` on `unserialize()` (serialization handles cycles), the deprecated `Serializable` interface (`C:` wire form) is unsupported, writing a property of an unserialized object held in a `Mixed` does not persist (a separate `Mixed` property-write limitation), and `unserialize()` does not emit PHP's `E_WARNING` / `E_NOTICE` on malformed input — it just returns `false`.