Update changelog and performance todo

Author: AJenbo

docs/CHANGELOG.md

@@ -7,17 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Laravel custom Eloquent builder support.** Models using the `#[UseEloquentBuilder]` attribute now have their custom builder's methods forwarded as static methods on the model. `query()`, `newQuery()`, and `newModelQuery()` return the custom builder type with correct generic model substitution. Contributed by @MingJen in https://github.com/AJenbo/phpantom_lsp/pull/118.
+
 ### Fixed
 
 - **`throw new` completion no longer offers non-instantiable types.** Interfaces, abstract classes, traits, and enums are now filtered out, matching the behavior of `new` completion. The `throw new` path also now filters to Throwable descendants only.
 - **Unified class name completion architecture.** `throw new` and `catch()` completion now use the same `build_class_name_completions` pipeline as `new`, `extends`, `implements`, etc. `throw new` uses a `ThrowNew` context (instantiable + Throwable) and `catch()`/`@throws` uses a `Catch` context (class or interface + Throwable). This gives both contexts the same affinity scoring, FQN shortening via use-map, namespace segment drill-down, deprecation flags, and consistent filtering. The separate `build_catch_class_name_completions` function has been removed.
 - **Consolidated class completion passes.** The previous 5-pass architecture (use-map, same-namespace, fqn_uri_index, fqn_uri_index duplicate, stub_index) has been simplified to 2 passes (fqn_uri_index + stub_index) with an inline `classify` closure that determines tier (`'0'` use-imported, `'1'` same/sub-namespace, `'2'` everything else) per candidate. The redundant pass 4 (identical to pass 3) is eliminated, and tier assignment is now based on proximity checks rather than which data source produced the item.
 
+### Changed
+
+- **Improved LSP responsiveness.** File parsing (`update_ast`) and diagnostics now run in background tasks, preventing interactive requests (completion, hover) from being blocked by full-file parses during typing. Contributed by @MingJen in https://github.com/AJenbo/phpantom_lsp/pull/118.
+- **Member completion caching.** Unfiltered member lists are cached per-target to speed up subsequent completions during keyword entry. Contributed by @MingJen in https://github.com/AJenbo/phpantom_lsp/pull/118.
+- **Laravel startup performance.** Common Laravel builder classes are warmed in the background at startup to eliminate the first-access penalty on Eloquent completions. Contributed by @MingJen in https://github.com/AJenbo/phpantom_lsp/pull/118.
+
 ## [0.8.0] - 2026-05-14
 
 ### Added
 
-- **Laravel custom Eloquent builder support.** Models using the `#[UseEloquentBuilder]` attribute now have their custom builder's methods forwarded as static methods on the model. `query()`, `newQuery()`, and `newModelQuery()` return the custom builder type with correct generic model substitution.
 - **Blade template support.** Completion, hover, go-to-definition, diagnostics, semantic tokens, and inlay hints work inside `.blade.php` files. Contributed by @MingJen in https://github.com/AJenbo/phpantom_lsp/pull/100.
 - **Blade keyword highlighting.** Blade directives, echo delimiters, PHP keywords, cast types, comments, and PHPDoc tags inside `.blade.php` files now receive semantic tokens for proper syntax coloring.
 - **Blade view directive navigation.** Go-to-definition works on view names inside Blade directives (`@include`, `@extends`, `@includeIf`, `@includeWhen`, `@includeUnless`, `@includeFirst`, `@component`, `@each`), jumping to the referenced template file.
@@ -53,9 +62,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **Improved LSP responsiveness.** File parsing (`update_ast`) and diagnostics now run in background tasks, preventing interactive requests (completion, hover) from being blocked by full-file parses during typing.
-- **Member completion caching.** Unfiltered member lists are cached per-target to speed up subsequent completions during keyword entry.
-- **Laravel startup performance.** Common Laravel builder classes are warmed in the background at startup to eliminate the first-access penalty on Eloquent completions.
 - **Find References performance and freshness.** Project-wide Find References now avoids more unnecessary file work while still returning references through aliased class and function imports, and it refreshes newly added workspace PHP files on later searches. Contributed by @MingJen in https://github.com/AJenbo/phpantom_lsp/pull/116.
 - **Incremental text sync.** The server now uses incremental document sync, receiving only changed ranges from the editor instead of the full file content on every keystroke.
 - **LSP responsiveness.** Hover, go-to-definition, signature help, code actions, rename, and other handlers now run on background threads. Slow requests no longer block other requests or cancellations.

docs/todo.md

