@pulse-compute/wasm-build-support 1.0.0-beta.5 → 1.0.0-beta.6

package/README.md

@@ -7,9 +7,9 @@
 > **Supported entry points:** `None for application authors.`<br>
 > **Stability:** Internal release-set interface; exported modules may change with compiler implementation needs.<br>
 > **npm:** [`@pulse-compute/wasm-build-support`](https://www.npmjs.com/package/@pulse-compute/wasm-build-support)<br>
-> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.5/packages/implementation-packages/)
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.6/packages/implementation-packages/)
 >
-> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.5` package policy.
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.6` package policy.
 <!-- pulse-package-status:end -->
 
 Shared build-time helpers for PulseWasm package-owned builders.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-compute/wasm-build-support",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.6",
   "license": "Apache-2.0",
   "engines": {
     "node": "^22.14.0 || ^24.0.0"
@@ -16,7 +16,7 @@
     "./files": "./src/files.js"
   },
   "dependencies": {
-    "@pulse-compute/wasm-contracts": "1.0.0-beta.5"
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.6"
   },
   "publishConfig": {
     "access": "public"
@@ -32,7 +32,7 @@
     "url": "git+https://github.com/pulse-compute/pulse.git",
     "directory": "wasm/packages/build-support"
   },
-  "homepage": "https://pulsecompute.io/v1.0.0-beta.5/packages/implementation-packages/",
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.6/packages/implementation-packages/",
   "bugs": {
     "url": "https://github.com/pulse-compute/pulse/issues"
   }

package/src/native-optimization.js

@@ -1,8 +1,11 @@
 'use strict';
 
+const path = require('node:path');
+
 const {
   NATIVE_OPTIMIZATION_VERSION,
-  EXPERIMENTAL_NATIVE_SIZE_MODE
+  EXPERIMENTAL_NATIVE_SIZE_MODE,
+  EXPERIMENTAL_NATIVE_BOUNDED_SIZE_MODE
 } = require('@pulse-compute/wasm-contracts/project/native-optimization');
 const EXPERIMENTAL_NATIVE_SIZE_OPTIMIZATION = Object.freeze({
   version: NATIVE_OPTIMIZATION_VERSION,
@@ -17,6 +20,19 @@ const EXPERIMENTAL_NATIVE_SIZE_OPTIMIZATION = Object.freeze({
   })
 });
 
