Type narrowing against @phpstan-assert/@psalm-assert no longer leaks

memory

Author: AJenbo

docs/CHANGELOG.md

@@ -52,6 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Type narrowing against `@phpstan-assert`/`@psalm-assert` no longer leaks memory.** Evaluating a narrowing call such as `Assert::isInstanceOf($x, Foo::class)` or a custom function/method with the same annotations allocated a small amount of memory that was never freed. This ran on every conditional touched during completion, hover, diagnostics, and go-to-definition, so memory held by a long-running editor session grew slowly but permanently the more the project was edited. Fixed by no longer leaking the allocation.
 - **Renaming a namespace no longer corrupts group `use` statements.** Renaming a namespace segment that is imported with a group `use` (e.g. `use App\Old\{Foo, Bar};`) previously rewrote the group's shared prefix and then also spliced the new prefix into each member name, producing invalid PHP like `use App\New\{App\New\Foo, Bar};`. The member names are left untouched now, since the prefix rewrite alone already updates the whole statement correctly.
 - **Parameter name inlay hints no longer shift to the wrong parameter when only part of a multi-line call is visible.** Editors request inlay hints only for the currently visible viewport, and when a call's arguments were split across the viewport boundary, every hint after the first excluded argument was labelled with the previous parameter's name instead of its own. This was most noticeable on multi-line constructor calls with several arguments, such as those using constructor property promotion.
 - **Linked editing no longer types into unrelated parts of the file.** Adding a line above a variable (for example inserting a `/** */` docblock) and then typing could insert the typed characters at two arbitrary places further down, such as in the middle of a method name and in front of a trailing comment. PHPantom is re-reading the file in the background while you type, and linked editing was handing the editor positions measured against the previous version of the file, which the editor then edited on trust. Linked editing now verifies that the positions it reports still point at the variable, and offers nothing at all if they do not, so a keystroke can never land somewhere unexpected. It also becomes available in Blade templates, where the reported positions are checked against the template itself rather than the generated PHP.

docs/todo/performance.md

