Stdlib JIT: similar_text() third & arg — LLVM lowering (phase 2 of #2445)

[PurHur]

Category

stdlib

Problem

similar_text() VM supports the optional third by-reference $percent argument; JIT/AOT reject three-arg calls at compile/lowering time. Framework code and PHPT suites that capture similarity percentage cannot run under bin/jit.php or AOT.

Phase 2 of closed #2445 (two-arg VM/JIT shipped).

php-src reference

• php/php-src ext/standard/string.c — php_similar_text(), percent out-parameter
• php/php-src ext/standard/basic_functions.stub.php — similar_text signature with optional &$percent

Repro

VM (passes today)

<?php
$p = 0;
similar_text('hello', 'hallo', $p);
echo $p, "\n"; // Zend + bin/vm.php: 80

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php repro.php'
php repro.php

JIT/AOT (failure today)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php repro.php'
# LogicException from ext/standard/similar_text.php:
# similar_text() JIT/AOT only supports two arguments in this compiler build; use bin/vm.php for &$percent

Two-arg calls (similar_text($a, $b)) must remain green.

Scope (this repo)

Layer	Files	Notes
VM	ext/standard/similar_text.php	Reference write to $percent (baseline — do not regress)
JIT	ext/standard/similar_text.php::call(), lib/JIT/Builtin/StringSimilarText.php (or existing helper)	Emit percent write-back via indirect slot / param-by-ref pattern (#3161)
AOT	shared JIT builtin	Same LLVM path as JIT
Tests	test/compliance/cases/stdlib/similar_text_percent.phpt	VM + JIT; assert $p === 80 for repro strings

Reference-arg pattern: compare preg_match $matches JIT deferrals and closure use (&$x) (#3108).

Done when

• Three-arg repro prints 80 under bin/jit.php (native MCJIT, no VM fallback)
• Two-arg repro unchanged on JIT/AOT
• ./script/ci-fast.sh --filter similar_text_percent green
• docs/capabilities.md regenerated if JIT notes change

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter similar_text_percent'

Related

• Stdlib: similar_text() VM + LLVM JIT/AOT #2445 closed (two-arg baseline)
• Stdlib JIT: str_word_count() format 1/2 — word list and offset map (phase 2 of #2382) #3584 str_word_count JIT format 1/2 (same phase-2 JIT stdlib batch)

[PurHur]

claim: cursor-agent-lane-b — starting this run (JIT third-arg &$percent for similar_text, phase 2 of #2445)

[PurHur]

Implemented in PR #3959 (branch `agent/issue-3583-similar-text-percent-jit`).

Changes: `BuiltinByRefParams` index 2 for `similar_text`; JIT `call()` writes `$percent` via `strlen` + `__value__writeDouble` (same pattern as `modf()`).

Verification (this runner):

• VM repro `hello`/`hallo` → `80` — pass
• `vendor/bin/phpunit test/compliance/SimilarTextVMTest.php test/unit/SimilarTextBuiltinTest.php test/unit/BuiltinByRefParamsTest.php` — OK
• JIT MCJIT: `script/jit-runtime-probe.php` fails here (pre-existing `bin/jit.php` segfault on trivial code); JIT PHPT pending probe-green host