perf(codegen): specialize imported methods capturing this

benchmarks/compiler_output/workloads.toml

@@ -2076,6 +2076,7 @@ allowed_hot_loop_runtime_calls = [
   "js_for_in_keys_stable_value",
   "js_gc_loop_safepoint",
   "js_in_operator",
+  "js_value_typeof",
 ]
 
 [workloads.for_in_stable_keys.vectorization]
@@ -2092,6 +2093,8 @@ allowed_missed_reason_kinds = [
   "unsupported_reduction",
 ]
 
+[workloads.for_in_stable_keys.runtime_budgets]
+
 [[workloads.for_in_stable_keys.stdout_checks]]
 name = "for_in_stable_keys_checksum"
 equals = "for_in_stable_keys:200000\n"
@@ -2114,3 +2117,40 @@ regex_none = [
   "call i64 @js_object_get_own_property_names",
 ]
 detail = "the stable arm does not directly allocate or rebuild generic key lists"
+
+[workloads.issue_8693_imported_this]
+source = "test-files/fixtures/issue_8693_imported_this/main.js"
+kind = "imported_class_method_specialization"
+allow_hot_loop_conversions = true
+allow_dynamic_property_runtime = true
+
+[workloads.issue_8693_imported_this.vectorization]
+min_vectorized_loops = 0
+scalar_baseline = "allowed: this fixture gates cross-module method dispatch, not loop vectorization"
+allowed_missed_reason_kinds = [
+  "call_instruction",
+  "control_flow",
+  "generic_not_vectorized",
+  "not_beneficial",
+  "uncountable_loop",
+  "unknown_trip_count",
+  "unsupported_instruction",
+  "unsupported_reduction",
+]
+
+[workloads.issue_8693_imported_this.runtime_budgets]
+
+[workloads.issue_8693_imported_this.native_rep_checks]
+allow_materialization_reasons = ["runtime_api"]
+
+[[workloads.issue_8693_imported_this.native_rep_checks.require_records]]
+name = "imported_registry_proven_this_selection"
+consumer = "proven_this_method_direct_call"
+notes_contains = "receiver_provenance=imported_class_metadata"
+min = 2
+
+[[workloads.issue_8693_imported_this.native_rep_checks.require_records]]
+name = "imported_registry_generic_fallback_retained"
+consumer = "proven_this_method_direct_call"
+notes_contains = "generic_dispatch_fallback=js_native_call_method_by_id"
+min = 2

changelog.d/8693-imported-this-specialization.md

@@ -0,0 +1,9 @@
+---
+category: Performance
+title: Specialize imported methods that capture this
+---
+
+ESM import and re-export metadata now carries producer-proven method
+eligibility, allowing guarded direct calls into stable class methods that use
+`this`. Generic dispatch remains available for shadowed or mutated receivers,
+including prototype replacement, deletion, and recreation.

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

@@ -339,6 +339,25 @@ pub(super) fn inline_hot_small_size_cap() -> usize {
     })
 }
 
+/// Give the representation-specialized method body the ordinary small-body
+/// inline bias. This lets producer-local chains such as `Registry.add ->
+/// Group.pushEntity` optimize through the second method boundary while the
+/// externally linked clone remains callable by importers.
+pub(super) fn apply_pshape_inline_policy(
+    lf: &mut crate::function::LlFunction,
+    method: &perry_hir::Function,
+    is_pshape_clone: bool,
+) {
+    if !is_pshape_clone || method.is_async || method.is_generator || method.was_plain_async {
+        return;
+    }
+    if method.body.len() <= 8 {
+        lf.force_inline = true;
+    } else if inline_hot_small_enabled() && method.body.len() <= inline_hot_small_size_cap() {
+        lf.inline_hint = true;
+    }
+}
+
 /// Maximum total (module-wide) direct call sites a function may have and still
 /// be hinted. This is the anti-bloat backstop: the raised `-inlinehint-threshold`
 /// lifts LLVM's ceiling for a hinted callee at *every* one of its call sites, so

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