@@ -1182,14 +1182,56 @@ 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 removes hundreds of thousands of allocations as a side
-effect (interning `SymbolKind` strings), so re-measure this line after
-it lands. If a meaningful gap remains afterward, 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, so only
-worth it if the per-allocation overhead is still the dominant cost once
-the count itself has come down.
+`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.
 
 ---
 

src/mem_audit.rs

@@ -1579,6 +1579,88 @@ pub(crate) fn report(backend: &Backend, runner_content_bytes: usize) {
     probe("global_functions", &mut || {
         backend.symbols.global_functions.write().clear()
     });
+    probe("global_defines", &mut || {
+        backend.symbols.global_defines.write().clear()
+    });
+    probe("gti_index", &mut || {
+        backend.symbols.gti_index.write().clear()
+    });
+    probe("uri_globals_index", &mut || {
+        backend.symbols.uri_globals_index.write().clear()
+    });
+    probe("fqn_uri + fqn_origin index", &mut || {
+        backend.symbols.fqn_uri_index.write().clear();
+        backend.symbols.fqn_origin_index.write().clear();
+    });
+    probe("autoload indexes", &mut || {
+        backend.symbols.autoload_function_index.write().clear();
+        backend
+            .symbols
+            .autoload_function_origin_index
+            .write()
+            .clear();
+        backend.symbols.autoload_constant_index.write().clear();
+        backend
+            .symbols
+            .autoload_constant_origin_index
+            .write()
+            .clear();
+        backend.symbols.autoload_file_paths.write().clear();
+    });
+    probe("class_not_found_cache", &mut || {
+        backend.symbols.class_not_found_cache.write().clear()
+    });
+    probe("stub indexes", &mut || {
+        backend.stub_index.write().clear();
+        backend.stub_function_index.write().clear();
+        backend.stub_constant_index.write().clear();
+    });
+    probe("parsed_uris", &mut || backend.parsed_uris.write().clear());
+    probe("laravel_aliases", &mut || {
+        *backend.laravel_aliases.write() = None
+    });
+    probe("laravel seed/mixin/pivot/command sets", &mut || {
+        backend.laravel_macro_seeds.write().clear();
+        backend.laravel_macro_mixin_uris.write().clear();
+        backend.laravel_date_seed_uris.write().clear();
+        *backend.laravel_pivots.write() = Default::default();
+        *backend.laravel_commands.write() = Default::default();
+    });
+    probe("blade_uris", &mut || backend.blade_uris.write().clear());
+    probe("phar_archives", &mut || {
+        backend.phar_archives.write().clear()
+    });
+    probe("open_files", &mut || backend.open_files.write().clear());
+    probe("did_change_parse_locks", &mut || {
+        backend.did_change_parse_locks.lock().clear()
+    });
+    probe("workspace psr4 + vendor paths", &mut || {
+        backend.workspace.psr4_mappings.write().clear();
+        backend.workspace.vendor_uri_prefixes.lock().clear();
+        backend.workspace.vendor_dir_paths.lock().clear();
+        backend
+            .workspace
+            .vendor_package_origin_roots
+            .write()
+            .clear();
+    });
+    probe("diagnostic state", &mut || {
+        backend.diag.pending_uris.lock().clear();
+        backend.diag.last_slow.lock().clear();
+        backend.diag.last_fast.lock().clear();
+        backend.diag.last_full.lock().clear();
+        backend.diag.result_ids.lock().clear();
+        backend.diag.suppressed.lock().clear();
+        *backend.diag.workspace_diags.lock() = Default::default();
+    });
+
+    let (residual_bytes, residual_allocs) = live_heap();
+    eprintln!(
+        "    ── residual after every probe: {:.1} MB in {} allocations (runner file contents {:.1} MB; the rest is ustr, thread-local caches, and runtime state)",
+        mb(residual_bytes),
+        residual_allocs,
+        mb(runner_content_bytes),
+    );
 
     eprintln!(
         "── audited live total {:.1} MB (cache section {:.1} MB) | VmRSS after collect {:.1} MB | VmHWM {:.1} MB",

src/type_engine/types/narrowing/assertions.rs

@@ -6,7 +6,7 @@ use std::sync::Arc;
 
 use crate::atom::{Atom, atom, bytes_to_str};
 use crate::php_type::PhpType;
-use crate::types::{AssertionKind, ClassInfo, ParameterInfo, TypeAssertion};
+use crate::types::{AssertionKind, ClassInfo, ParameterInfo, SharedVec, TypeAssertion};
 
 use mago_span::HasSpan;
 use mago_syntax::cst::*;
@@ -22,18 +22,24 @@ use super::*;
 /// Produced by [`extract_call_assertions`] so that callers can apply
 /// narrowing logic uniformly regardless of whether the call is
 /// `myFunc($x)` or `Assert::check($x)`.
+///
+/// The callee metadata is owned rather than borrowed: the callee is a
+/// clone produced by the loader (or by the trait/parent chain walk), so
+/// there is nothing outliving the call to borrow from. Moving the four
+/// fields out of that clone keeps the cost to an `Arc` bump plus three
+/// `Vec` moves, and lets the rest of the clone drop immediately.
 pub(in crate::type_engine) struct CallAssertionInfo<'a> {
     /// The `@phpstan-assert` / `@psalm-assert` annotations on the callee.
-    pub(in crate::type_engine) assertions: &'a [TypeAssertion],
+    pub(in crate::type_engine) assertions: Vec<TypeAssertion>,
     /// The callee's parameter list (used to map assertion `$param` names
     /// to positional argument indices).
-    pub(in crate::type_engine) parameters: &'a [ParameterInfo],
+    pub(in crate::type_engine) parameters: SharedVec<ParameterInfo>,
     /// The call-site argument list.
     pub(in crate::type_engine) argument_list: &'a ArgumentList<'a>,
     /// Template parameter names from the callee's `@template` tags.
-    template_params: &'a [Atom],
+    template_params: Vec<Atom>,
     /// Template parameter → parameter name bindings (e.g. `("T", "$class")`).
-    template_bindings: &'a [(Atom, Atom)],
+    template_bindings: Vec<(Atom, Atom)>,
 }
 
 /// Try to extract assertion metadata from a call expression.
@@ -61,16 +67,12 @@ pub(in crate::type_engine) fn extract_call_assertions<'a>(
             if func_info.type_assertions.is_empty() {
                 return None;
             }
-            // SAFETY: We leak the FunctionInfo to get a stable reference.
-            // This is acceptable because narrowing runs once per completion
-            // request and the allocation is small.
-            let func_info = Box::leak(Box::new(func_info));
             Some(CallAssertionInfo {
-                assertions: &func_info.type_assertions,
-                parameters: &func_info.parameters,
+                assertions: func_info.type_assertions,
+                parameters: func_info.parameters,
                 argument_list: &func_call.argument_list,
-                template_params: &func_info.template_params,
-                template_bindings: &func_info.template_bindings,
+                template_params: func_info.template_params,
+                template_bindings: func_info.template_bindings,
             })
         }
         Call::StaticMethod(static_call) => {
@@ -170,15 +172,12 @@ fn build_method_assertion_info<'a>(
 ) -> Option<CallAssertionInfo<'a>> {
     let method =
         find_assertion_method_in_chain(class, method_name, ctx.class_loader, &mut Vec::new(), 0)?;
-    // Leak MethodInfo to get a stable reference for the duration of this
-    // narrowing pass.
-    let method = Box::leak(Box::new(method));
     Some(CallAssertionInfo {
-        assertions: &method.type_assertions,
-        parameters: &method.parameters,
+        assertions: method.type_assertions,
+        parameters: method.parameters,
         argument_list,
-        template_params: &method.template_params,
-        template_bindings: &method.template_bindings,
+        template_params: method.template_params,
+        template_bindings: method.template_bindings,
     })
 }
 
@@ -324,12 +323,12 @@ pub(in crate::type_engine) fn try_apply_custom_assert_narrowing(
         None => return false,
     };
     let mut definite = false;
-    for assertion in info.assertions {
+    for assertion in &info.assertions {
         if assertion.kind != AssertionKind::Always {
             continue;
         }
         if let Some(arg_var) =
-            find_assertion_arg_variable(info.argument_list, &assertion.param_name, info.parameters)
+            find_assertion_arg_variable(info.argument_list, &assertion.param_name, &info.parameters)
             && arg_var == ctx.var_name
         {
             // Resolve the asserted type.  When the type is a template
@@ -404,7 +403,7 @@ pub(in crate::type_engine) fn collect_assert_reexport_conditions<'a>(
         return Vec::new();
     };
     let mut out = Vec::new();
-    for assertion in info.assertions {
+    for assertion in &info.assertions {
         if assertion.kind != AssertionKind::Always {
             continue;
         }
@@ -420,7 +419,7 @@ pub(in crate::type_engine) fn collect_assert_reexport_conditions<'a>(
             continue;
         };
         if let Some(arg_expr) =
-            assertion_arg_expression(info.argument_list, &assertion.param_name, info.parameters)
+            assertion_arg_expression(info.argument_list, &assertion.param_name, &info.parameters)
         {
             out.push((arg_expr, asserts_true));
         }
@@ -476,7 +475,7 @@ pub(in crate::type_engine) fn call_asserts_not_null(
             && find_assertion_arg_variable(
                 info.argument_list,
                 &assertion.param_name,
-                info.parameters,
+                &info.parameters,
             )
             .as_deref()
                 == Some(ctx.var_name)

src/type_engine/types/narrowing/guards.rs

@@ -373,7 +373,7 @@ pub(in crate::type_engine) fn apply_guard_clause_narrowing(
         // inverted=true, same logic as try_apply_assert_condition_narrowing
         let function_returned_true = condition_negated;
 
-        for assertion in info.assertions {
+        for assertion in &info.assertions {
             let applies_positively = match assertion.kind {
                 AssertionKind::IfTrue => function_returned_true,
                 AssertionKind::IfFalse => !function_returned_true,
@@ -383,7 +383,7 @@ pub(in crate::type_engine) fn apply_guard_clause_narrowing(
             if let Some(arg_var) = find_assertion_arg_variable(
                 info.argument_list,
                 &assertion.param_name,
-                info.parameters,
+                &info.parameters,
             ) && arg_var == ctx.var_name
             {
                 let should_exclude = assertion.negated ^ !applies_positively;