GeezerVison

Builds on the Node-API surface from #2004 (now merged); rebased onto main, so the diff here is only the fast-call extension.

What

Lets a plugin's hot leaf functions be called from optimized JS with unboxed arguments — V8's fast API calls — without the addon writing any V8 code. A normal Node-API call crosses through FunctionCallbackInfo, a handle scope and boxed arguments; a fast call is a direct C call from TurboFan-generated code.

Design follows the brainstorm notes in ns-v8ios-runtime/NAPI_FAST_CALLS.md (deviations listed below).

This is an explicitly unstable vendor extension. Upstream Node-API declined to expose fast calls (closed not planned): Node-API's contract says a callback may call napi_*, and a fast callback may not — there is no safe general subset, so any support is an embedder extension by definition.

Gating

Three layers, answering different questions:

Surface

#define NODE_API_NS_EXPERIMENTAL_FAST_CALLS
#include <node_api_ns_fast.h>

static int32_t FastAdd(ns_fast_receiver recv, int32_t a, int32_t b) { return a + b; }
static napi_value SlowAdd(napi_env env, napi_callback_info info) { /* identical */ }

ns_fast_descriptor d = {0};
d.slow_cb = SlowAdd;
d.fast_fn = (const void*)FastAdd;
d.return_type.type = ns_fast_int32;
d.argc = 2;
d.arg_types = params;   // {ns_fast_int32}, {ns_fast_int32}
node_api_ns_create_fast_function(env, "add", NAPI_AUTO_LENGTH, &d, &add);

• The descriptor vocabulary is ours (ns_fast_type, ns_fast_param, flags). No V8 type ever reaches plugin source, so V8's churn — which has broken embedders twice already (the receiver parameter, the fallback field) — stays inside the runtime.
• Receiver is the first parameter from day one, opaque, even if v1 addons ignore it — exactly the change that broke Deno (denoland/deno#15139).
• fast_fn == NULL returns a plain Node-API function with zero wrapper overhead. That is the portable-addon path: one source compiles for this runtime and for the jitless iOS runtime, going fast only where the tier exists.
• Fallible fast functions are supported. V8 12.6+ lets a fast callback throw; the addon takes an opaque trailing ns_fast_options and throws through node_api_ns_fast_throw_{error,type_error,range_error}, which open the handle scope internally so no isolate is ever exposed.
• WebIDL conversion flags (clamp, enforce_range, is_restricted, allow_shared) are validated at registration — a flag on a type that cannot carry it is napi_invalid_arg rather than a V8 assert somewhere later.

Full contract, type table and "where it pays" in docs/node-api-fast-calls.md.

Implementation notes

• Per-signature interning is mandatory, not an optimization: CFunctionInfo keeps its argument array by raw pointer, and V8 keeps the CFunctionInfo by pointer for the template's life, so both are interned per distinct signature and intentionally never freed — the shape Node gets for free from file-scope statics.
• The slow path costs one extra V8 call. The vendored js_native_api_v8.cc defines CallbackBundle/FunctionCallbackWrapper inside namespace v8impl { namespace { … } } — internal linkage — so no other translation unit can invoke a napi_callback or fabricate a napi_callback_info. The forwarding callback therefore calls a real function made by napi_create_function, preserving napi's argument/receiver/exception semantics exactly, at the cost of one extra call whenever the fast path is not taken. That is the warmup path for anything hot enough to want fast calls; the real fix would be upstream, not a local ODR hack against internal classes.
• Fast functions cannot be used as constructors (ConstructorBehavior::kThrow): new would have to run the slow path with a new.target the forwarding cannot reproduce.

Deviations from the brainstorm doc

• Descriptor struct instead of the flat parameter list, so an explicitly unstable API can gain fields without breaking call sites — it already needed fallible and int64_as_bigint.
• Handle and string returns are rejected in v1 (they would require allocation, which the fast path forbids); scalars and void only.
• The iOS side should mirror the descriptor shape when it ships its slow-path-only version.

Testing

Full suite on an arm64 emulator (API 35): 895 passing / 0 failing — the feat/node-api baseline plus 16 fast-call specs.

The load-bearing ones:

• The fast path actually fires: after 300k calls through a monomorphic caller, fastCallCount > 0 and fast + slow account for exactly all 300,000 calls (the addon counts each path separately).
• The throw shim runs under optimized code: divide-by-zero calls are interleaved into the warm-up loop and the addon counts throws raised inside the fast function, because the observable RangeError is identical from either path. All 300 throws are caught with the right message and code, and the caller keeps running afterwards.
• Semantics on both paths, WebIDL clamping, one-byte vs two-byte strings (V8 declines the fast path for two-byte, so the slow path must agree), slow-only registration, and constructor rejection.

Note for reviewers: a pre-existing worker crash

While testing I hit intermittent SIGSEGVs (2 of 4 runs) that are not from this branch or #2004. They land within ~40 ms of a Worker runtime starting, and the fast-call specs create no workers. The device carries tombstones for this test app in threads named W10: ./EvalWork dated 2026-07-30, 08-03, 08-11 and 08-12 — weeks before any Node-API work — the most recent faulting inside v8::base::OS::Abort(). Worth tracking separately (no issue filed yet); flagging here so it is not mistaken for fallout from this stack. It also explains an occasional timing failure in the Throw error in onerror worker spec.

Performance

Measured on this runtime (not borrowed figures): 2M calls of a two-int32 addition — the cheapest possible body, so essentially pure call overhead — from an optimized caller on an arm64 emulator. Absolute numbers are inflated by virtualization; the ratio is the meaningful part.

≈ 35× on call overhead — the ceiling, not a typical result: as soon as the body does real work, or the arguments need anything the fast path forbids, the ratio collapses toward 1. The slow path's extra forwarding call is not separately measured.

Follow-ups

• Overloads (V8 resolves them by argument count), richer typed-array parameters, exposing the FastApiCallbackOptions data pointer.
• Root-cause the pre-existing worker crash above.