@@ -306,10 +306,18 @@ pub(super) fn compile_method(
     let ic_base = llmod.ic_counter;
     let buffer_alias_base = llmod.buffer_alias_counter;
     let lf = llmod.define_function(&llvm_name, DOUBLE, params);
-    if is_pshape_clone || is_index_clone || typed_public_trampoline.is_some() || force_generic_body
+    // Plain `$pshape` clones are producer-published capabilities and need
+    // external linkage for guarded calls from importing modules. The stricter
+    // array-cache clone remains module-local: only containment-proven locals
+    // in this module may select it.
+    if ptr_array_cache_clone
+        || is_index_clone
+        || typed_public_trampoline.is_some()
+        || force_generic_body
     {
         lf.linkage = "internal".to_string();
     }
+    super::helpers::apply_pshape_inline_policy(lf, method, is_pshape_clone);
     if is_index_clone {
         lf.pre_statepoint_inline = true;
     }

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

@@ -216,6 +216,10 @@ pub(crate) fn build_method_names(
             let param_types: Vec<crate::types::LlvmType> =
                 std::iter::repeat_n(DOUBLE, arity).collect();
             llmod.declare_function(&llvm_fn, DOUBLE, &param_types);
+            if ic.proven_this_method_names.contains(method_name) {
+                let clone = crate::collectors::pshape_method_name(&llvm_fn);
+                llmod.declare_function(&clone, DOUBLE, &param_types);
+            }
         }
 
         // Cross-module getters. The dispatch site at

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

@@ -1808,17 +1808,6 @@ pub fn compile_module(hir: &HirModule, opts: CompileOptions) -> Result<Vec<u8>>
                 receiver_class_table,
                 &module_dispatch_facts,
             ) {
-                // #7142: the tower routing site emits its own inline shape
-                // re-check, so it only takes the clone where the clone deletes
-                // strictly more guarded field sites than that check costs. The
-                // other two sites are guard-dominated and route unconditionally.
-                if crate::collectors::pshape_tower_route_profitable(
-                    class,
-                    method,
-                    receiver_class_table,
-                ) {
-                    pshape_tower_routable.insert((class.name.clone(), method.name.clone()));
-                }
                 pshape_methods.insert((class.name.clone(), method.name.clone()), fact);
             }
             match typed_abi::typed_f64_method_rejection_reason(method) {
@@ -1933,6 +1922,60 @@ pub fn compile_module(hir: &HirModule, opts: CompileOptions) -> Result<Vec<u8>>
             }
         }
     }
