Closes #293.

What this changes

Scalar literals now survive ordinary expression flow instead of being widened to string/int/float at resolution time.

Given:

function test(bool $flag): void {
    $scalar = 'draft';
    $choice = $flag ? 'asc' : 'desc';
    $collection = [$scalar, $choice];
}

hovering $scalar used to show $scalar = string. It now shows $scalar = 'draft', and $choice shows 'asc'|'desc'. $collection still shows list<string>, because storing into a mutable collection is where the distinction stops being meaningful.

Why

resolve_rhs_expression widened literals immediately, so every consumer that wanted precision had to rebuild it. The diagnostic path did that with narrow_literal_type(), which walked the expression tree a second time and handled a fixed list of compound forms — ternary, null-coalesce, match, and parenthesised wrappers. Anything outside that list, and anything reached by hover, completion, or inferred PHPDoc return types, got no literal precision at all.

As #293 puts it, the narrowing pass is architecturally fragile because it enumerates expression forms rather than getting precision for free from the resolver.

How

• Resolution returns literal_string_raw / literal_int / literal_float for scalar literals and preserves them through parenthesised and signed expressions, ternaries, match arms, coalescing, branch merges, guards, increments and decrements, by-reference updates, and return inference.
• A runtime-value join, distinct from coercive parameter subtyping, keeps int|float a real runtime union while letting broad scalar domains absorb literal subsets.
• Semantic literal equality, hashing, and union deduplication are deterministic without conflating case-sensitive string payloads, escaped quote semantics, malformed numerics, aliases, or the Number class.
• A shallow widening operation deliberately leaves nested generic, shape, and callable payloads intact, and is applied at the real mutable boundaries: array literals, shapes, keyed writes, appends, spreads, iterator conversion, and collection return paths.
• Array keys are normalised across literal and broad scalar domains, nullable and union keys, explicit numeric shape keys, escaped keys, object shapes, and unresolved class-constant keys, following PHP's own coercion rules.
• PHP 8 numeric-string recognition and the scalar aliases numeric, the lowercase pseudo-type number, the class Number, and real are corrected.
• narrow_literal_type() and the closure, assignment, and by-reference collection workarounds are removed, since the type engine now carries the information they existed to recover.

Tests

New coverage spans literals, structured unions, malformed and overflow numerics, PHP numeric strings, class metadata, branch joins, nullable and coalesce flow, keyed and appended collections, array-key coercion, iterator conversion, typed and variadic by-reference parameters, and large literal return unions.

hover_preserves_scalar_literals_but_widens_collections fails on an unmodified checkout of the base commit with $scalar = string, and passes with this change.

Validation

Run on Windows against base 88ba719:

The same suite on the unmodified base commit, measured in the same session with no local changes at all, gives 11,463 run, 11,426 passed, 37 failed, 2 skipped. The two failure sets are identical by name — nothing introduced, nothing fixed — and are 9 library, 27 integration, and 1 unit case, all Windows path, symlink, and URI-escaping behaviour unrelated to this change.

Performance

Because performance matters here, base and candidate were compared by building both benchmark harnesses first and then running them alternately for three rounds each, so background load affects both sides equally. Medians:

Repeating an identical build varied by ±4% to ±12% between rounds, so none of these is resolvable as a real difference, including on update_ast_parse_time, which this change cannot affect and which is included as a control. No regression is detectable at this machine's resolution, and no improvement is claimed.

Not verified locally

php -l examples/demo.php, php -d zend.assertions=1 examples/demo.php, and php -l examples/laravel/app/Demo.php need a PHP CLI that was not available on the machine used, and coverage via cargo llvm-cov and the Linux-musl target were likewise unavailable. Those are left to CI.

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, examples/)
• I have updated the config schema (config-schema.json)
• I have added/updated tests to cover my changes
• I fully understand the code that I am submitting (what it does,
  how it works, how it's organized), including any code drafted by an LLM.
• For any prose generated by an LLM, I have proof-read and copy-edited with
  an eye towards deleting anything that is irrelevant, clarifying anything
  that is confusing, and adding details that are relevant. This includes,
  for example, commit descriptions, PR descriptions, and code comments.