Lower memory use across every stored type

Author: AJenbo

docs/CHANGELOG.md

@@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **Lower memory use across every stored type.** The internal representation of a PHP type is now 24 bytes instead of 64, so every parameter, return, and property type (and every type nested inside them) takes less than half the space it used to. On large Laravel projects this cuts peak memory by roughly 15% and the live heap by roughly 19%, with no change to what PHPantom resolves.
 - **Lower memory use when resolving class hierarchies.** Resolving a class no longer copies every inherited or synthesized member into it. Members that a merge does not actually rewrite are shared with their source across the whole workspace, and the copies a merge does produce (template substitution, trait and interface merging, Eloquent Builder and scope forwarding) are deduplicated so that value-identical results share a single allocation instead of one per class. Method parameter lists are shared the same way. On large Laravel projects, where nearly every Eloquent model resolves through a generic base and forwards the same query-builder methods, this roughly halves the memory held by the resolved-class cache during whole-project analysis and speeds up the merge itself.
 - **Property and constant sharing extends the same memory win.** Inherited and synthesized properties and constants are now shared and interned the same way methods already were, instead of being cloned onto every class that inherits them. This further reduces the resolved-class cache's memory footprint on large projects, on top of the method sharing above.
 - **Classes are pre-resolved for the whole workspace after startup.** Once the background index completes, every known class is resolved in dependency order even when workspace diagnostics are disabled, so the first completion, hover, or go-to-definition against any class reads a warm cache instead of resolving on demand. Edits still re-resolve only the affected classes.

docs/todo.md