+    // #7142: the tower routing site emits its own inline shape re-check, so it
+    // only takes a clone where that clone deletes strictly more guarded work
+    // than the check costs. Price these routes after all local clone facts are
+    // known so nested `this.other()` calls can count an inherited clone too.
+    let local_pshape_methods: std::collections::HashSet<(String, String)> =
+        pshape_methods.keys().cloned().collect();
+    for class in &hir.classes {
+        for method in &class.methods {
+            let key = (class.name.clone(), method.name.clone());
+            if local_pshape_methods.contains(&key)
+                && crate::collectors::pshape_tower_route_profitable(
+                    class,
+                    method,
+                    receiver_class_table,
+                    &local_pshape_methods,
+                )
+            {
+                pshape_tower_routable.insert(key);
+            }
+        }
+    }
+    // Imported classes publish only clone names the defining module proved and
+    // emitted. Installing those capabilities in the same registries lets both
+    // the ordinary exact-class/shape guarded arm and profitable adapter-field
+    // dispatch towers retain the receiver proof across ESM and npm boundaries.
+    // The tower subset is producer-authored because only the defining module
+    // can see enough of the body to price its additional keys-token check.
+    for imported in &opts.imported_classes {
+        let effective_name = imported
+            .local_alias
+            .as_deref()
+            .unwrap_or(&imported.name)
+            .to_string();
+        if hir.classes.iter().any(|class| class.name == effective_name) {
+            continue;
+        }
+        for method in &imported.proven_this_method_names {
+            if !imported.method_names.contains(method) {
+                continue;
+            }
+            pshape_methods.insert(
+                (effective_name.clone(), method.clone()),
+                crate::collectors::PtrShapeLocal {
+                    class_name: effective_name.clone(),
+                    numeric_fields: std::collections::HashSet::new(),
+                    report_name: crate::opt_report::enabled()
+                        .then(|| format!("imported:{}", imported.source_prefix)),
+                },
+            );
+            if imported.proven_this_tower_method_names.contains(method) {
+                pshape_tower_routable.insert((effective_name.clone(), method.clone()));
+            }
+        }
+    }
     let mut compiler_private_async_i32_control_locals = std::collections::HashSet::new();
     let mut compiler_private_async_i1_control_locals = std::collections::HashSet::new();
     crate::boxed_vars::collect_compiler_private_async_control_locals_in_stmts(

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

@@ -510,6 +510,16 @@ pub struct ImportedClass {
     pub has_instance_fields: bool,
     /// Method names defined on this class.
     pub method_names: Vec<String>,
+    /// Own methods for which the defining module emitted an externally
+    /// callable, guarded proven-`this` clone. Consumers may reference only
+    /// names in this producer-authored capability set; absence is fail-closed
+    /// and keeps the public method body on the direct arm.
+    pub proven_this_method_names: Vec<String>,
+    /// Subset of `proven_this_method_names` for which the producer also proved
+    /// that the extra exact-keys check paid by a class-id dispatch-tower arm is
+    /// profitable. This keeps adapter-field calls fail-closed without asking
+    /// an importer that cannot see the method body to repeat the decision.
+    pub proven_this_tower_method_names: Vec<String>,
     /// Declared return types parallel to `method_names`. Imported class stubs
     /// retain these so a call such as `factory.make().run()` can recover the
     /// returned receiver class without value-importing that class directly.
@@ -911,12 +921,11 @@ pub(crate) struct CrossModuleCtx {
     /// exported.
     pub nonnegative_index_methods: std::collections::HashMap<(String, String), Vec<u32>>,
     /// Representation-selection Phase 5a: `(class, method)` pairs that have a
-    /// generated `internal` proven-`this` clone
-    /// (`collectors/proven_this.rs`). Keys are OWN declarations of
-    /// module-local classes only, which is precisely the condition the two
-    /// routing sites rely on: a hit means the receiver's proven exact class is
-    /// the class the clone was compiled for, so `this` cannot be a subclass
-    /// instance with a different chain.
+    /// generated proven-`this` clone (`collectors/proven_this.rs`). Local keys
+    /// come from body analysis; imported keys come from an explicit capability
+    /// published by the defining module. Both represent OWN declarations, so a
+    /// hit means the receiver's proven exact class is the class the clone was
+    /// compiled for and `this` cannot have a different subclass chain.
     pub pshape_methods:
         std::collections::HashMap<(String, String), crate::collectors::PtrShapeLocal>,
     /// #7142: the subset of [`Self::pshape_methods`] whose clone the class-id

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

@@ -87,6 +87,7 @@ pub(crate) use number_by_construction::collect_number_by_construction_locals;
 pub(crate) use param_ranges::{collect_param_int_ranges, ParamIntRanges};
 pub(crate) use pointer_locals::collect_pointer_typed_locals;
 pub(crate) use proven_this::{
+    exportable_method_capabilities as exportable_proven_this_method_capabilities,
     method_proven_this, prune_unregistered_clones, pshape_method_name, ptr_array_cache_fields,
     ptr_array_cache_method_name, ptr_array_cached_method,
     tower_route_profitable as pshape_tower_route_profitable,

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

@@ -15,7 +15,7 @@
 //! 2. `lower_call/property_get/dynamic_dispatch.rs` — the Phase 3b guard-free
 //!    `Ptr<Shape>` receiver arm, whose receiver is a shape-proven local.
 //!
-//! Phase 5a emits an `internal` `{public}$pshape` clone of the method whose
+//! Phase 5a emits a `{public}$pshape` clone of the method whose
 //! `this` carries the [`PtrShapeLocal`] proof, and routes those two sites to
 //! it. Net new proof work: zero. Net new GC work: zero — the clone keeps the
 //! identical `(double this, double args…)` ABI and the identical shadow-bound
@@ -148,9 +148,10 @@ pub fn ptr_shape_this_enabled() -> bool {
 /// composed-symbol collision prune here.)
 ///
 /// This symbol is NEVER registered into a runtime vtable
-/// (`js_register_class_method` keeps the public name) and is reachable only
-/// from the proven call sites. [`tests::pshape_symbol_reachability`]
-/// ratchets that.
+/// (`js_register_class_method` keeps the public name). It is externally
+/// visible solely so an importing native module can use it after receiving a
+/// producer-authored capability; every call remains one of the proven direct
+/// sites. [`tests::pshape_symbol_reachability`] ratchets that.
 pub(crate) fn pshape_method_name(public_name: &str) -> String {
     format!("{public_name}$pshape")
 }
@@ -602,6 +603,60 @@ pub(crate) fn method_proven_this(
     })
 }
 
+/// Producer-side capabilities that may be published to native-module
+/// consumers.
+///
+/// This deliberately uses only classes defined in `hir`. A class whose parent
+/// is imported therefore stays out of the published set even when the full
+/// compile options later make its chain resolvable. Under-publishing only
+/// leaves a guarded call on the public body; over-publishing could make a
+/// consumer reference a clone the producer did not emit.
+pub(crate) fn exportable_method_capabilities(
+    hir: &perry_hir::Module,
+) -> (HashMap<String, Vec<String>>, HashMap<String, Vec<String>>) {
+    let classes: HashMap<String, &Class> = hir
+        .classes
+        .iter()
+        .map(|class| (class.name.clone(), class))
+        .collect();
+    let module_dispatch = super::collect_module_dispatch_facts(hir);
+    let mut exported = HashMap::new();
+    let mut tower_routable = HashMap::new();
+    let mut eligible = HashSet::new();
+
+    for class in &hir.classes {
+        let mut methods = Vec::new();
+        for method in &class.methods {
+            if method_proven_this(class, method, &classes, &module_dispatch).is_none() {
+                continue;
+            }
+            methods.push(method.name.clone());
+            eligible.insert((class.name.clone(), method.name.clone()));
+        }
+        if !methods.is_empty() {
+            exported.insert(class.name.clone(), methods);
+        }
+    }
+
+    // Price tower routes only after every clone capability is known: a clone
+    // can delete the public guard at a nested `this.other()` boundary too,
+    // including when `other` is inherited from another class in the chain.
+    for class in &hir.classes {
+        let tower_methods: Vec<String> = class
+            .methods
+            .iter()
+            .filter(|method| eligible.contains(&(class.name.clone(), method.name.clone())))
+            .filter(|method| tower_route_profitable(class, method, &classes, &eligible))
+            .map(|method| method.name.clone())
+            .collect();
+        if !tower_methods.is_empty() {
+            tower_routable.insert(class.name.clone(), tower_methods);
+        }
+    }
+
+    (exported, tower_routable)
+}
+
 /// #7142 profitability: should a class-id dispatch-tower case route to
 /// `method`'s `{public}$pshape` clone?
 ///
@@ -617,13 +672,18 @@ pub(crate) fn tower_route_profitable(
     class: &Class,
     method: &Function,
     classes: &HashMap<String, &Class>,
+    eligible: &HashSet<(String, String)>,
 ) -> bool {
     let chain = chain_classes(classes, &class.name);
     if chain.is_empty() {
         return false;
     }
     let fields = chain_field_names(&chain);
-    super::repsel_benefit::tower_route_profitable(method, &fields)
+    let pshape_methods = chain_method_map(&chain)
+        .into_iter()
+        .filter_map(|(name, (owner, _))| eligible.contains(&(owner, name.clone())).then_some(name))
+        .collect();
+    super::repsel_benefit::tower_route_profitable(method, &fields, &pshape_methods)
 }
 
 /// Does the method body READ `this.<declared chain field>` anywhere?
@@ -777,7 +837,7 @@ mod tests {
         assert!(
             offenders.is_empty(),
             "proven-`this` clone symbol fragments found outside the allowlist \
-             (the clone is `internal` and must NEVER be registered into a \
+             (the clone must NEVER be registered into a \
              runtime vtable or reached indirectly): {offenders:?}"
         );
     }