perf: ECS command path round 3 — field-push inline append, inline f64 typed guard, header-gated registry probes (+5.4%)

changelog.d/8897-ecs-round3-field-push-inline-append.md

@@ -0,0 +1,9 @@
+Four more general mechanisms on the ECS command path (round 3 after #8885):
+`this.field.push(v)` statements bind their receiver to a local so the push
+takes the inline append instead of the runtime push (and the tiny-method
+allocation kernel rule sees through that expansion); the f64 typed-argument
+guard and unbox are inlined at every typed dispatch; the array iteration
+helpers probe the typed-array/Buffer registries only for a non-array header.
+On the upstream `codehz/ecs` "5k entities: 3 commands each + sync" row the
+compiled benchmark went from 4.38 ms/op to 4.15 ms/op (−5.4%, paired runs on
+an idle Mac mini; Node 26.5.1 is 1.76 ms/op).

crates/perry-codegen/src/codegen/mod.rs

@@ -250,8 +250,9 @@ pub(crate) use opts::{CrossModuleCtx, ImportedCtor};
 pub(crate) use param_guard::scalar_descriptor_rep;
 pub(crate) use spec_abi::{spec_abi_enabled, spec_function_name, SpecDispatch, SpecFnPlan};
 pub(crate) use typed_abi::{
-    emit_typed_arg_guard, emit_typed_arg_to_raw, generic_closure_body_name,
-    generic_function_body_name, generic_method_body_name, nonnegative_index_fast_array_method_name,
+    emit_typed_arg_guard, emit_typed_arg_to_raw, emit_typed_f64_guard,
+    emit_typed_f64_to_raw_guarded, generic_closure_body_name, generic_function_body_name,
+    generic_method_body_name, nonnegative_index_fast_array_method_name,
     nonnegative_index_fast_array_params, nonnegative_index_method_name,
     typed_arg_is_guard_candidate, typed_f64_closure_name, typed_f64_function_name,
     typed_f64_method_name, typed_f64_receiver_method_info, typed_f64_receiver_method_name,

crates/perry-codegen/src/codegen/ordinary_param_guard_tests.rs

@@ -672,10 +672,11 @@ fn nonsuspending_async_function_needs_no_direct_call_site_for_its_guarded_clone(
             .count(),
         1
     );
-    assert_eq!(
-        public.matches("call i32 @js_typed_f64_arg_guard(").count(),
-        1
-    );
+    // The Number leg is the inline `is_number || is_int32` predicate now
+    // (`emit_typed_f64_guard`): one band test against the Perry tag range,
+    // no runtime call.
+    assert!(!public.contains("call i32 @js_typed_f64_arg_guard("));
+    assert_eq!(public.matches(", 32761").count(), 1, "{public}");
     assert!(public.contains("$spec_b_b("));
     assert!(public.contains("$generic("));
     let specialized = function_ir(&ir, "renderAsync$spec_b_b(");

crates/perry-codegen/src/codegen/spec_self_recursion_tests.rs

@@ -339,7 +339,10 @@ fn derived_recursive_number_argument_re_enters_the_guarded_clone() {
 
     // Keep both halves of the subject live: this must be the ordinary boxed
     // clone selected by the public Number guard, not the raw-i32 Tier-A path.
-    assert!(public.contains("call i32 @js_typed_f64_arg_guard("));
+    assert!(
+        public.contains(", 32761") && !public.contains("call i32 @js_typed_f64_arg_guard("),
+        "the public Number guard is the inline band test:\n{public}"
+    );
     assert!(
         clone.starts_with("define internal")
             && clone.contains("double @perry_fn_spec_self_recursion_ts__f$spec_b(double"),
@@ -376,7 +379,10 @@ fn bigint_capable_recursive_argument_keeps_the_public_guard() {
     let public = function_ir(&ir, "@perry_fn_spec_self_recursion_bigint_ts__f(");
     let clone = function_ir(&ir, "$spec_b_b(");
 
-    assert!(public.contains("call i32 @js_typed_f64_arg_guard("));
+    assert!(
+        public.contains(", 32761") && !public.contains("call i32 @js_typed_f64_arg_guard("),
+        "the public Number guard is the inline band test:\n{public}"
+    );
     assert!(
         clone.starts_with("define internal")
             && clone.contains("double @perry_fn_spec_self_recursion_bigint_ts__f$spec_b_b(double"),

crates/perry-codegen/src/codegen/typed_abi.rs

@@ -242,6 +242,9 @@ pub(crate) fn emit_typed_arg_guard(
     rep: TypedParamRep,
     arg: &str,
 ) -> String {
+    if rep == TypedParamRep::F64 {
+        return emit_typed_f64_guard(blk, arg);
+    }
     let raw = blk.call(
         crate::types::I32,
         rep.guard_fn(),
@@ -250,17 +253,53 @@ pub(crate) fn emit_typed_arg_guard(
     blk.icmp_ne(crate::types::I32, &raw, "0")
 }
 
+/// Inline the exact contract of runtime `js_typed_f64_arg_guard`
+/// (`JSValue::is_number || JSValue::is_int32`), the way
+/// [`emit_typed_i32_guard_and_raw`] already does for the i32 lane.
+///
+/// The public entry of every function with a boxed-double clone runs this
+/// guard on each numeric parameter before dispatching; a one-line predicate
+/// such as an ECS `isComponentId(id)` paid a cross-crate call per invocation
+/// for a compare it could have done in four instructions. Same predicate,
+/// same routing decision.
+pub(crate) fn emit_typed_f64_guard(blk: &mut crate::block::LlBlock, arg: &str) -> String {
+    use crate::types::{I1, I64};
+    let bits = blk.bitcast_double_to_i64(arg);
+    // JSValue::is_number: Perry-owned tags occupy the positive-qNaN top words
+    // 0x7ff9..=0x7fff; everything outside that band is a Number.
+    let top16 = blk.lshr(I64, &bits, "48");
+    let below_tag_band = blk.icmp_ult(I64, &top16, crate::nanbox::SHORT_STRING_TAG_TOP16_I64);
+    let above_tag_band = blk.icmp_ugt(I64, &top16, crate::nanbox::STRING_TAG_TOP16_I64);
+    let is_plain_number = blk.or(I1, &below_tag_band, &above_tag_band);
+    // JSValue::is_int32: the INT32 tag with any payload.
+    let int32_identity_mask = crate::nanbox::i64_literal(!crate::nanbox::INT32_MASK);
+    let tagged_identity = blk.and(I64, &bits, &int32_identity_mask);
+    let is_int32 = blk.icmp_eq(I64, &tagged_identity, crate::nanbox::INT32_TAG_I64);
+    blk.or(I1, &is_plain_number, &is_int32)
+}
+
+/// Inline `js_typed_f64_arg_to_raw` for a value the F64 guard admitted: an
+/// INT32-tagged value converts its low lane, anything else is already the
+/// double the clone wants. Only valid after [`emit_typed_f64_guard`] passed
+/// (a tagged non-number would otherwise reach the clone as its raw bits).
+pub(crate) fn emit_typed_f64_to_raw_guarded(blk: &mut crate::block::LlBlock, arg: &str) -> String {
+    use crate::types::{DOUBLE, I1, I32, I64};
+    let bits = blk.bitcast_double_to_i64(arg);
+    let int32_identity_mask = crate::nanbox::i64_literal(!crate::nanbox::INT32_MASK);
+    let tagged_identity = blk.and(I64, &bits, &int32_identity_mask);
+    let is_int32 = blk.icmp_eq(I64, &tagged_identity, crate::nanbox::INT32_TAG_I64);
+    let low = blk.trunc(I64, &bits, I32);
+    let converted = blk.sitofp(I32, &low, DOUBLE);
+    blk.select(I1, &is_int32, DOUBLE, &converted, arg)
+}
+
 pub(crate) fn emit_typed_arg_to_raw(
     blk: &mut crate::block::LlBlock,
     rep: TypedParamRep,
     arg: &str,
 ) -> String {
     match rep {
-        TypedParamRep::F64 => blk.call(
-            crate::types::DOUBLE,
-            rep.unbox_fn(),
-            &[(crate::types::DOUBLE, arg)],
-        ),
+        TypedParamRep::F64 => emit_typed_f64_to_raw_guarded(blk, arg),
         TypedParamRep::I32 => blk.call(
             crate::types::I32,
             rep.unbox_fn(),

crates/perry-codegen/src/collectors/hot_callees.rs

@@ -64,6 +64,29 @@ const INDIRECT_CLOSURE_ALLOC_SITE_BUDGET: u32 = 8;
 const TINY_METHOD_MAX_STMTS: usize = 2;
 const TINY_METHOD_ALLOC_SITE_BUDGET: u32 = 8;
 
+/// The receiver-binding local `perry-transform`'s `field_push_local_bind`
+/// pass introduces when it expands one `this.f.push(v)` statement into four
+/// (`let __push_recv_old = this.f; let __push_recv = old; push; if (moved)
+/// this.f = __push_recv`). For the tiny-method budget above that is still the
+/// ONE statement the author wrote: the pass exists so the push takes the
+/// inline append, and a command-buffer method that is exactly
+/// `this.commands.push({ ... })` must not lose its allocation kernel to the
+/// rewrite that made its push cheaper. Kept in sync by name with the pass
+/// (`field_push_local_bind.rs`); the test below pins the shape.
+const FIELD_PUSH_RECEIVER_OLD_NAME: &str = "__push_recv_old";
+
+/// Statement count for the tiny-method rule: each field-push expansion
+/// counts as the single statement it came from.
+fn tiny_method_stmt_count(body: &[Stmt]) -> usize {
+    let expansions = body
+        .iter()
+        .filter(
+            |stmt| matches!(stmt, Stmt::Let { name, .. } if name == FIELD_PUSH_RECEIVER_OLD_NAME),
+        )
+        .count();
+    body.len().saturating_sub(3 * expansions)
+}
+
 /// Collect the set of `FuncId`s eligible for `inlinehint`: those with ≥1 direct
 /// call site inside a loop AND at most `max_call_sites` total direct call sites
 /// across the whole module (`init` + every function + every executable
@@ -245,7 +268,7 @@ pub fn collect_alloc_hot_functions(hir: &Module) -> HashSet<u32> {
     let mut tiny_method_sites: HashMap<u32, u32> = HashMap::new();
     for class in &hir.classes {
         for method in &class.methods {
-            if method.body.len() > TINY_METHOD_MAX_STMTS {
+            if tiny_method_stmt_count(&method.body) > TINY_METHOD_MAX_STMTS {
                 continue;
             }
             // Count into a scratch map because the ownership-aware walker also
@@ -832,6 +855,123 @@ mod recursion_participant_tests {
         }))
     }
 
+    fn new_expr() -> Expr {
+        Expr::New {
+            class_name: "Command".to_string(),
+            args: Vec::new(),
+            cap_args_appended: 0,
+            type_args: Vec::new(),
+            byte_offset: 0,
+        }
+    }
+
+    /// `this.commands.push({ ... })` after `field_push_local_bind` expanded it.
+    fn expanded_field_push(old_id: u32, recv_id: u32) -> Vec<Stmt> {
+        vec![
+            Stmt::Let {
+                id: old_id,
+                name: FIELD_PUSH_RECEIVER_OLD_NAME.to_string(),
+                ty: Type::Any,
+                mutable: false,
+                init: Some(Expr::PropertyGet {
+                    object: Box::new(Expr::This),
+                    property: "commands".to_string(),
+                    byte_offset: 0,
+                }),
+            },
+            Stmt::Let {
+                id: recv_id,
+                name: "__push_recv".to_string(),
+                ty: Type::Any,
+                mutable: true,
+                init: Some(Expr::LocalGet(old_id)),
+            },
+            Stmt::Expr(Expr::ArrayPush {
+                array_id: recv_id,
+                value: Box::new(new_expr()),
+            }),
+            Stmt::If {
+                condition: Expr::Compare {
+                    op: perry_hir::CompareOp::Ne,
+                    left: Box::new(Expr::LocalGet(recv_id)),
+                    right: Box::new(Expr::LocalGet(old_id)),
+                },
+                then_branch: vec![Stmt::Expr(Expr::PropertySet {
+                    object: Box::new(Expr::This),
+                    property: "commands".to_string(),
+                    value: Box::new(Expr::LocalGet(recv_id)),
+                })],
+                else_branch: None,
+            },
+        ]
+    }
+
+    fn class_with_method(method: Function) -> perry_hir::Class {
+        perry_hir::Class {
+            id: 1,
+            name: "CommandBuffer".to_string(),
+            type_params: Vec::new(),
+            extends: None,
+            extends_name: None,
+            native_extends: None,
+            extends_expr: None,
+            heritage_lexically_shadowed: false,
+            fields: Vec::new(),
+            constructor: None,
+            methods: vec![method],
+            getters: Vec::new(),
+            setters: Vec::new(),
+            static_accessor_names: Vec::new(),
+            static_accessor_fn_ids: Vec::new(),
+            computed_members: Vec::new(),
+            static_fields: Vec::new(),
+            static_methods: Vec::new(),
+            decorators: Vec::new(),
+            is_exported: false,
+            aliases: Vec::new(),
+            is_nested: false,
+            alloc_width_hint: 0,
+            specialized_from: None,
+        }
+    }
+
+    /// Rule 4 must see through `field_push_local_bind`'s expansion: a method
+    /// that was `this.commands.push({ ... })` is still a tiny allocation
+    /// kernel after the pass rewrote its push, while four genuinely separate
+    /// statements still exceed the budget.
+    #[test]
+    fn tiny_method_rule_counts_a_field_push_expansion_as_one_statement() {
+        let mut module = Module::new("buffer.ts");
+        module
+            .classes
+            .push(class_with_method(func(11, expanded_field_push(100, 101))));
+        let mut plain = expanded_field_push(200, 201);
+        // Same four statements, but the first is an ordinary local: not an
+        // expansion, so the method is four statements long.
+        if let Stmt::Let { name, .. } = &mut plain[0] {
+            *name = "old".to_string();
+        }
+        module.classes.push(class_with_method(func(12, plain)));
+
+        assert_eq!(
+            tiny_method_stmt_count(&module.classes[0].methods[0].body),
+            1
+        );
+        assert_eq!(
+            tiny_method_stmt_count(&module.classes[1].methods[0].body),
+            4
+        );
+        let hot = collect_alloc_hot_functions(&module);
+        assert!(
+            hot.contains(&11),
+            "the expanded field push is still a tiny kernel: {hot:?}"
+        );
+        assert!(
+            !hot.contains(&12),
+            "four unrelated statements are not: {hot:?}"
+        );
+    }
+
     #[test]
     fn self_call_cycle_pair_and_acyclic_chain_are_classified() {
         let mut module = Module::new("recursion.ts");

crates/perry-codegen/src/lower_call/early_branches.rs

@@ -967,10 +967,11 @@ pub fn try_lower_closure_typed_local_call(
                             crate::codegen::generic_closure_body_name(&closure_fn);
                         let mut typed_guard: Option<String> = None;
                         for (value, rep) in lowered_args.iter().zip(typed_param_reps.iter()) {
-                            let raw =
-                                ctx.block()
-                                    .call(I32, rep.guard_fn(), &[(DOUBLE, value.as_str())]);
-                            let ok = ctx.block().icmp_ne(I32, &raw, "0");
+                            let ok = crate::codegen::emit_typed_arg_guard(
+                                ctx.block(),
+                                *rep,
+                                value.as_str(),
+                            );
                             typed_guard = Some(match typed_guard {
                                 Some(prev) => ctx.block().and(I1, &prev, &ok),
                                 None => ok,
@@ -1005,11 +1006,13 @@ pub fn try_lower_closure_typed_local_call(
                             Vec::with_capacity(lowered_args.len());
                         for (value, rep) in lowered_args.iter().zip(typed_param_reps.iter()) {
                             typed_args_storage.push(match rep {
-                                crate::codegen::TypedParamRep::F64 => ctx.block().call(
-                                    DOUBLE,
-                                    rep.unbox_fn(),
-                                    &[(DOUBLE, value.as_str())],
-                                ),
+                                crate::codegen::TypedParamRep::F64 => {
+                                    crate::codegen::emit_typed_arg_to_raw(
+                                        ctx.block(),
+                                        *rep,
+                                        value.as_str(),
+                                    )
+                                }
                                 crate::codegen::TypedParamRep::I32 => ctx.block().call(
                                     I32,
                                     rep.unbox_fn(),

crates/perry-codegen/src/lower_call/func_ref.rs

@@ -1336,10 +1336,7 @@ pub fn try_lower_func_ref_call(
         let generic_body_name = crate::codegen::generic_function_body_name(&fname);
         let mut guard: Option<String> = None;
         for (value, rep) in lowered.iter().zip(typed_i1_param_reps.iter()) {
-            let raw = ctx
-                .block()
-                .call(I32, rep.guard_fn(), &[(DOUBLE, value.as_str())]);
-            let ok = ctx.block().icmp_ne(I32, &raw, "0");
+            let ok = crate::codegen::emit_typed_arg_guard(ctx.block(), *rep, value.as_str());
             guard = Some(match guard {
                 Some(prev) => ctx.block().and(I1, &prev, &ok),
                 None => ok,
@@ -1362,8 +1359,7 @@ pub fn try_lower_func_ref_call(
         for (value, rep) in lowered.iter().zip(typed_i1_param_reps.iter()) {
             typed_args_storage.push(match rep {
                 crate::codegen::TypedParamRep::F64 => {
-                    ctx.block()
-                        .call(DOUBLE, rep.unbox_fn(), &[(DOUBLE, value.as_str())])
+                    crate::codegen::emit_typed_arg_to_raw(ctx.block(), *rep, value.as_str())
                 }
                 crate::codegen::TypedParamRep::I32 => {
                     ctx.block()

crates/perry-codegen/src/lower_call/method_override.rs

@@ -1273,8 +1273,7 @@ pub(super) fn emit_guarded_direct_method_call(
                 .collect();
             let mut guard: Option<String> = None;
             for (value, rep) in formal_args.iter().zip(typed_param_reps.iter()) {
-                let raw = ctx.block().call(I32, rep.guard_fn(), &[(DOUBLE, *value)]);
-                let ok = ctx.block().icmp_ne(I32, &raw, "0");
+                let ok = crate::codegen::emit_typed_arg_guard(ctx.block(), *rep, value);
                 guard = Some(match guard {
                     Some(prev) => ctx.block().and(I1, &prev, &ok),
                     None => ok,
@@ -1298,8 +1297,7 @@ pub(super) fn emit_guarded_direct_method_call(
             for (value, rep) in formal_args.iter().zip(typed_param_reps.iter()) {
                 typed_args_storage.push(match rep {
                     crate::codegen::TypedParamRep::F64 => {
-                        ctx.block()
-                            .call(DOUBLE, rep.unbox_fn(), &[(DOUBLE, *value)])
+                        crate::codegen::emit_typed_arg_to_raw(ctx.block(), *rep, value)
                     }
                     crate::codegen::TypedParamRep::I32 => {
                         ctx.block().call(I32, rep.unbox_fn(), &[(DOUBLE, *value)])

crates/perry-codegen/src/lower_call/scalar_method.rs

@@ -1145,10 +1145,7 @@ pub(super) fn try_lower_scalar_replaced_method_call(
     let guard_values = collect_guard_local_values(ctx, &arg_plans)?;
     let mut guard: Option<String> = None;
     for (_, value) in &guard_values {
-        let raw = ctx
-            .block()
-            .call(I32, "js_typed_f64_arg_guard", &[(DOUBLE, value.as_str())]);
-        let ok = ctx.block().icmp_ne(I32, &raw, "0");
+        let ok = crate::codegen::emit_typed_f64_guard(ctx.block(), value.as_str());
         guard = Some(match guard {
             Some(prev) => ctx.block().and(I1, &prev, &ok),
             None => ok,
@@ -1172,11 +1169,7 @@ pub(super) fn try_lower_scalar_replaced_method_call(
     for (id, value) in &guard_values {
         raw_locals.insert(
             *id,
-            ctx.block().call(
-                DOUBLE,
-                "js_typed_f64_arg_to_raw",
-                &[(DOUBLE, value.as_str())],
-            ),
+            crate::codegen::emit_typed_f64_to_raw_guarded(ctx.block(), value.as_str()),
         );
     }
     let mut fast_args = Vec::with_capacity(args.len());