@crossbind/core-embind-napi 0.0.0-bootstrap.0 → 2.0.0-beta.62

package/README.md

@@ -1,6 +1,44 @@
 # @crossbind/core-embind-napi
+**crossbind Node-API host**  
+Runs the crossbind embind runtime inside a native Node.js addon, so the bindings that serve
+WebAssembly and React Native also build `.node` addons for Node.js and Electron.
 
-This version, 0.0.0-bootstrap.0, holds no code. npm lets a trusted publisher be configured only for a
-package that exists, so it reserves the name for the crossbind release workflow.
+<a href="https://www.npmjs.com/package/@crossbind/core-embind-napi">
+    <img alt="NPM version" src="https://img.shields.io/npm/v/@crossbind/core-embind-napi?style=for-the-badge" />
+</a>
+<a href="https://github.com/crossbind/crossbind/blob/main/LICENSE">
+    <img alt="License" src="https://img.shields.io/github/license/crossbind/crossbind?style=for-the-badge" />
+</a>
 
-Install the real package: `npm install @crossbind/core-embind-napi@beta`. Source: https://github.com/crossbind/crossbind
+## Use
+
+Add it next to `crossbind` and build the native platform:
+
+```bash
+pnpm add -D crossbind @crossbind/core-embind-napi
+pnpm crossbind build -p darwin
+```
+
+`dist/` then holds one addon per platform and architecture (`<name>.darwin-arm64.node`,
+`<name>.darwin-x64.node`) and the loader that picks one at runtime:
+
+```js
+const initNative = require('./dist/<name>.native.cjs');
+
+const { Native } = await initNative();
+```
+
+crossbind resolves this package from your project; you never import it yourself. See the
+[Node.js integration guide](https://github.com/crossbind/crossbind/blob/main/docs/playbooks/integration/nodejs.md#native-addon-node-api) for
+requirements and current limits (macOS only, no `worker_threads` yet).
+
+## Contents
+
+- `cpp/` — the addon's CMake project and its Node-API entry point.
+- `js/loader.js` — the loader crossbind bundles into `dist/<name>.native.cjs`.
+- `third_party/node-api-jsi/` — Microsoft's JSI implementation over Node-API (MIT), vendored at a
+  pinned commit; provenance and local patches are in its README.
+
+## License
+
+MIT

package/cpp/CMakeLists.txt

@@ -0,0 +1,69 @@
+cmake_minimum_required(VERSION 3.28)
+project(crossbind_node_addon CXX)
+
+# crossbind configures this project for one Node-API addon: the embind runtime and its Node-API
+# host compile here, the project's own code arrives as prebuilt archives in CROSSBIND_LINK_ARGS.
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+set(NODE_API_JSI "${CMAKE_CURRENT_SOURCE_DIR}/../third_party/node-api-jsi")
+
+if(WIN32)
+    set(NODE_API_LOADER "${NODE_API_JSI}/src/ApiLoaders/NodeApi_win.cpp")
+else()
+    set(NODE_API_LOADER "${NODE_API_JSI}/src/ApiLoaders/NodeApi_posix.cpp")
+endif()
+
+add_library(addon MODULE
+    src/node_api_module.cpp
+    "${NODE_API_JSI}/src/NodeApiJsiRuntime.cpp"
+    "${NODE_API_JSI}/src/ApiLoaders/NodeApi.cpp"
+    "${NODE_API_LOADER}"
+    "${NODE_API_JSI}/src/ApiLoaders/JSRuntimeApi.cpp"
+    "${NODE_API_JSI}/jsi/jsi/jsi.cpp"
+    "${CROSSBIND_JSI_ROOT}/cpp/src/emscripten/bind.cpp"
+    ${CROSSBIND_EXTRA_SOURCES})
+
+set_target_properties(addon PROPERTIES PREFIX "" SUFFIX "" OUTPUT_NAME "${CROSSBIND_ADDON_FILE}")
+
+target_include_directories(addon PRIVATE
+    "${NODE_API_JSI}/src"
+    "${NODE_API_JSI}/node-api"
+    "${NODE_API_JSI}/jsi"
+    "${CROSSBIND_JSI_ROOT}/cpp/src")
+
+target_link_libraries(addon PRIVATE ${CROSSBIND_LINK_ARGS})
+# A force-loaded archive reaches the link as a linker flag, which CMake does not track: without
+# this, a rebuilt bridge archive would leave the previous addon in place.
+set_property(TARGET addon APPEND PROPERTY LINK_DEPENDS ${CROSSBIND_LINK_DEPENDS})
+
+# glibc 2.28 keeps threads and dlopen in libraries of their own. The archives' symbols stay private
+# to the addon: node exports its own OpenSSL and zlib, and an exported copy here would trade calls
+# with them.
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    find_package(Threads REQUIRED)
+    target_link_libraries(addon PRIVATE Threads::Threads ${CMAKE_DL_LIBS})
+    target_link_options(addon PRIVATE "LINKER:--exclude-libs,ALL")
+    add_custom_command(TARGET addon POST_BUILD
+        COMMAND "${CMAKE_COMMAND}" "-DNM=${CMAKE_NM}" "-DADDON=$<TARGET_FILE:addon>"
+            -P "${CMAKE_CURRENT_SOURCE_DIR}/check-undefined.cmake"
+        VERBATIM)
+endif()
+
+# The C++ runtime, its unwinder and winpthreads go into the addon; the CRT stays the system's UCRT.
+# node-api-jsi's pooled values call the sized operator delete, which clang leaves off for MinGW.
+if(MINGW)
+    target_compile_options(addon PRIVATE -fsized-deallocation)
+    target_link_options(addon PRIVATE -static)
+endif()
+
+# Node-API symbols resolve against the node (or Electron) process that loads the addon. Everything
+# else must resolve at link time, so a stale or missing archive fails the build instead of the load.
+if(APPLE)
+    file(STRINGS "${NODE_API_JSI}/src/ApiLoaders/NodeApi.inc" NODE_API_FUNCS REGEX "^NODE_API_FUNC\\(")
+    foreach(line IN LISTS NODE_API_FUNCS)
+        string(REGEX REPLACE "^NODE_API_FUNC\\(([A-Za-z0-9_]+)\\).*" "\\1" func "${line}")
+        target_link_options(addon PRIVATE "LINKER:-U,_${func}")
+    endforeach()
+endif()

package/cpp/check-undefined.cmake

@@ -0,0 +1,18 @@
+# A Linux shared object may leave symbols undefined, and the loader binds functions lazily: an addon
+# that misses an archive loads, then dies at its first call into the missing code. Every undefined
+# symbol has to be a Node-API function or carry the version of a system library that defines it.
+execute_process(
+    COMMAND "${NM}" -D --undefined-only "${ADDON}"
+    OUTPUT_VARIABLE listing
+    COMMAND_ERROR_IS_FATAL ANY)
+string(REPLACE "\n" ";" lines "${listing}")
+set(unresolved)
+foreach(line IN LISTS lines)
+    if(line MATCHES "^ *U ([^@ ]+)$" AND NOT CMAKE_MATCH_1 MATCHES "^(napi|node_api)_")
+        list(APPEND unresolved "${CMAKE_MATCH_1}")
+    endif()
+endforeach()
+if(unresolved)
+    list(JOIN unresolved ", " names)
+    message(FATAL_ERROR "crossbind: ${ADDON} leaves symbols no archive defines: ${names}")
+endif()

package/cpp/src/node_api_module.cpp

@@ -0,0 +1,153 @@
+// Node-API host for the embind runtime in @crossbind/core-embind-jsi. The environment whose start()
+// runs first gets a JSI runtime; embind-jsi keeps one current runtime per process, so until runtimes
+// are kept per environment a second one (a worker thread) is refused rather than left to race it.
+#include <node_api.h>
+
+#ifdef _WIN32
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+#include <windows.h>
+#endif
+
+#include <atomic>
+#include <cstring>
+#include <memory>
+#include <string>
+
+#include <ApiLoaders/JSRuntimeApi.h>
+#include <NodeApiJsiRuntime.h>
+#include <emscripten/bind.h>
+
+namespace {
+
+using Microsoft::NodeApiJsi::FuncPtr;
+using Microsoft::NodeApiJsi::IFuncResolver;
+using Microsoft::NodeApiJsi::JSRuntimeApi;
+
+// node-api-jsi reaches Node-API through a function table; each entry points at the symbol this
+// addon already imports from the host process. On Windows the entries are looked up in the
+// executable instead: node.exe and Electron both export Node-API, so the addon imports nothing from
+// either and needs no import library. jsr_* engine extensions stay null on purpose: JSRuntimeApi
+// falls back to its defaults for them.
+struct ProcessResolver : IFuncResolver {
+    FuncPtr getFuncPtr(const char *funcName) override {
+#ifdef _WIN32
+        return reinterpret_cast<FuncPtr>(GetProcAddress(GetModuleHandleW(nullptr), funcName));
+#else
+#define NODE_API_FUNC(func) \
+    if (std::strcmp(funcName, #func) == 0) return reinterpret_cast<FuncPtr>(&func);
+#include <ApiLoaders/NodeApi.inc>
+        return nullptr;
+#endif
+    }
+};
+
+// The Node-API calls this file makes itself resolve the same way. They look the function up on each
+// call rather than through a JSRuntimeApi, whose entries resolve against the current runtime's table,
+// and there is none while the module initializes.
+ProcessResolver processResolver;
+#define NODE_API(func) reinterpret_cast<decltype(&::func)>(processResolver.getFuncPtr(#func))
+
+struct EnvState {
+    napi_env env = nullptr;
+    ProcessResolver resolver;
+    JSRuntimeApi api{&resolver};
+    std::unique_ptr<facebook::jsi::Runtime> runtime;
+};
+
+std::atomic<napi_env> owner{nullptr};
+
+// Native values can outlive the runtime they point into (thread-local ones are destroyed inside
+// exit()); with no current runtime their release becomes a no-op instead of a call into a dead one.
+void forgetRuntime(EnvState *state) {
+    if (state == nullptr) {
+        return;
+    }
+    if (emscripten::jsRuntime == state->runtime.get()) {
+        emscripten::jsRuntime = nullptr;
+    }
+    napi_env finished = state->env;
+    owner.compare_exchange_strong(finished, nullptr);
+}
+
+std::string readString(napi_env env, napi_value value) {
+    size_t length = 0;
+    NODE_API(napi_get_value_string_utf8)(env, value, nullptr, 0, &length);
+    std::string result(length, '\0');
+    NODE_API(napi_get_value_string_utf8)(env, value, result.data(), length + 1, &length);
+    return result;
+}
+
+// start(dataPath) registers every EMSCRIPTEN_BINDINGS block of the addon into this environment's
+// embind runtime, so embind.js must already be loaded. A second call in the same environment is a
+// no-op: registering twice fails with "Cannot register public name ... twice".
+napi_value Start(napi_env env, napi_callback_info info) {
+    void *existing = nullptr;
+    NODE_API(napi_get_instance_data)(env, &existing);
+    if (existing != nullptr) {
+        return nullptr;
+    }
+    // The same environment may retry after a start that failed before it took ownership.
+    napi_env current = nullptr;
+    if (!owner.compare_exchange_strong(current, env) && current != env) {
+        NODE_API(napi_throw_error)(env, nullptr,
+            "crossbind: the native addon already runs in another Node environment; "
+            "worker_threads are not supported yet");
+        return nullptr;
+    }
+
+    size_t argc = 1;
+    napi_value argv[1];
+    NODE_API(napi_get_cb_info)(env, info, &argc, argv, nullptr, nullptr);
+    const std::string dataPath = argc > 0 ? readString(env, argv[0]) : std::string();
+
+    // An exception must not unwind through Node-API, which would end the process.
+    try {
+        auto state = std::make_unique<EnvState>();
+        state->env = env;
+        JSRuntimeApi::setCurrent(&state->api);
+        state->runtime = Microsoft::NodeApiJsi::makeNodeApiJsiRuntime(env, &state->api, [] {});
+        // The environment owns it before any binding registers: registered functions point into it,
+        // so it has to outlive a registration that fails halfway.
+        EnvState *owned = state.release();
+        NODE_API(napi_set_instance_data)(
+            env, owned,
+            [](napi_env, void *data, void *) {
+                auto *finished = static_cast<EnvState *>(data);
+                forgetRuntime(finished);
+                delete finished;
+            },
+            nullptr);
+        emscripten::internal::_embind_initialize_bindings(*owned->runtime, dataPath);
+    } catch (const std::exception &error) {
+        NODE_API(napi_throw_error)(env, nullptr, error.what());
+    } catch (...) {
+        NODE_API(napi_throw_error)(env, nullptr, "crossbind: the native module failed to start");
+    }
+    return nullptr;
+}
+
+// stop() runs from the environment's 'exit' event: no JS runs here afterwards, and process.exit()
+// skips the teardown that would otherwise release the instance data.
+napi_value Stop(napi_env env, napi_callback_info) {
+    void *data = nullptr;
+    NODE_API(napi_get_instance_data)(env, &data);
+    forgetRuntime(static_cast<EnvState *>(data));
+    return nullptr;
+}
+
+}  // namespace
+
+NAPI_MODULE_INIT() {
+    napi_value start;
+    NODE_API(napi_create_function)(env, "start", NAPI_AUTO_LENGTH, Start, nullptr, &start);
+    NODE_API(napi_set_named_property)(env, exports, "start", start);
+    napi_value stop;
+    NODE_API(napi_create_function)(env, "stop", NAPI_AUTO_LENGTH, Stop, nullptr, &stop);
+    NODE_API(napi_set_named_property)(env, exports, "stop", stop);
+    return exports;
+}

package/js/loader.js

@@ -0,0 +1,70 @@
+// Entry of the per-project loader crossbind bundles next to the native addons
+// (dist/<name>.native.cjs). It keeps the wasm build's initNative() contract, so the same app code
+// runs on either build.
+import path from 'node:path';
+import Module from '@crossbind/core-embind-jsi';
+import systemConfig from 'crossbind/systemConfig';
+
+function addonFileName() {
+    return systemConfig.paths.addon.replace('{platform}', process.platform).replace('{arch}', process.arch);
+}
+
+function loadAddon(file) {
+    const addon = { exports: {} };
+    try {
+        process.dlopen(addon, file);
+    } catch (error) {
+        throw new Error(
+            `crossbind: cannot load ${file} - build it with \`crossbind build -p ${process.platform} -a ${process.arch}\`.`,
+            { cause: error },
+        );
+    }
+    return addon.exports;
+}
+
+function setEnv(dataPath, runtimeEnv) {
+    // Build-time values are keyed by addon: a target-scoped value must not leak from one arch's
+    // build into another's. Values passed to initNative() win, as in the wasm runtime.
+    const env = { ...systemConfig.env[`${process.platform}-${process.arch}`], ...runtimeEnv };
+    Object.entries(env).forEach(([key, value]) => {
+        Module.Crossbind.setEnv(key, String(value).replace('_CROSSBIND_DATA_PATH_', dataPath), false);
+    });
+}
+
+let addon = null;
+
+function boot(config) {
+    const dataPath = config.dataPath ?? path.join(__dirname, 'data');
+    // Loaded and started once per process: Node cannot unload an addon, and a second dlopen gets a
+    // fresh environment whose start() would register every binding twice.
+    if (!addon) {
+        const loaded = loadAddon(config.addonPath ?? path.join(__dirname, addonFileName()));
+        loaded.start(dataPath);
+        // Native values released after this (thread-local ones die inside exit()) must not call
+        // back into the runtime.
+        process.once('exit', () => loaded.stop());
+        addon = loaded;
+    }
+    setEnv(dataPath, config.env);
+    return Module;
+}
+
+let booted = null;
+
+export default function initNative(config = {}) {
+    if (!booted) {
+        try {
+            booted = Promise.resolve(boot(config));
+        } catch (error) {
+            // Not remembered: a later call retries, for example once the addon is built.
+            return Promise.reject(error);
+        }
+    }
+    return booted;
+}
+
+// The wasm runtime's contract: forget the booted module so the next call boots again. Native state
+// cannot be reset (Node cannot unload an addon), so that call resolves the same module.
+initNative.terminate = function terminate() {
+    booted = null;
+};

package/package.json

@@ -1,7 +1,30 @@
 {
-    "name": "@crossbind/core-embind-napi",
-    "version": "0.0.0-bootstrap.0",
-    "description": "Placeholder that let npm trust the crossbind release workflow; install @crossbind/core-embind-napi@beta.",
-    "license": "MIT",
-    "repository": "https://github.com/crossbind/crossbind.git"
-}
+  "name": "@crossbind/core-embind-napi",
+  "version": "2.0.0-beta.62",
+  "description": "Node-API host for the crossbind embind runtime: native Node.js addons from the same C++ and Rust bindings.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/core/embind-napi#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "files": [
+    "cpp",
+    "js",
+    "third_party"
+  ],
+  "dependencies": {
+    "@crossbind/core-embind-jsi": "^2.0.0-beta.62"
+  },
+  "keywords": [
+    "embind",
+    "node-api",
+    "napi",
+    "addon",
+    "bind",
+    "c++",
+    "rust",
+    "node",
+    "electron"
+  ]
+}

package/third_party/node-api-jsi/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/third_party/node-api-jsi/README.md

@@ -0,0 +1,55 @@
+# node-api-jsi (vendored)
+
+A JSI (`facebook::jsi`) implementation on top of Node-API. It lets the embind runtime in
+`@crossbind/core-embind-jsi` run inside a Node.js addon unchanged.
+
+- Upstream: https://github.com/microsoft/node-api-jsi
+- Commit: `4b8a4a59c4e1b7b988b809dedffd89a7662aa785` (upstream publishes no releases)
+- Archive: `https://codeload.github.com/microsoft/node-api-jsi/tar.gz/4b8a4a5`,
+  sha256 `701dfaac5b281b9b67986611ba612d6fe253c434f65459c877b24debf41d3c43`
+- License: MIT, see `LICENSE`
+
+Only the files the addon compiles are kept: `src/NodeApiJsiRuntime.*`, the `src/ApiLoaders`
+Node-API and JSRuntime loaders, `jsi/jsi/{jsi.h,jsi-inl.h,jsi.cpp,instrumentation.h}` and the
+`node-api` headers. `jsi.h` falls back to `JSI_VERSION` 21 when no compile definition sets it, so
+no `jsi-version.h` is needed.
+
+## Local patches
+
+- `src/NodeApiJsiRuntime.cpp` includes `<atomic>` and `<utility>`, which GCC and Clang do not
+  pull in transitively.
+- `jsiHostFunctionCallback` is declared `NAPI_CDECL` instead of `__cdecl`, so the calling
+  convention only applies where Node-API defines one (Windows).
+- `createStringFromAscii`, `createStringFromUtf8`, `createBigIntFromInt64`,
+  `createBigIntFromUint64`, `bigintIsInt64`, `bigintIsUint64`, `truncate`, `utf8(const String&)`
+  and `call` skip their own `NodeApiScope` while a pointer value scope is open and has taken fewer
+  than `MaxUsesPerOpenScope` (64) such calls. Upstream wraps every primitive they return in an
+  object behind a `napi_ref` when that scope closes and reads it back on use; a string-returning
+  call went from about 370 to 120 ns and a `const char*` argument, seven emval round trips, from
+  4.2 to 1.3 µs. The cap keeps a loop inside one call bounded: without it, a million callbacks
+  from one call raised peak memory from 96 to 649 MB. `getProperty`, `instanceOf`,
+  `isArrayBuffer`, `size` and `data` of an `ArrayBuffer`, and `callAsConstructor` skip it the same
+  way: reading a typed array from C++ opened a Node-API handle scope (a heap allocation in Node)
+  for each of these, and a Rust `&[u8]` argument went from 1.16 to 0.94 µs.
+- `NodeApiPendingDeletions` keeps an atomic flag, so `deletePointerValues` takes its mutex only
+  when something waits for deletion (about 10 to 20 ns off every call).
+- `NodeApiRefCountedPointerValue::decRefCount` marks a value released on the JS thread while it
+  is still on the value stack and has no `napi_ref` for the stack to delete, which is all the
+  pending deletion would do, and skips the recursive mutex it takes twice. embind reads every
+  `this` pointer and string argument through such a clone: a four-double method call went from
+  384 to 362 ns and a `std::string` argument from 211 to 179 ns.
+- `JsiValueViewArgs` constructs each argument in place and destroys only those, instead of
+  building `MaxStackArgCount` `jsi::Value`s, move-assigning into them and destroying all of them
+  out of line on every call: 369 to 347 ns for the same method call.
+- `NodeApiJsiRuntime` answers `castInterface` for `crossbind::IDirectReads`
+  (`core/embind-jsi/cpp/src/crossbind/direct_reads.h`). `typedArrayElements` makes one
+  `napi_get_typedarray_info` call where reading the view's `buffer`, `byteOffset` and `length`
+  through the object API took about 440 ns, most of a Rust `xxh32` call on 32 bytes, which went
+  from 591 to 87 ns. `bigIntToUint64` and `bigIntToInt64` read a BigInt argument without cloning
+  it into a heap pointer value first; embind-jsi reads `this` and its other 64-bit values through
+  them, and a method call such as `vector.size()` went from 61 to 51 ns.
+- `NodeApiRefCountedPointerValue` takes its memory from a per-thread list of up to 64 blocks
+  instead of malloc: most live for one host call, a string, BigInt or `this` read or made during
+  it. A string return went from 75 to 69 ns and a string argument from 95 to 84 ns; together with
+  the direct BigInt read, a Rust `xxh64` call on 32 bytes with a BigInt seed and result went from
+  141 to 110 ns. A million callbacks in one call peak at the same 70 MB.

package/third_party/node-api-jsi/jsi/jsi/instrumentation.h

@@ -0,0 +1,150 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <chrono>
+#include <iosfwd>
+#include <string>
+#include <tuple>
+#include <unordered_map>
+
+#include <jsi/jsi.h>
+
+namespace facebook {
+namespace jsi {
+
+/// Methods for starting and collecting instrumentation, an \c Instrumentation
+/// instance is associated with a particular \c Runtime instance, which it
+/// controls the instrumentation of.
+/// None of these functions should return newly created jsi values, nor should
+/// it modify the values of any jsi values in the heap (although GCs are fine).
+class JSI_EXPORT Instrumentation {
+ public:
+#if JSI_VERSION >= 13
+  /// Additional options controlling what to include when capturing a heap
+  /// snapshot.
+  struct HeapSnapshotOptions {
+    bool captureNumericValue{false};
+  };
+#endif
+
+  virtual ~Instrumentation() = default;
+
+  /// Returns GC statistics as a JSON-encoded string, with an object containing
+  /// "type" and "version" fields outermost. "type" is a string, unique to a
+  /// particular implementation of \c jsi::Instrumentation, and "version" is a
+  /// number to indicate any revision to that implementation and its output
+  /// format.
+  ///
+  /// \pre This call can only be made on the instrumentation instance of a
+  ///   runtime initialised to collect GC statistics.
+  ///
+  /// \post All cumulative measurements mentioned in the output are accumulated
+  ///   across the entire lifetime of the Runtime.
+  ///
+  /// \return the GC statistics collected so far, as a JSON-encoded string.
+  virtual std::string getRecordedGCStats() = 0;
+
+  /// Request statistics about the current state of the runtime's heap. This
+  /// function can be called at any time, and should produce information that is
+  /// correct at the instant it is called (i.e, not stale).
+  ///
+  /// \return a map from a string key to a number associated with that
+  /// statistic.
+  virtual std::unordered_map<std::string, int64_t> getHeapInfo(
+      bool includeExpensive) = 0;
+
+  /// Perform a full garbage collection.
+  /// \param cause The cause of this collection, as it should be reported in
+  ///   logs.
+  virtual void collectGarbage(std::string cause) = 0;
+
+  /// A HeapStatsUpdate is a tuple of the fragment index, the number of objects
+  /// in that fragment, and the number of bytes used by those objects.
+  /// A "fragment" is a view of all objects allocated within a time slice.
+  using HeapStatsUpdate = std::tuple<uint64_t, uint64_t, uint64_t>;
+
+  /// Start capturing JS stack-traces for all JS heap allocated objects. These
+  /// can be accessed via \c ::createSnapshotToFile().
+  /// \param fragmentCallback If present, invoke this callback every so often
+  ///   with the most recently seen object ID, and a list of fragments that have
+  ///   been updated. This callback will be invoked on the same thread that the
+  ///   runtime is using.
+  virtual void startTrackingHeapObjectStackTraces(
+      std::function<void(
+          uint64_t lastSeenObjectID,
+          std::chrono::microseconds timestamp,
+          std::vector<HeapStatsUpdate> stats)> fragmentCallback) = 0;
+
+  /// Stop capture JS stack-traces for JS heap allocated objects.
+  virtual void stopTrackingHeapObjectStackTraces() = 0;
+
+  /// Start a heap sampling profiler that will sample heap allocations, and the
+  /// stack trace they were allocated at. Reports a summary of which functions
+  /// allocated the most.
+  /// \param samplingInterval The number of bytes allocated to wait between
+  ///   samples. This will be used as the expected value of a poisson
+  ///   distribution.
+  virtual void startHeapSampling(size_t samplingInterval) = 0;
+
+  /// Turns off the heap sampling profiler previously enabled via
+  /// \c startHeapSampling. Writes the output of the sampling heap profiler to
+  /// \p os. The output is a JSON formatted string.
+  virtual void stopHeapSampling(std::ostream& os) = 0;
+
+#if JSI_VERSION >= 13
+  /// Captures the heap to a file
+  ///
+  /// \param path to save the heap capture.
+  /// \param options additional options for what to capture.
+  virtual void createSnapshotToFile(
+      const std::string& path,
+      const HeapSnapshotOptions& options = {false}) = 0;
+#else
+  /// Captures the heap to a file
+  ///
+  /// \param path to save the heap capture
+  virtual void createSnapshotToFile(const std::string& path) = 0;
+#endif
+
+#if JSI_VERSION >= 13
+  /// Captures the heap to an output stream
+  ///
+  /// \param os output stream to write to.
+  /// \param options additional options for what to capture.
+  virtual void createSnapshotToStream(
+      std::ostream& os,
+      const HeapSnapshotOptions& options = {false}) = 0;
+#else
+  /// Captures the heap to an output stream
+  ///
+  /// \param os output stream to write to.
+  virtual void createSnapshotToStream(std::ostream& os) = 0;
+#endif
+
+  /// If the runtime has been created to trace to a temp file, flush
+  /// any unwritten parts of the trace of bridge traffic to the file,
+  /// and return the name of  the file.  Otherwise, return the empty string.
+  /// Tracing is disabled after this call.
+  virtual std::string flushAndDisableBridgeTrafficTrace() = 0;
+
+  /// Write basic block profile trace to the given file name.
+  virtual void writeBasicBlockProfileTraceToFile(
+      const std::string& fileName) const = 0;
+
+#if JSI_VERSION >= 21
+  /// Write the opcode stats to the given stream.
+  virtual void dumpOpcodeStats(std::ostream& os) const = 0;
+#endif
+
+  /// Dump external profiler symbols to the given file name.
+  virtual void dumpProfilerSymbolsToFile(const std::string& fileName) const = 0;
+};
+
+} // namespace jsi
+} // namespace facebook