perf(codegen): recover guarded ordinary-parameter specialization lost by #8033

[proggeramlug]

Summary

PR #8033 correctly stopped treating erased TypeScript binding annotations as runtime representation proofs, but it also removed ordinary function-parameter evidence from generic function bodies. That causes a large, reproducible specialization cliff across the current performance corpus.

Do not revert #8033 or seed the generic body from declared parameter types. The correctness constraint from #7846 is real. We need a guarded parameter-specialized clone (or equivalent entry guard) with the unchanged generic body as fallback.

Current-main regression

Measured at exact main 601a02d235af2d9af1841089426a1da379edac0a.

The clean M1 mini sweep regressed from the previously recorded 843ef621f sweep as follows:

• Perry/Node wins: 10/19 -> 2/19
• Perry/scriptc wins: 14/19 -> 8/18
• Perry geomean across all 19 rows: 3.480x slower
• clean and separately dirty corroboration agreed within 0.2%

Largest wall-time changes on the clean mini:

benchmark	843ef621f	current main	change
pipeline	0.1630 s	3.3585 s	+1960%
asyncpipe	0.0980 s	1.1216 s	+1045%
retain_wide	0.1840 s	1.0826 s	+488%
shapes	0.0550 s	0.3183 s	+479%
interp	0.8090 s	3.9931 s	+394%
iso_miss	0.9380 s	4.4743 s	+377%

The current timings also reproduce the older conservative-codegen regbase across 15 common rows: geomean current/regbase is 1.00003x, with a maximum row difference of 1.24%.

Causal A/B

I built a diagnostic-only compiler from exact current main that changed only ordinary compile_function admission:

• local_types remained unchanged;
• proven_local_types was seeded from f.params only;
• module globals and local initializers were excluded;
• runtime, stdlib, benchmark input, compile flags, and execution environment were otherwise held fixed.

This control is intentionally unsound for lying annotations and is not a proposed patch. It exists only to identify the lost optimization surface.

Every tested benchmark retained byte-exact output. Same-host retired instructions were:

benchmark	current main	parameter-hint control	reduction	current/control
asyncpipe	17,054,037,641	1,279,430,024	92.5%	13.329x
interp	64,455,747,802	12,683,767,308	80.3%	5.082x
iso_miss	72,572,449,776	15,332,837,352	78.9%	4.733x
pipeline	52,150,730,952	3,714,983,318	92.9%	14.038x
tree	31,782,383,093	8,896,702,263	72.0%	3.572x

interp was repeated three times in each arm. Current was 64.455-64.478B instructions; the parameter-only control was 12.684-12.699B. The control returns to the previously recorded roughly 11.5-14.1B instruction band.

This proves that lost ordinary-parameter type evidence is the dominant cause of the headline regression.

Mechanism

In current codegen/function.rs:

1. f.params still populate local_types.
2. The generic FnCtx initializes proven_local_types empty.
3. stable_local_type_proof() deliberately reads only proven_local_types and rejects reassigned locals.
4. Therefore an ordinary typed parameter is unproven throughout the generic body unless a separate guarded clone supplies evidence.

This is especially costly for the interpreter corpus. Hot recursive functions such as evalNode(n: Node, env: Env), lookup(env: Env, name: string), parser functions taking Parser, and lex(src: string) lose typed property, array, string, and numeric lowering at every use.

Current interp --opt-report=json records 8 selections and 64 denials, including:

• pointer-shape: 0 selected / 49 denied
• canonical-slot: 7 selected / 3 denied
• specialized ABI: 1 selected / 12 denied

The diagnostic control does not repair pointer-shape clone routing (it remains 0/49). Its performance recovery comes from letting the ordinary body lowering consume the parameter type again.

Ruled out

• Mini noise: independent clean/dirty sweeps agree within 0.2%.
• Native-root GC overhead / Propagate native-root decisions to codegen-unit workers #8071: a compile-time PERRY_RS4GC=0 shadow-root control did not recover performance. asyncpipe retired 17.08B vs 17.07B instructions; interp worsened to 71.30B from 64.63B.
• Output/correctness differences: Perry remained byte-exact on all 19 sweep rows; the five causal-control programs above were byte-exact in both arms.

Required soundness boundary

TypeScript annotations are erased and may lie. #7846 demonstrates that a declared scalar, class, array, or capture type cannot by itself select an unguarded representation or behavior. The generic body and GC rooting must remain conservative.

A sound recovery should therefore build on guarded clone-and-route machinery:

1. Select eligible ordinary parameter tuples without changing the generic entry/body semantics.
2. Emit runtime guards for the complete tuple before entering a specialized body clone.
3. Populate proven_local_types only inside the successfully guarded clone.
4. Preserve the generic boxed fallback for failed guards and indirect/unknown callers.
5. Route direct call sites only when their current argument facts prove the same tuple.
6. Support recursive calls from a guarded clone without reintroducing annotation trust.
7. Add object/array/discriminated-union parameter coverage; existing specialized ABI coverage is primarily scalar/string/typed-array and does not cover the hot Node/Env shapes here.

This likely belongs with the clone-and-route work already referenced by the pointer-shape report as #7034 section 1.