@@ -163,6 +163,7 @@ unlikely to move the needle for most users.
 |     | **[Performance](todo/performance.md) / [Eager Resolution](todo/eager-resolution.md)**                                                                                       |             |             |
 | ER5 | [Mago-style separated metadata](todo/eager-resolution.md#er5--mago-style-separated-metadata)                                                                                | High        | High        |
 | P14 | [Eager docblock parsing into structured fields](todo/performance.md#p14-eager-docblock-parsing-into-structured-fields)                                                      | Medium      | Medium      |
+| P9  | [`resolved_class_cache` generic-arg specialisation](todo/performance.md#p9-resolved_class_cache-generic-arg-specialisation)                                                 | Medium      | Medium      |
 | P11 | [Uncached base-resolution in `build_scope_methods_for_builder`](todo/performance.md#p11-uncached-base-resolution-in-build_scope_methods_for_builder)                        | Low-Medium  | Low         |
 | P3  | Parallel pre-filter in `find_implementors`                                                                                                                                  | Low-Medium  | Medium      |
 | P4  | `memmem` for block comment terminator search                                                                                                                                | Low         | Low         |
@@ -171,6 +172,7 @@ unlikely to move the needle for most users.
 | P7  | `diag_pending_uris` uses `Vec::contains` for dedup                                                                                                                          | Low         | Low         |
 | P8  | `find_class_in_uri_classes_index` linear fallback scan                                                                                                                       | Low         | Low         |
 | P12 | [`find_or_load_function` Phase 1.75 serial bottleneck](todo/performance.md#p12-find_or_load_function-phase-175-serial-bottleneck)                                           | Low         | Low         |
+| P17 | [`mago-names` resolution on the parse hot path](todo/performance.md#p17-mago-names-resolution-on-the-parse-hot-path)                                                        | Medium      | Low         |
 | P18 | [Subtype result caching](todo/performance.md#p18-subtype-result-caching) (per-request HashMap for hierarchy walks)                                                          | Medium      | Low         |
 | P19 | [Arena reuse on the parse hot path](todo/performance.md#p19-arena-reuse-on-the-parse-hot-path) (thread-local `Bump::reset()` instead of `Bump::new()`)                      | Medium      | Low         |
 | P20 | [Content-hash gated resolution cache persistence](todo/performance.md#p20-content-hash-gated-resolution-cache-persistence)                                                  | Medium      | Medium      |

docs/todo/performance.md

@@ -190,6 +190,36 @@ window.
 
 ---
 
+## P9. `resolved_class_cache` generic-arg specialisation
+
+**Impact: Medium · Effort: Medium**
+
+The resolved-class cache is keyed by `(FQN, Vec<String>)`. Every
+distinct generic instantiation of the same class (e.g.
+`Builder<User>`, `Builder<Order>`, `Builder<Product>`) triggers a
+full `resolve_class_fully` call, even though the base resolution
+(inheritance merging, trait merging, virtual member injection) is
+identical. Only the final generic substitution differs.
+
+In a Laravel codebase with hundreds of Eloquent models, this means
+`Builder` is fully resolved hundreds of times, once per model.
+
+### Fix
+
+Cache the base-resolved class (before generic substitution)
+separately, keyed by FQN alone. When a generic instantiation is
+requested, look up the base-resolved class and apply
+`apply_substitution` on top. The substitution step is cheap
+(tree walk) compared to the full resolution (inheritance walking,
+trait merging, virtual member providers).
+
+This requires splitting `resolve_class_fully` into two stages:
+base resolution (cached by FQN) and generic specialisation (cached
+by `(FQN, Vec<String>)` as today, but with a much cheaper miss
+path).
+
+---
+
 ## P11. Uncached base-resolution in `build_scope_methods_for_builder`
 
 **Impact: Low-Medium · Effort: Low**
@@ -476,6 +506,48 @@ essentially free for both eager and deferred indexing paths.
 
 ---
 
+## P17. `mago-names` resolution on the parse hot path
+
+**Impact: Medium · Effort: Low**
+
+The `mago-names` name resolver runs synchronously inside
+`update_ast_inner`, adding a full AST walk plus an owned `HashMap`
+copy on every `didChange` event. Measured regression from `6a0737a`
+("Migrate to use mago-names"):
+
+| Benchmark        | Before | After | Δ    |
+| ---------------- | ------ | ----- | ---- |
+| with_narrowing   | 12 ms  | 15 ms | +25% |
+| 5_methods_chain  | 8 ms   | 10 ms | +25% |
+| carbon_class     | 250 ms | 340 ms | +36% |
+| large_file       | 150 ms | 210 ms | +40% |
+
+The resolved names are currently consumed only by diagnostics (which
+run asynchronously) and `FileContext::resolve_name_at()`. Nothing on
+the completion hot path requires this data to be computed eagerly.
+
+### Fix
+
+Defer name resolution out of `update_ast_inner`. Options:
+
+- **Lazy resolution:** compute `OwnedResolvedNames` on first access
+  per file version, invalidate on the next `update_ast`. Moves the
+  cost off the typing hot path entirely.
+- **Diagnostic-worker resolution:** run the resolver in the
+  diagnostic worker clone of `Backend`, since diagnostics are the
+  primary consumer.
+
+### When to implement
+
+Low priority. The `mago-names` migration is complete, but the
+`use_map` is still used by several consumers. Further refactoring
+(migrating more consumers to byte-offset lookups, eventually
+removing `use_map`) will change the access patterns. Optimizing
+now would likely be reworked. Revisit once `use_map` usage is
+significantly reduced.
+
+---
+
 ## P18. Subtype result caching
 
 **Impact: Medium · Effort: Low**