Find References, Rename, and Go to Implementation no longer look stalled

during startup

Author: AJenbo

docs/CHANGELOG.md

@@ -54,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Find References, Rename, and Go to Implementation no longer look stalled during startup indexing.** A search started while the background index is still parsing the workspace waits for that index to finish, since acting on a partial index would silently miss results. That wait now shows in the request's own progress bar as "Waiting for workspace index" alongside the index's live file counts, instead of sitting at "Resolving…" with no indication of what it is waiting for.
 - **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.

docs/todo.md

@@ -25,9 +25,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         |
-| 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        |
 | L18 | [`Macroable::mixin()` registrations](todo/laravel.md)                                                                          | Low         | Medium      |
 | L1  | [Facade completion](todo/laravel.md#l1-facade-completion-upstream-method-template-improvement)                                                                 | High        | High        |

docs/todo/indexing.md

@@ -343,50 +343,6 @@ ready to implement.
 
 ---
 
-## X10. Interactive requests block on the workspace index lock during initial indexing
-
-**Impact: Medium · Effort: Medium**
-
-The full background index holds `workspace_index_lock` for its entire
-run. Any request that reaches `ensure_workspace_indexed` during that
-window parks on the lock until the whole workspace parse finishes
-(tens of seconds on large projects):
-
-- **Laravel string-key completion** (`config('`, `route('`, `view('`,
-  `__('`): the key enumerations call `user_file_symbol_maps()`, so
-  the first such completion during startup stalls instead of
-  returning what is already parsed. Same for the invalid-string-key
-  diagnostics pass on open files.
-- **Find References / Rename**: these need complete data, so waiting
-  is semantically right, but the user gets no signal that the wait is
-  the index (the request's own progress token stays at "Resolving…").
-- **Go to Implementation** (full strategy, index not yet ready):
-  blocks the same way.
-
-Core completion, hover, and go-to-definition are unaffected (they use
-lazy per-class loading and never touch the index lock), which is the
-main responsiveness guarantee to preserve.
-
-### Direction
-
-Completeness-critical consumers (references, rename, GTI) should keep
-waiting but report "waiting for workspace index" through their
-progress token. Best-effort consumers (string-key completion, the
-string-key diagnostics pass) should not call
-`ensure_workspace_indexed` while `full_index_in_progress` is set;
-they should serve partial results from the current `symbol_maps`
-snapshot and rely on the post-index `workspace/diagnostic/refresh`
-to correct anything that was missing. Additionally, the config /
-view / translation enumerations are directory-scoped (`config/`,
-`resources/views/`, `lang/`) and could be fed by targeted scans that
-do not depend on the full workspace parse at all.
-
-Related but separate: the deferred X2 priority-aware scheduling
-covers the CPU-contention side (index workers saturating all cores);
-this item covers the lock-blocking side.
-
----
-
 ## X9. Honor editor file excludes and PHP associations during indexing
 
 **Impact: Low-Medium · Effort: Medium**

docs/todo/performance.md

@@ -856,71 +856,6 @@ and delete the second pass entirely.
 
 ---
 
-## P33. Workspace diagnostics leaves the whole project fully resolved in memory
-
-**Impact: High · Effort: Medium-High**
-
-Enabling background workspace diagnostics raises resident memory
-several-fold over a full index alone. Measured on a mid-size Laravel
-project (~1,200 indexed user files, ~3,000 resolved classes) the live
-set after the pass is ~1.16 GB, of which the resolved-class cache is
-**~748 MB — about 65%**. Ranked by the RSS each structure releases
-when dropped: resolved-class cache ~748 MB, class indexes
-(`method_store` + `fqn_class_index` + `uri_classes_index`) ~99 MB,
-`symbol_maps` ~26 MB, `reference_index` ~14 MB. The cache
-holds ~247 KB per resolved class.
-
-Two compounding causes:
-
-1. **Inheritance flattening stores a member slot per class.** Each
-   fully-resolved class stores the complete flattened member set (own +
-   trait + parent + interface + mixin), so a project with ~3 K classes
-   at ~214 members each holds ~648 K method slots. The distinct
-   *allocations* behind those slots are now heavily shared for methods,
-   properties, and constants alike: a slot the merge does not rewrite
-   points back at its source `Arc<MethodInfo>`/`Arc<PropertyInfo>`/
-   `Arc<ConstantInfo>`, and the copies a merge does produce (template
-   substitution, trait / interface / enrichment merges, Eloquent Builder
-   and scope forwarding) are interned so value-identical results
-   collapse to one allocation with a shared parameter list. What remains
-   per class is the flattened `Vec<Arc<_>>` itself plus its
-   `method_index` — one pointer slot per visible member. Measured on a
-   full Laravel app (~2 K resolved classes) this residual is only
-   ~10 MB across the whole resolved-class cache; the member
-   *allocations* the vecs point at, not the pointer slots, are the bulk.
-   Bounding the cache (fix below) reclaims both; separating the pointer
-   slots on their own is not worth the rewrite.
-
-2. **The cache is retained for the whole session, unbounded.** Eager
-   population plus lazy resolution during the pass fill the cache with
-   every class in the project, and nothing evicts it afterwards.
-   Interactive requests only ever touch a small working set, so the bulk
-   sits resident for nothing. (Disabling eager population does not help:
-   the per-file diagnostic pass refills the cache to the same size.)
-
-Fix:
-
-1. **Bound the resolved-class cache.** After the workspace pass, the
-   fully-flattened metadata for every project class does not need to stay
-   resident. Either drop the cache when the pass finishes (interactive
-   requests re-resolve lazily) or make it an LRU with a size cap. The
-   recursion-guard elimination made a wholesale clear safe: resolution
-   cycles are broken by the cache's in-flight set, which `clear()`
-   deliberately leaves untouched, so clearing mid-resolution cannot
-   resurrect unbounded recursion. **Low-Medium.**
-
-Separating the per-class member vectors from a global member store
-(Mago's model, resolving members on demand instead of flattening a
-`Vec` of pointers) was the other candidate here, but measurement showed
-the residual pointer slots + `method_index` are only ~10 MB across the
-whole cache once member allocations are shared and interned. That is not
-worth moving substitution to query time (the transform-on-inherit model
-means an inherited member is not byte-identical to the declaring class's
-once template substitution or bare-`self` rewriting applies), so the
-lever is bounding the cache, not separating the metadata.
-
----
-
 ## P34. Eager class population is single-threaded
 
 **Impact: Medium · Effort: Medium**
@@ -995,148 +930,6 @@ CPU-sampling loop in the Appendix after any change.
 
 ---
 
-## P36. Diagnostic-path call sites re-merge inheritance per call instead of reading the resolved-class cache
-
-**Impact: Medium · Effort: Low**
-
-Six call sites on the diagnostic path call
-`resolve_class_with_inheritance` directly, re-running the full
-inheritance merge (traits, parent chain, generic substitution) on every
-call and discarding the result after reading a single member:
-
-- `src/diagnostics/undefined_variables/mod.rs` — by-reference parameter
-  positions for static, constructor, and instance calls (3 sites).
-- `src/diagnostics/type_errors/compatibility.rs` — the
-  Stringable/`__toString` acceptance check and the
-  `model-property<Model>` literal check (2 sites).
-- `src/class_lookup.rs` — the `model-property<Model>` literal subtype
-  check (1 site).
-
-Measured on a large Laravel project (release build, 32 threads): 25,676
-direct merge calls costing ~7 s of thread-CPU during the diagnostic
-pass, roughly 11% of the run's total CPU — while a resolved-class cache
-hit serves the same class in ~3 µs. The Stringable check is the likely
-hot one (it fires for every object-argument-to-string-parameter
-comparison).
-
-Route these through `resolve_class_fully_maybe_cached`; the
-resolved-class cache is active during diagnostic passes
-(`with_active_resolved_class_cache`), and `undefined_variables` has
-`self` (the `Backend`) in scope already. Note the cached result
-additionally includes interface members and virtual members. For these
-member-existence and parameter lookups that is a strict improvement
-(e.g. a `__toString` declared on an interface is currently missed), but
-verify the affected diagnostics against the fixture suites for
-unexpected acceptance changes.
-
-The provider-internal callers in `src/virtual_members/` and the
-interface merge inside `resolve_class_fully_inner` are intentional
-(they run *while* the cache entry is being built) and are out of scope.
-
-**Still worth doing, and orthogonal to the memory work below.** This is
-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 — 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-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
-at the end of `analyze` when `PHPANTOM_MEM_AUDIT` is set:
-
-```sh
-cargo build --release --features mem-audit
-PHPANTOM_MEM_AUDIT=1 ./target/release/phpantom_lsp analyze \
-  --project-root <dir> --no-colour
-```
-
-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, 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,
-`PhpType` duplication) are allocator-independent — they come from
-`size_of`/`capacity()`, not from the allocator — and were cross-checked
-identical under both `System` and `mimalloc`. Only RSS and the
-"overhead" line are allocator-specific; those are reported here for
-mimalloc, since that is what every shipped Linux binary runs (see
-`docs/BUILDING.md` for reproducing that exact build locally):
-
-| Measure                       | Mid-size Laravel app | Large Laravel app |
-| ----------------------------- | -------------------- | ----------------- |
-| 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`, 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.
-
-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` | 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 (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:
-
-- **Boxing the display-only docblock fields is a net loss.** Only 9-10%
-  of methods have no description, `@return` text, links, `@see` refs, or
-  deprecation data, so moving the six fields behind one `Option<Box<…>>`
-  would add a pointer plus an allocation header to the other 90%. The
-  same holds for constants. Properties and parameters are mostly
-  doc-free but their doc fields are few, so the win there is ~2-8 MB and
-  not worth the indirection on its own.
-- **A shared empty `SharedVec` saves under 1 MB.** Only 13% of parameter
-  vectors are empty. Worth folding into another change that touches
-  `SharedVec`, not worth a commit by itself.
-
----
-
 ## P42. Reference index is built during the headless `analyze` pipeline but never queried there
 
 **Impact: Low-Medium · Effort: Low**