+const EXPERIMENTAL_NATIVE_BOUNDED_SIZE_OPTIMIZATION = Object.freeze({
+  version: NATIVE_OPTIMIZATION_VERSION,
+  mode: EXPERIMENTAL_NATIVE_BOUNDED_SIZE_MODE,
+  experimental: true,
+  goal: 'size',
+  assemblyScript: Object.freeze({
+    optimize: true,
+    optimizeLevel: 3,
+    shrinkLevel: 2,
+    converge: false
+  })
+});
+
 function resolveNativeOptimization(value) {
   if (value === undefined || value === null || value === false) return undefined;
   if (
@@ -26,11 +42,21 @@ function resolveNativeOptimization(value) {
   ) {
     return EXPERIMENTAL_NATIVE_SIZE_OPTIMIZATION;
   }
+  if (value === EXPERIMENTAL_NATIVE_BOUNDED_SIZE_MODE
+    || (typeof value === 'object' && value.mode === EXPERIMENTAL_NATIVE_BOUNDED_SIZE_MODE)) {
+    return EXPERIMENTAL_NATIVE_BOUNDED_SIZE_OPTIMIZATION;
+  }
   throw new TypeError(`Unsupported Pulse Native optimization mode ${String(value && value.mode || value)}.`);
 }
 
-function appendAssemblyScriptOptimizationArgs(args, value) {
+function appendAssemblyScriptOptimizationArgs(args, value, options = {}) {
   if (!Array.isArray(args)) throw new TypeError('AssemblyScript optimization arguments require a mutable argument array.');
+  // AssemblyScript ignores custom @noinline annotations. Apply Pulse's generated
+  // annotations to Binaryen IR before its default passes in every profile.
+  args.push('--transform', path.join(__dirname, 'native-retention-transform.cjs'));
+  // Run merging after asc's optimizer has honored retained helper boundaries.
+  // Guest inputs are merged once, with the other units, by the guest-link owner.
+  if (!options.guestLinked) args.push('--runPasses', 'merge-similar-functions');
   const optimization = resolveNativeOptimization(value);
   if (!optimization) return undefined;
   args.push(
@@ -45,6 +71,8 @@ module.exports = Object.freeze({
   NATIVE_OPTIMIZATION_VERSION,
   EXPERIMENTAL_NATIVE_SIZE_MODE,
   EXPERIMENTAL_NATIVE_SIZE_OPTIMIZATION,
+  EXPERIMENTAL_NATIVE_BOUNDED_SIZE_MODE,
+  EXPERIMENTAL_NATIVE_BOUNDED_SIZE_OPTIMIZATION,
   resolveNativeOptimization,
   appendAssemblyScriptOptimizationArgs
 });

package/src/native-retention-transform.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+// asc injects its own pinned Binaryen instance into transform constructors.
+// No additional optimizer instance, public decorator or dependency is needed.
+const generatedEntries = new Set(['canonical-native.as', 'fastly-native-platform-capabilities.as']);
+// Legacy numeric names remain supported for captured sources and fixtures.
+// The private retained suffix is only a batching aid: it grants no retention
+// without the existing compiler-owned source and @noinline annotation.
+const generatedFunction = /^__pulse_(?:expr_\d+|ex_\d+\$[ik]|chunk_\d+|shared_stage_\d+|stage_(?:prepare|clear|ready|result)|step|route_error)$/;
+
+function commonPrefixLength(left, right) {
+  let length = 0;
+  while (length < left.length && length < right.length && left[length] === right[length]) length++;
+  return length;
+}
+
+function retentionPatterns(module, binaryen, retainedNames) {
+  const selected = new Set(retainedNames.filter(name => module.getFunction(name)));
+  if (selected.size < 2) return [...selected];
+  const names = [];
+  for (let index = 0; index < module.getNumFunctions(); index++) {
+    names.push(binaryen.Function.getName(module.getFunctionByIndex(index)));
+  }
+  const patterns = new Set();
+  for (const entry of generatedEntries) {
+    const prefix = `${entry}/__pulse_ex_`, suffix = '$k';
+    const matches = names.filter(name => name.startsWith(prefix) && name.endsWith(suffix));
+    // Check every actual wildcard match, including unannotated functions and
+    // imports. A private-looking name never grants retention on its own.
+    if (matches.length > 1 && matches.every(name => selected.has(name))) {
+      patterns.add(`${prefix}*${suffix}`);
+      for (const name of matches) selected.delete(name);
+    }
+  }
+  names.sort();
+  for (let start = 0; start < names.length;) {
+    if (!selected.has(names[start])) { start++; continue; }
+    let end = start + 1;
+    while (end < names.length && selected.has(names[end])) end++;
+    // In lexical order, the nearest unselected neighbors bound every safe
+    // prefix in this run. Include all module functions, including imports and
+    // unannotated leaves: a wildcard must never broaden retention policy.
+    const before = names[start - 1] || '';
+    const after = names[end] || '';
+    for (let index = start; index < end; index++) {
+      const name = names[index];
+      const length = Math.max(
+        name.indexOf('/__pulse_') + '/__pulse_'.length,
+        commonPrefixLength(name, before) + 1,
+        commonPrefixLength(name, after) + 1
+      );
+      // An unselected name may extend the entire selected name (e.g. 1/10).
+      // In that case only an exact pattern is safe.
+      patterns.add(length > name.length ? name : `${name.slice(0, length)}*`);
+    }
+    start = end;
+  }
+  return [...patterns];
+}
+
+module.exports = class NativeRetentionTransform {
+  afterParse(parser) {
+    this.retainedNames = [];
+    for (const source of parser.sources) {
+      if (!generatedEntries.has(source.internalPath)) continue;
+      for (const declaration of source.statements) {
+        if (generatedFunction.test(declaration.name?.text || '')
+          && declaration.decorators?.some(decorator => decorator.name?.text === 'noinline')) {
+          this.retainedNames.push(`${source.internalPath}/${declaration.name.text}`);
+        }
+      }
+    }
+  }
+
+  afterCompile(module) {
+    // afterCompile precedes optimization; asc --runPasses runs too late.
+    const previous = this.binaryen.getPassArgument('no-inline');
+    try {
+      // Binaryen's no-inline pass scans the whole module for one wildcard.
+      // Batch only patterns whose existing matches are all already selected.
+      for (const pattern of retentionPatterns(module, this.binaryen, this.retainedNames)) {
+        this.binaryen.setPassArgument('no-inline', pattern);
+        module.runPasses(['no-inline']);
+      }
+    } finally {
+      this.binaryen.setPassArgument('no-inline', previous);
+    }
+  }
+};