Identical types are stored once

Author: AJenbo

docs/ARCHITECTURE.md

@@ -151,7 +151,8 @@ project for PHP parsing and type representation:
 | `mago-names`       | Use-statement and namespace resolution                 |
 | `mago-type-syntax` | PHPStan/Psalm type expression parsing into `PhpType`   |
 
-`PhpType` (`src/php_type.rs`) is an owned enum that wraps the borrowed
+`PhpType` (`src/php_type/`) is a pointer-sized handle to an interned
+`TypeKind` node, itself built from the borrowed
 `mago_type_syntax::cst::Type` AST. Every type-carrying field in the
 data model (`type_hint`, `return_type`, `native_type_hint`,
 `native_return_type`, `asserted_type`, `template_param_bounds` values,
@@ -160,6 +161,20 @@ The substitution engine in `inheritance.rs` operates on
 `HashMap<String, PhpType>` so that template parameter replacement
 never re-parses type strings.
 
+Types are hash-consed: every constructor routes through the interner in
+`php_type/intern.rs`, so two structurally equal types always share one
+allocation. That is what lets a type occurrence cost 8 bytes rather
+than 24 plus a private copy of its payload on a workload that repeats
+the same few thousand forms everywhere, and it makes `PartialEq` a
+pointer comparison instead of a structural walk. Match on
+`PhpType::kind()` to inspect a node, and build new ones through the
+constructors (`PhpType::named`, `PhpType::nullable`, `PhpType::union`,
+…) rather than by constructing a `TypeKind` directly, so the pointer
+and structural notions of equality never drift apart. The table holds
+weak references, so forms nothing refers to any more are reclaimed:
+`TypeKind::Raw` and `TypeKind::Literal` carry free text, which would
+otherwise grow without bound in a long-running server.
+
 Several other Mago crates were evaluated and ruled out:
 
 | Crate              | Reason                                                                  |

docs/CHANGELOG.md

@@ -36,6 +36,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.
+- **Identical types are stored once.** A project repeats the same handful of types thousands of times over: every `string` parameter, every `?Carbon` property, every `Collection<User>` return. PHPantom now stores each distinct type a single time and refers to it by a pointer, so a type occurrence costs 8 bytes instead of 24 plus its own copy of the payload. On large Laravel projects this cuts peak memory by a further 10% and the live heap by 20%, and drops around a quarter of all live allocations. Comparing two types is now a pointer check rather than a walk over their structure, so analysis is slightly faster as well.
 - **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

@@ -26,8 +26,6 @@ within the same impact tier.
 | #   | Item                                                                                                                  | Impact     | Effort |
 | --- | --------------------------------------------------------------------------------------------------------------------- | ---------- | ------ |
 | 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         |
-| P38 | [Resolved type values are duplicated ~34x](todo/performance.md#p38-resolved-type-values-are-duplicated-34x)                                                          | High        | High        |
-| 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

@@ -404,9 +404,10 @@ so this fast-path would apply to the majority of checks.
    `HashMap<(Atom, Atom), bool>` that caches the result of
    "is type A a subtype of type B?" lookups. Clear the map at the
    start of each completion/hover/diagnostic request. Class names
-   are interned now (`PhpType::Named` carries an `Atom`, `ClassInfo`
+   are interned now (`TypeKind::Named` carries an `Atom`, `ClassInfo`
    caches its FQN as an `Atom`), so the keys are `Copy` and
-   identity-hashed.
+   identity-hashed. Whole types are interned too, so a `(PhpType,
+   PhpType)` key would work as well and hash just as cheaply.
 
 2. Add a `has_template_params: bool` flag (or equivalent) to
    `ClassInfo` or type representations. Set it during parsing when
@@ -1036,16 +1037,16 @@ interface merge inside `resolve_class_fully_inner` are intentional
 a CPU fix (11% of diagnostic-pass CPU), not a memory one, but it is
 memory-neutral-to-positive: today each of the 25,676 calls builds a
 full inheritance-merged `ClassInfo` (its own methods/properties vecs)
-and immediately discards it, which is 25,676 transient allocations of
-exactly the kind P41 cares about. Routing through the cache turns most
-of those into a hit against an entry the diagnostic pass populates
-anyway; it can only add a new persistent cache entry for a class that
-was otherwise *never* resolved in the pass, which is a narrow case
-bounded by the same fix as P33.
+and immediately discards it — 25,676 transient allocations that
+straight-line CPU savings would remove as a side effect. Routing
+through the cache turns most of those into a hit against an entry the
+diagnostic pass populates anyway; it can only add a new persistent
+cache entry for a class that was otherwise *never* resolved in the
+pass, which is a narrow case bounded by the same fix as P33.
 
 ---
 
-## Memory baseline (2026-07-26, refreshed after the `PhpType` shrink)
+## Memory baseline (2026-07-28, refreshed after `PhpType` interning)
 
 Measured with the `mem-audit` cargo feature, which installs a counting
 global allocator and prints a deep-size walk of every long-lived store
@@ -1061,8 +1062,8 @@ The walk dedups shared `Arc`s by pointer, so a member reached from
 several classes is counted once. It reports both a field-level
 attribution and a drop-and-measure probe that clears each store and
 reads the exact allocator delta, which cross-checks the walk. Since
-which allocator is active changes the RSS/overhead figures (see P41),
-the audit labels its own build (`target … / … libc, allocator …`) —
+which allocator is active changes the RSS/overhead figures, the audit
+labels its own build (`target … / … libc, allocator …`) —
 always check that line before comparing a new run to the table below.
 
 The byte/allocation figures (live heap, per-store bytes released,
@@ -1075,39 +1076,50 @@ mimalloc, since that is what every shipped Linux binary runs (see
 
 | Measure                       | Mid-size Laravel app | Large Laravel app |
 | ----------------------------- | -------------------- | ----------------- |
-| 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%)      |
+| Peak RSS (`VmHWM`)            | 402 MB               | 540 MB            |
+| RSS after mimalloc collect    | 370 MB               | 510 MB            |
+| Live heap (allocator-reported)| 245 MB               | 358 MB            |
+| Live allocations              | 1.44 M               | 2.21 M            |
+| Allocator + page overhead     | 125 MB (34% of RSS)  | 152 MB (30%)      |
 
 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
+one with a 64-byte `PhpType`, before it was shrunk and then interned)
+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
-parse-burst memory promptly. See P41 for what's left after that tuning.
+parse-burst memory promptly.
+
+The overhead percentage rose as later changes (P33 sharing, P38
+interning) cut the live-allocation count — evidence that this overhead
+tracks the size of mimalloc's retained free-page pool, not a flat
+per-allocation cost, and that pool is sized by the parse-burst peak
+rather than the steady-state live set. Reducing allocation count on
+its own is therefore not expected to move it further; a real
+reduction would have to target that peak instead.
 
 Bytes released per store (drop-and-measure, mid-size / large):
 
 | Store                  | Released         | Allocations     |
 | ---------------------- | ---------------- | --------------- |
-| `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 / 27 MB    | 122 K / 171 K   |
+| `resolved_class_cache` | 101 MB / 165 MB  | 719 K / 1.18 M  |
+| `symbol_maps`          | 30 MB / 47 MB    | 159 K / 248 K   |
+| `uri_classes_index`    | 16 MB / 23 MB    | 104 K / 149 K   |
+| `reference_index`      | 5.3 MB / 8.1 MB  | 73 K / 112 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 (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).
+are `MethodInfo` structs (78 MB across 232 K distinct methods at 336 B
+each), parameter vectors (36 MB across 191 K vectors holding 325 K
+parameters at 88 B each), member docblock text (13 MB), and
+`method_index` (12 MB). Type payloads no longer register: interning
+collapsed 856 K live type occurrences on that app to 51 K distinct
+nodes, so the whole type representation now costs under 4 MB.
 
 Two findings from the baseline are worth recording because they close
 off obvious-looking ideas:
@@ -1125,116 +1137,6 @@ off obvious-looking ideas:
 
 ---
 
-## P38. Resolved type values are duplicated ~34x
-
-**Impact: High · Effort: High**
-
-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 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
-should keep owned payloads or use a separate bounded cache.
-
----
-
-## 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 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 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
-`src/lib.rs`), which already earns back real RSS: the same run under
-plain glibc `malloc` peaks *higher* (622 MB / 855 MB) despite a lower
-overhead percentage (19% / 17%), because glibc holds freed arena
-pages far more readily than mimalloc does once tuned. So the
-allocator swap this item used to propose is already done — mimalloc is
-the shipped allocator and it is outperforming the alternative on
-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 ~45 B of overhead per
-live allocation, each allocation avoided is worth more than its own
-`size_of`. P39 removed hundreds of thousands of allocations as a side
-effect (interning `SymbolKind` strings).
-
-**2026-07-27 re-measurement.** With P39 landed, re-running the
-`mem-audit` walk turned up a genuine leak in the assertion-narrowing
-path (`src/type_engine/types/narrowing/assertions.rs`): every
-`@phpstan-assert`/`@psalm-assert` call-site evaluation `Box::leak`ed a
-cloned `FunctionInfo` or `MethodInfo` to get a stable reference for
-`CallAssertionInfo`, and neither clone was ever freed. Narrowing runs
-on every conditional the forward walker visits, so this leaked once
-per asserting call touched during a pass, for the life of the
-process — worse in a long-running LSP session (re-run on every
-keystroke) than in one-shot `analyze`. Fixed by having
-`CallAssertionInfo` own the four fields it actually needs (an
-`Arc`-shared parameter vector plus three small `Vec`s) instead of
-leaking the whole clone.
-
-Re-measured on four real projects (one small, two mid-size, one
-large) with the fixed build: live allocations dropped 7-12% on the
-three larger projects and 53% on the small one, which spends
-proportionally more of its pass time in narrowing relative to its
-total symbol count. Live bytes dropped correspondingly (tens of MB on
-the larger projects). The allocator-overhead *percentage* barely
-moved — mimalloc's rounding overhead per allocation is roughly
-constant regardless of which allocations are removed, so cutting
-count shrinks both the overhead and the total footprint by a similar
-proportion. This confirms the mechanism above without yet closing the
-gap enough to retire this item.
-
-While re-measuring, the audit's drop-and-measure probes (`src/mem_audit.rs`)
-were extended to cover every remaining `Backend` store (the phar
-archive cache, autoload/stub indexes, workspace PSR-4/vendor paths,
-diagnostic pull-model caches, and more). Previously 18-26% of live
-heap was an unattributed gap between the field-level walk and the
-allocator's own count; the probes now account for nearly all of it, so
-future passes on this item measure against a real residual (dominated
-by the `ustr` name interner and short-lived per-request state) instead
-of an unexplained shortfall. One find from the newly-covered stores:
-`phar_archives` (raw phar bytes plus a byte-offset index, kept for lazy
-re-extraction of phar-embedded PHP files such as vendor-shipped
-PHPStan) held on the order of 25 MB on projects with a phar-shaped
-dependency, previously invisible to the audit.
-
-If a meaningful gap remains once other in-flight allocation-count
-reductions land, the next lever is arena-allocating the member
-metadata (bump-allocate `MethodInfo`/`PropertyInfo`/`ParameterInfo` per
-resolved class instead of one `Box`/`Arc` per member) — a much larger
-change than anything else in this list, and today's re-measurement
-does not yet show the overhead percentage moving enough to justify it
-on its own.
-
----
-
 ## P42. Reference index is built during the headless `analyze` pipeline but never queried there
 
 **Impact: Low-Medium · Effort: Low**

docs/todo/type-inference.md

@@ -308,7 +308,7 @@ The remaining gap is that *unannotated* closures like
 `$fn = function(int $x): string { ... }` resolve to bare `Closure`
 with no signature detail. `infer_closure_literal_type` (in
 `rhs_resolution.rs`) already embeds the inferred return type in a
-`PhpType::Callable`, but always leaves `params` empty, so it does not
+`TypeKind::Callable`, but always leaves `params` empty, so it does not
 produce a full callable type string for variable-type contexts.
 
 **Example:**