Acceptance

• Lying-annotation regressions, including test_gap_7846_local_binding_type_proofs.ts, pass through the generic fallback with Node-equivalent output.
• Positive tests prove the runtime guard is present and the specialized clone receives parameter proofs only after that guard.
• Negative tests prove a wrong scalar/object/array/union value cannot enter the clone.
• Direct, indirect, and recursive call paths retain a valid generic fallback.
• Precise-root/forced-moving verification remains green for both clone and fallback paths.
• interp, iso_miss, pipeline, asyncpipe, and tree are remeasured on the clean mini with exact-output gates.
• The recovered instruction count is structurally pinned or otherwise guarded so this cliff cannot silently recur.

Measurement provenance

Perry was built with:

cargo build --release -p perry -p perry-runtime-static -p perry-stdlib-static

Compiles pinned the exact release directory with PERRY_RUNTIME_DIR, PERRY_NO_AUTO_OPTIMIZE=1, PERRY_NO_CACHE=1, and --no-cache. Nothing was built on the mini. The accepted mini cells were warmed and then measured best-of-five in interleaved order with exit/output validation on every run.

[proggeramlug]

Status: the in-flight branch works, and it recovers nearly all of the regression soundly

The perf/issue-8079-guarded-param-specialization worktree had ~2,900 lines of new code across 34 files sitting uncommitted with no active owner. I committed it as-is to the branch first (2f70cd7bb, unvalidated preservation commit — git reset --soft HEAD~1 restores the exact working-tree state) and then validated it. Nothing was rebased or edited.

Acceptance test: passes byte-exact

test-files/test_gap_specabi_ordinary_param_guards.ts against the pinned oracle (node v26.5.1, matching .node-version):

PASS  test_gap_specabi_ordinary_param_guards
Parity Pass: 1   Parity Fail: 0   Compile Fail: 0   Crashed: 0   Skipped: 0
Parity Rate: 100.0%      (harness exit 0)

The test covers every case this issue asked for: annotation lies on array elements, array container, scalar, bare number, object fields, class instance, and both flat and nested discriminated-union positions; an escaped/indirect call through const escapedArrayTotal = arrayTotal; an accessor-backed property with a getter-hit count; a parameter the body mutates; a recursive generic (treeTotal); and a 50,000-allocation loop exercised on both the clone and the failed-guard fallback.

The clone is actually live — a pass alone would be vacuous

A guard test passes trivially if the optimization never engages and everything falls back to generic. From --trace llvm on that fixture:

• 7 js_param_type_guard call sites emitted.
• 6 functions carry a $spec_* / $generic pair: arrayTotal$spec_b, addFirst$spec_b_b, choose$spec_i32_b, render$spec_b, treeTotal$spec_b, surviveMovingGc$spec_b — each beside its $generic sibling.
• mutatePayload has no clone, which is the ineligibility rule firing on the parameter whose value the body invalidates. That negative is as important as the positives.

Instruction recovery: 55–93%, matching the unsound control

A/B against the preserved sweep binaries at 601a02d235af2d9af1841089426a1da379edac0a — the exact base of this branch, and the regressed state this issue was filed about. Same sources, same --no-cache / PERRY_NO_AUTO_OPTIMIZE=1 invocation, same output basenames. instructions retired, which is load-independent, so a contended box does not distort it:

benchmark	base (regressed)	guarded	recovered	unsound control (for comparison)
pipeline	52,171,319,894	3,721,524,902	92.9%	92.9%
asyncpipe	17,060,951,945	1,369,231,377	92.0%	92.5%
retain_wide	18,446,669,808	2,471,890,150	86.6%	—
interp	64,502,116,097	12,725,435,786	80.3%	80.3%
iso_miss	72,582,797,852	15,357,602,597	78.8%	78.9%
shapes	5,141,727,141	1,291,612,836	74.9%	—
tree	31,779,662,666	14,261,587,660	55.1%	72.0%

All 14 runs exited 0, and all 14 stdouts are byte-identical to the node-derived expected outputs.

The right-hand column is the diagnostic-only, deliberately unsound parameter-hint control recorded when this issue was filed. On pipeline, interp and iso_miss the sound guarded implementation matches it to a tenth of a percent, and on asyncpipe to half a percent. That is the outcome you want: the guard is not costing measurable work relative to simply trusting the annotation.

tree is the exception — 55.1% against the control's 72.0%. Worth understanding before this lands; it is the one row where guarding is visibly leaving recovery on the table.

What is NOT done

I am reporting, not merging. Still outstanding:

• Full gap-suite regression. Only the one new test was run. A 28-file codegen change needs the whole suite.
• Unit tests for the new modules — ordinary_param_guard_tests.rs and the perry-codegen suite have not been executed.
• Wall clock on the quiet mini. Instructions measure work, not time, and are blind to idle and understate stalls. The mini numbers are what decide whether the standings recover.
• Forced-moving-GC instruments. surviveMovingGc allocates hard, but it has not been run under PERRY_GC_ZEAL=1 PERRY_GC_PROTECT_FROMSPACE=1. A guarded clone that keeps a proof-bearing parameter live across 50k allocations is exactly the shape that wants that pairing.
• Rebase. The branch is 10 commits behind main (506f4ab11) but git merge-tree reports a clean merge.
• No PR is open.