@@ -27,11 +27,10 @@ within the same impact tier.
 | --- | --------------------------------------------------------------------------------------------------------------------- | ---------- | ------ |
 | P36 | [Diagnostic-path call sites re-merge inheritance per call](todo/performance.md#p36-diagnostic-path-call-sites-re-merge-inheritance-per-call-instead-of-reading-the-resolved-class-cache)          | Medium      | Low         |
 | P31 | [Reference index stores per-span entries when consumers only read distinct URIs](todo/performance.md#p31-reference-index-stores-per-span-entries-when-consumers-only-read-distinct-uris)          | Medium      | Low-Medium  |
-| P37 | [`PhpType` is 64 bytes and is embedded ~3 M times](todo/performance.md#p37-phptype-is-64-bytes-and-is-embedded-3-m-times)                                            | High        | Medium      |
-| P38 | [Resolved type values are duplicated ~33x](todo/performance.md#p38-resolved-type-values-are-duplicated-33x)                                                          | High        | High        |
+| P38 | [Resolved type values are duplicated ~34x](todo/performance.md#p38-resolved-type-values-are-duplicated-34x)                                                          | High        | High        |
 | P39 | [`SymbolKind` stores owned strings per span](todo/performance.md#p39-symbolkind-stores-owned-strings-per-span)                                                       | Medium      | Low-Medium  |
 | P40 | [`method_index` is a per-class `HashMap` even when the member vec is shared](todo/performance.md#p40-method_index-is-a-per-class-hashmap-even-when-the-member-vec-is-shared) | Low-Medium  | Low         |
-| P41 | [3.8 M live allocations cost ~130 MB in allocator overhead](todo/performance.md#p41-38-m-live-allocations-cost-130-mb-in-allocator-overhead)                          | Medium      | Medium      |
+| P41 | [3.8 M live allocations cost ~170 MB in allocator overhead](todo/performance.md#p41-38-m-live-allocations-cost-170-mb-in-allocator-overhead)                          | Medium      | Medium      |
 | P33 | [Workspace diagnostics leaves the whole project fully resolved in memory](todo/performance.md#p33-workspace-diagnostics-leaves-the-whole-project-fully-resolved-in-memory) | High        | Medium-High |
 | X10 | [Interactive requests block on the workspace index lock during initial indexing](todo/indexing.md#x10-interactive-requests-block-on-the-workspace-index-lock-during-initial-indexing) | Medium      | Medium      |
 | L21 | [Tighten the supertype-where-subtype comparison escape hatch (blocked on resolver precision)](todo/laravel.md#l21-tighten-the-supertype-where-subtype-comparison-escape-hatch-blocked-on-resolver-precision) | Medium      | High        |

docs/todo/performance.md

@@ -1095,7 +1095,7 @@ bounded by the same fix as P33.
 
 ---
 
-## Memory baseline (2026-07-26)
+## Memory baseline (2026-07-26, refreshed after the `PhpType` shrink)
 
 Measured with the `mem-audit` cargo feature, which installs a counting
 global allocator and prints a deep-size walk of every long-lived store
@@ -1125,15 +1125,18 @@ mimalloc, since that is what every shipped Linux binary runs (see
 
 | Measure                       | Mid-size Laravel app | Large Laravel app |
 | ----------------------------- | -------------------- | ----------------- |
-| Peak RSS (`VmHWM`)            | 578 MB               | 834 MB            |
-| RSS after mimalloc collect    | 552 MB               | 814 MB            |
-| Live heap (allocator-reported)| 415 MB               | 634 MB            |
-| Live allocations              | 2.46 M               | 3.83 M            |
-| Allocator + page overhead     | 136 MB (25% of RSS)  | 179 MB (22%)      |
-
-For reference, the same run under plain glibc `malloc` (no mimalloc)
-peaks higher despite a *lower* overhead percentage: 622 MB / 855 MB
-peak, 100 MB (19%) / 133 MB (17%) overhead. mimalloc holds more
+| Peak RSS (`VmHWM`)            | 505 MB               | 706 MB            |
+| RSS after mimalloc collect    | 477 MB               | 686 MB            |
+| Live heap (allocator-reported)| 344 MB               | 514 MB            |
+| Live allocations              | 2.45 M               | 3.81 M            |
+| Allocator + page overhead     | 133 MB (28% of RSS)  | 172 MB (25%)      |
+
+The glibc figures below were taken against the original baseline (the
+one with a 64-byte `PhpType`) and have not been re-measured since; the
+relative picture they illustrate is unchanged. Under plain glibc
+`malloc` (no mimalloc) the same run peaked higher despite a *lower*
+overhead percentage: 622 MB / 855 MB peak, 100 MB (19%) / 133 MB (17%)
+overhead. mimalloc holds more
 allocator/page overhead in percentage terms but a smaller absolute
 peak, because PHPantom already tunes it (`configure_allocator`: a
 short purge delay plus a per-process THP opt-out) to return freed
@@ -1143,18 +1146,18 @@ Bytes released per store (drop-and-measure, mid-size / large):
 
 | Store                  | Released         | Allocations     |
 | ---------------------- | ---------------- | --------------- |
-| `resolved_class_cache` | 205 MB / 336 MB  | 1.17 M / 1.96 M |
+| `resolved_class_cache` | 143 MB / 237 MB  | 1.17 M / 1.94 M |
 | `symbol_maps`          | 40 MB / 64 MB    | 367 K / 602 K   |
 | `reference_index`      | 26 MB / 43 MB    | 204 K / 330 K   |
-| `uri_classes_index`    | 25 MB / 36 MB    | 122 K / 172 K   |
+| `uri_classes_index`    | 25 MB / 27 MB    | 122 K / 171 K   |
 | `resolved_names`       | 4.6 MB / 6.7 MB  | 53 K / 75 K     |
 | everything else        | < 6 MB each      | —               |
 
 Within the member data, the largest field-level groups on the large app
-are `MethodInfo` structs (122 MB across 223 K distinct methods at 560 B
-each), parameter vectors (86 MB across 187 K vectors holding 312 K
-parameters at 256 B each), `PhpType` heap payloads (~66 MB), and
-`method_index` (20 MB).
+are `MethodInfo` structs (92 MB across 232 K distinct methods at 400 B
+each), parameter vectors (51 MB across 191 K vectors holding 325 K
+parameters at 136 B each), `PhpType` heap payloads (~33 MB), and
+`method_index` (21 MB).
 
 Two findings from the baseline are worth recording because they close
 off obvious-looking ideas:
@@ -1172,72 +1175,30 @@ off obvious-looking ideas:
 
 ---
 
-## P37. `PhpType` is 64 bytes and is embedded ~3 M times
-
-**Impact: High · Effort: Medium**
-
-`PhpType` is 64 bytes because its largest variants force that size:
-`Conditional` carries a `String` plus three `Box`es, `Callable` carries
-a `String` plus a `Vec` plus an `Option<Box>`, and `Generic` carries a
-`String` plus a `Vec`. Every `PhpType` slot in the program pays for
-them.
-
-Measured on the large Laravel app: **2.94 M slots** (1.90 M sitting
-inline in struct fields, 1.05 M inside heap allocations). The variants
-that force the 64-byte size are rare — the mix is `Named` 70.6%,
-`Generic` 12.8%, `Union` 10.2%, `Callable` 2.9%, `Nullable` 1.2%,
-`Conditional` 1.1%, everything else under 0.5%.
-
-The cost lands squarely on the hottest structs. `MethodInfo` is 560 B,
-of which four `Option<PhpType>` fields (`return_type`,
-`native_return_type`, `conditional_return`, `if_this_is`) account for
-256 B. `ParameterInfo` is 256 B, of which three `Option<PhpType>`
-fields account for 192 B.
-
-### Fix
-
-Box the rare variants so the enum's payload fits a pointer, e.g.
-`Conditional(Box<ConditionalType>)`, `Callable(Box<CallableType>)`,
-`Generic(Box<GenericType>)`, `Union(Box<Vec<PhpType>>)`,
-`IntRange(Box<(String, String)>)`. `Named(Atom)` stays inline, which is
-the 70% case, so the common path gains an indirection nowhere.
-
-Reclaim at 16 B per slot: **83 MB** on the mid-size app, **135 MB** on
-the large one. `MethodInfo` drops to ~368 B and `ParameterInfo` to
-~112 B. A less aggressive version that only boxes `Conditional` and
-`Callable` (leaving 24 B, since `Box<[T]>` and `Box<str>` are fat
-pointers) still reclaims roughly two thirds of that.
-
-Note `Generic`'s first field is a `String` holding a class name or
-keyword — a bounded set that should be an `Atom` regardless.
-
----
-
-## P38. Resolved type values are duplicated ~33x
+## P38. Resolved type values are duplicated ~34x
 
 **Impact: High · Effort: High**
 
-The same measurement pass that produced P37 rendered every live
-`PhpType` and counted distinct forms: **1.68 M values collapse to
-50,590 distinct rendered types** on the large Laravel app, and 1.02 M to
-30,903 on the mid-size one. Both are almost exactly **33x duplication**.
-Every `string`, `?Carbon`, `Collection<User>`, and
-`Builder<TModel>` is re-allocated per method, per parameter, per class
-that inherits it.
+The memory audit renders every live `PhpType` and counts distinct
+forms: **1.76 M values collapse to 51,272 distinct rendered types** on
+the large Laravel app, and 1.07 M to 31,074 on the mid-size one. Both
+are almost exactly **34x duplication**. Every `string`, `?Carbon`,
+`Collection<User>`, and `Builder<TModel>` is re-allocated per method,
+per parameter, per class that inherits it.
 
 Interning types the way `Atom` interns names would collapse both halves
-of the cost at once: each slot becomes a pointer-or-index handle, and
-each distinct type is allocated once. Combined with the slot shrink from
-P37 the ceiling is roughly 230 MB on the large app and 140 MB on the
-mid-size one — the single largest structural win available.
-
-This is deliberately filed separately from P37 because it is a much
-larger change: `PhpType` is currently a value that substitution paths
-mutate in place, so interning means moving to a construct-and-intern
-API (`PhpType::named(...)`, `PhpType::union(...)`) and auditing every
-site that builds or rewrites a type. Do P37 first — it is
-self-contained, it delivers most of the per-slot win, and it does not
-foreclose interning later.
+of the remaining cost at once: each slot becomes a pointer-or-index
+handle (24 B down to 8 B, worth another ~24 MB of slot bytes on the
+large app on its own), and each distinct type is allocated once instead
+of ~34 times. The audit's "PhpType 24→16 B" projection covers only the
+slot half; the duplicate payloads are the larger share.
+
+This is a much larger change than the slot shrink that preceded it:
+`PhpType` is a value that substitution paths mutate in place, so
+interning means moving fully to a construct-and-intern API (the
+`PhpType::union(...)` / `PhpType::generic(...)` constructors added by
+the slot shrink are the beginning of that surface) and auditing every
+site that builds or rewrites a type.
 
 Take care not to feed the interner unbounded text: `Raw` holds
 free-text parse fallbacks and `Literal` holds source literals, so those
@@ -1304,17 +1265,17 @@ Two options, either of which is small:
 
 ---
 
-## P41. 3.8 M live allocations cost ~180 MB in allocator overhead
+## P41. 3.8 M live allocations cost ~170 MB in allocator overhead
 
 **Impact: Medium · Effort: Medium**
 
 Independent of what we store, *how many* allocations we hold costs
 real memory. On the large Laravel app, mimalloc (the allocator every
 shipped Linux binary runs — see the "Memory baseline" note above)
-reports 634 MB live across 3.83 M allocations (average 174 B), while
-peak RSS is 834 MB. The 179 MB difference (22% of RSS; 25% on the
+reports 514 MB live across 3.81 M allocations (average 142 B), while
+peak RSS is 706 MB. The 172 MB difference (25% of RSS; 28% on the
 mid-size app) is mimalloc's per-size-class page and slot rounding —
-roughly 47 B per live allocation.
+roughly 45 B per live allocation.
 
 This is *after* the existing `configure_allocator` tuning (a short
 purge delay plus a per-process transparent-huge-pages opt-out — see
@@ -1328,11 +1289,10 @@ absolute peak RSS. `MALLOC_ARENA_MAX` capping under plain glibc moves
 peak RSS (622 MB to 516 MB on the mid-size app) but barely moves the
 trimmed live figure, confirming arena count was never the lever.
 
-What is left is allocation *count* itself: at ~47 B of overhead per
+What is left is allocation *count* itself: at ~45 B of overhead per
 live allocation, each allocation avoided is worth more than its own
-`size_of`. P37, P39, and P40 each remove hundreds of thousands of
-allocations as a side effect (folding `Option<PhpType>` heap payloads
-into fewer, larger buffers; interning `SymbolKind` strings; sharing
+`size_of`. P39 and P40 each remove hundreds of thousands of allocations
+as a side effect (interning `SymbolKind` strings; sharing
 `method_index`), so re-measure this line after those land. If a
 meaningful gap remains afterward, the next lever is arena-allocating
 the member metadata (bump-allocate `MethodInfo`/`PropertyInfo`/

src/class_lookup.rs

@@ -337,11 +337,11 @@ pub(crate) fn is_subtype_of_typed(
 
     // ── Nullable normalisation ──────────────────────────────────
     if let PhpType::Nullable(inner) = subtype {
-        let as_union = PhpType::Union(vec![inner.as_ref().clone(), PhpType::null()]);
+        let as_union = PhpType::union(vec![inner.as_ref().clone(), PhpType::null()]);
         return is_subtype_of_typed(&as_union, supertype, class_loader);
     }
     if let PhpType::Nullable(inner) = supertype {
-        let as_union = PhpType::Union(vec![inner.as_ref().clone(), PhpType::null()]);
+        let as_union = PhpType::union(vec![inner.as_ref().clone(), PhpType::null()]);
         return is_subtype_of_typed(subtype, &as_union, class_loader);
     }
 
@@ -371,9 +371,9 @@ pub(crate) fn is_subtype_of_typed(
     // namespace-qualified name and the other uses a short name
     // (e.g. `list<Pen>` vs `list<Demo\Pen>`).  Re-check with the
     // class loader so nominal hierarchy applies to inner params.
-    if let (PhpType::Generic(name_sub, args_sub), PhpType::Generic(name_sup, args_sup)) =
-        (subtype, supertype)
-    {
+    if let (PhpType::Generic(sub), PhpType::Generic(sup)) = (subtype, supertype) {
+        let (name_sub, args_sub) = (&sub.name, &sub.args);
+        let (name_sup, args_sup) = (&sup.name, &sup.args);
         let base_sub = name_sub.to_ascii_lowercase();
         let base_sup = name_sup.to_ascii_lowercase();
         let bases_compatible = base_sub == base_sup
@@ -448,12 +448,12 @@ pub(crate) fn is_subtype_of_typed(
     // permissive (return true) to avoid false positives.
     if let PhpType::Literal(lit) = subtype
         && lit.string_content().is_some()
-        && let PhpType::Generic(name, args) = supertype
-        && name.eq_ignore_ascii_case("model-property")
-        && args.len() == 1
+        && let PhpType::Generic(g) = supertype
+        && g.name.eq_ignore_ascii_case("model-property")
+        && g.args.len() == 1
     {
         let prop_name = lit.string_content().unwrap();
-        if let Some(model_name) = args[0].base_name()
+        if let Some(model_name) = g.args[0].base_name()
             && let Some(cls) = class_loader(model_name)
         {
             let resolved = crate::inheritance::resolve_class_with_inheritance(&cls, class_loader);
@@ -473,7 +473,7 @@ pub(crate) fn is_subtype_of_typed(
     // content cannot be resolved to a class — it may simply live in
     // a file we haven't indexed — and only reject when the resolved
     // class provably fails to satisfy the bound.
-    if let PhpType::Literal(crate::php_type::LiteralValue::String(_)) = subtype
+    if let Some(crate::php_type::LiteralValue::String(_)) = subtype.as_literal()
         && matches!(
             supertype,
             PhpType::ClassString(_) | PhpType::InterfaceString(_)

src/code_actions/phpstan/add_iterable_type.rs

@@ -80,7 +80,7 @@ fn extract_iterable_return_type(message: &str) -> Option<PhpType> {
 /// Uses PHPStan's generic syntax: `array<string>`, `iterable<User>`,
 /// `Traversable<mixed>`, `array<int, string>`, etc.
 fn build_return_type(iterable_type: &str, args: Vec<PhpType>) -> PhpType {
-    PhpType::Generic(iterable_type.to_owned(), args)
+    PhpType::generic(iterable_type, args)
 }
 
 // ── Docblock helpers ────────────────────────────────────────────────────────
@@ -548,9 +548,9 @@ impl Backend {
 
         // Try to extract the generic parameter(s) from the inferred type.
         // e.g. `list<string>` → [string], `array<int, User>` → [int, User]
-        if let PhpType::Generic(_, args) = &parsed {
-            if !args.is_empty() && args.iter().all(|a| !a.is_mixed()) {
-                return Some(args.clone());
+        if let PhpType::Generic(g) = &parsed {
+            if !g.args.is_empty() && g.args.iter().all(|a| !a.is_mixed()) {
+                return Some(g.args.clone());
             }
             return None;
         }

src/code_actions/phpstan/fix_return_type/inference.rs

@@ -237,7 +237,7 @@ pub(crate) fn infer_return_type(
     let effective = if deduped.len() == 1 {
         deduped.into_iter().next().unwrap()
     } else if deduped.len() <= 3 {
-        PhpType::Union(deduped)
+        PhpType::union(deduped)
     } else {
         return None;
     };

src/code_actions/phpstan/remove_unused_return_type.rs

@@ -135,9 +135,9 @@ fn format_type_list(types: &[&PhpType], sep: &str) -> PhpType {
         return cloned.into_iter().next().unwrap();
     }
     if sep == "&" {
-        PhpType::Intersection(cloned)
+        PhpType::intersection(cloned)
     } else {
-        PhpType::Union(cloned)
+        PhpType::union(cloned)
     }
 }