cargo check -p perry-codegen -p perry-runtime is clean (exit 0, zero errors).

Note on the artifacts

/private/tmp/perry-current-sweep-artifacts/ is what made this A/B possible in minutes rather than a 30-minute baseline rebuild — it holds the corpus sources, the expected outputs and the baseline-compiled p_* binaries. Keep it until the mini re-sweep is done.

[proggeramlug]

Not ready to close — #8094 needs a design change before it can land, and I'd rather say so
than have it merge on the strength of the instruction-count numbers alone.

The performance result is real and reproduces. What does not hold is the soundness argument.
js_param_type_guard validates the argument at entry, but the proof it licenses is
stamped for the entire clone body, and nothing re-establishes it after a call that can write
through an alias. collectors::has_any_mutation — the demotion gate at codegen/mod.rs:2468
— only sees syntactic writes through the parameter, because expr_has_mutation has no
LocalGet arm. So b.v = x inside the body demotes the parameter, and the identical write
inside a callee does not.

This is reachable from ordinary TypeScript with no casts, because any is assignable to
number:

interface Box { v: number; }
const poison: any = "lie";
function assign(b: Box): void { b.v = poison; }
function compute(b: Box): string {
  const before = b.v + 1;
  assign(b);
  const after = b.v + 1;
  return "before=" + before + " after=" + after + " typeof=" + typeof b.v;
}
console.log(compute({ v: 41 }));

Same runtime archive for every arm, exit 0 everywhere:

• node v26.5.1 — before=42 after=lie1 typeof=string
• base 601a02d23 — before=42 after=lie1 typeof=string
• the branch with PERRY_SPECIALIZED_ABI=0 — before=42 after=lie1 typeof=string
• the branch, default — before=42 after=lie typeof=string

An array-of-interface parameter reproduces the same way. The IR shows a bare
fadd double %field, 1.0 inside the clone with no tag check; per #7773 an fadd on a NaN-box
propagates the payload, so the wrong-typed value survives the arithmetic intact and the program
prints a plausible-looking wrong answer instead of NaN.

Full evidence, the three-way control, the IR, and three candidate fixes (one of which is
already implemented in this same PR, in spec_return_proof.rs, just not applied to the codegen
body path) are in the PR comment.

Separately, lint — a required context — fails on the branch with four findings that
git diff origin/main..HEAD shows are introduced by it. Every other script in the lint job
passes at 514ff7c9a, including the three #8092 reported red on main.

The tree row from the sweep is also explained: param_guard.rs::build_named refuses class
types outright, so in tree.ts only build(depth: number) is guardable — count(t: Tree),
the hot recursive one, is not, and the Tree constructor is refused at one remove because
Tree | null is a union containing a class. That is a scope boundary, not an inherent limit;
the runtime already implements the class-identity check (class_chain_reaches,
param_type_guard.rs:399) and codegen simply never emits a non-zero class_id.

[proggeramlug]

Update: the soundness hole reported above is fixed on the PR branch, and the performance result
survives it.

The fix is not the shape that was first proposed. Treating "the parameter was handed to a callee"
as the trigger closes only the route where we pass the reference; it does not close this one,
which I measured:

let stash: any = null;
function poison(): void { stash.v = "lie"; }
function victim(b: Box): string {
  const before = b.v + 1;
  poison();                 // b is NEVER passed anywhere
  return "before=" + before + " after=" + (b.v + 1);
}

b never appears in an argument list, so an escape analysis structurally cannot see it, yet the
callee reaches the same object through the global the caller stashed it in first. So the rule is
keyed on "did unknown code run", not "did the reference escape":

guard_blocked[i] = body_contains_call(&f.body) && is_reference_like(&aliases, &p.ty, 0)

Primitive parameters stay eligible — a callee has no route to the caller's copy of a number or a
string — and that is why most of the win survives.

Post-fix instruction recovery vs 601a02d23, all stdout byte-exact against expected/, exit 0:

bench	post-fix	previously published	delta
pipeline	93.0%	92.9%	+0.1
asyncpipe	92.4%	92.0%	+0.4
retain_wide	85.6%	86.6%	−1.0
shapes	75.2%	74.9%	+0.3
interp	75.6%	80.3%	−4.7
iso_miss	74.8%	78.8%	−4.0
tree	55.1%	55.1%	0.0

The cost lands exactly where the mechanism predicts — interp and iso_miss are the two programs
whose hot parameters are object-typed (Parser, Env, Value) and passed into call-bearing
bodies. Everything else is within noise.

Three regression rows are in test_gap_specabi_ordinary_param_guards.ts covering the
passed-reference, array-element and never-passed shapes, sabotage-verified green → red → green
with a real rebuild each way. Details, including a gate that had quietly stopped testing anything
and how it was restored, are in the PR.

Still open before this closes: the gap suite and the full cargo test runs, which I stopped
rather than run on a box that was down to 8.8 GiB of disk. The class-typed-parameter gap behind
the tree row is split out as #8099.