@pulse-compute/wasm-compiler 0.0.0 → 1.0.0-beta.2

package/src/provider-toolchain.js

@@ -0,0 +1,299 @@
+'use strict';
+
+const path = require('node:path');
+const { createRequire } = require('node:module');
+const {
+  PROVIDER_DRIVER_VERSION,
+  PROVIDER_TARGET_RESULT_VERSION,
+  assertProviderToolchain,
+  assertProviderDriver,
+  normalizeProviderTargetResult
+} = require('@pulse-compute/wasm-contracts/provider/toolchain');
+
+const PROVIDER_PACKAGE_SCOPE = '@pulse-compute';
+const PROVIDER_PACKAGE_PREFIX = 'provider-';
+const BUILTIN_PROVIDER_IDS = Object.freeze(['node', 'fastly', 'none']);
+const loadedByEntry = new Map();
+
+const reportingTargetCapability = Object.freeze({
+  supported: true,
+  default: 'info',
+  levels: Object.freeze(['off', 'error', 'warn', 'info', 'debug'])
+});
+
+const noneDriver = assertProviderDriver({
+  version: PROVIDER_DRIVER_VERSION,
+  id: 'none',
+  descriptor: undefined,
+  executable: false,
+  localExecution: false,
+  deployable: false,
+  deploymentValidated: false,
+  sourcePackage: false,
+  compiledWasm: true,
+  defaultBuildMode: 'compile-only',
+  sourceOnlySupported: false,
+  normalizeConfig() {
+    return Object.freeze({ kind: 'none', bindings: Object.freeze({}), local: Object.freeze({}) });
+  },
+  defaultLocalNetworkFetch: false,
+  projectConfigDocument() { return undefined; },
+  initTemplate() {
+    return Object.freeze({ profileFragment: '', dependencies: Object.freeze({}) });
+  },
+  targets: Object.freeze({
+    native: Object.freeze({
+      version: 'pulse.provider-target-descriptor.v1',
+      target: 'native',
+      targetId: 'portable-native-wasm',
+      runtimeClass: 'native',
+      status: 'compile-only',
+      automaticFallback: false,
+      reporting: reportingTargetCapability,
+      commands: Object.freeze({ compile: true, inspect: true, doctor: true, build: false, test: false, dev: false })
+    }),
+    javascript: Object.freeze({
+      version: 'pulse.javascript-target-descriptor.v2',
+      target: 'javascript',
+      targetId: 'none-javascript',
+      runtimeClass: 'javascript',
+      status: 'unsupported',
+      sourceApplication: true,
+      automaticFallback: false,
+      hostBridge: false,
+      applicationLoader: false,
+      requestAdapter: false,
+      lifecycle: false,
+      reporting: reportingTargetCapability,
+      commands: Object.freeze({ compile: true, inspect: true, doctor: true, build: false, test: false, dev: false })
+    })
+  }),
+  inspectRealization(invocation) {
+    const artifact = invocation.nativeArtifact;
+    return normalizeProviderTargetResult({
+      version: PROVIDER_TARGET_RESULT_VERSION,
+      action: 'inspect-native',
+      provider: 'none',
+      target: 'native',
+      status: 'inspected',
+      automaticFallback: false,
+      files: Object.freeze({}),
+      build: null,
+      realization: Object.freeze({
+        target: 'portable-native-wasm',
+        provider: null,
+        providerNeutralWasm: true,
+        nativeWasm: true,
+        javascriptRuntime: false,
+        jsComputeRuntime: false,
+        wasm: artifact.manifest.wasm,
+        wat: artifact.manifest.wat,
+        importModules: artifact.manifest.importModules,
+        imports: artifact.manifest.imports,
+        exports: artifact.manifest.exports
+      }),
+      packaging: null
+    });
+  }
+});
+
+function providerError(code, message, detail = {}, cause) {
+  const error = new TypeError(message, cause ? { cause } : undefined);
+  error.code = code;
+  error.detail = Object.freeze({ ...detail });
+  return error;
+}
+
+function normalizeSelector(value) {
+  const selector = String(value || '').trim();
+  if (!selector) throw providerError('PULSE_PROVIDER_UNSUPPORTED', 'Pulse provider selection must not be empty.');
+  return selector.startsWith('@') ? selector : selector.toLowerCase();
+}
+
+function assertPackageName(value) {
+  const packageName = String(value);
+  const segment = '[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?';
+  const valid = new RegExp(`^(?:${segment}|@${segment}/${segment})$`).test(packageName);
+  if (!valid || packageName === '.' || packageName === '..') {
+    throw providerError(
+      'PULSE_PROVIDER_UNSUPPORTED',
+      `Pulse provider "${packageName}" must be an exact npm package name.`,
+      { selector: packageName }
+    );
+  }
+  return packageName;
+}
+
+function providerPackageName(value) {
+  const selector = normalizeSelector(value);
+  if (selector === 'none') return null;
+  if (selector.startsWith('@')) return assertPackageName(selector);
+  return `${PROVIDER_PACKAGE_SCOPE}/${PROVIDER_PACKAGE_PREFIX}${assertPackageName(selector)}`;
+}
+
+function projectRequire(projectRoot) {
+  const root = path.resolve(projectRoot || process.cwd());
+  return createRequire(path.join(root, 'package.json'));
+}
+
+function resolveToolchainEntry(selector, packageName, options = {}) {
+  const request = `${packageName}/toolchain`;
+  const builtin = BUILTIN_PROVIDER_IDS.includes(selector);
+  const resolver = builtin ? require : projectRequire(options.projectRoot);
+  try {
+    return resolver.resolve(request);
+  } catch (cause) {
+    throw providerError(
+      'PULSE_PROVIDER_PACKAGE_NOT_FOUND',
+      `Pulse provider package "${packageName}" does not expose ${request}.`,
+      {
+        selector,
+        packageName,
+        projectRoot: path.resolve(options.projectRoot || process.cwd()),
+        entrypoint: './toolchain'
+      },
+      cause
+    );
+  }
+}
+
+function loadProviderToolchain(selector, packageName, entry) {
+  const cached = loadedByEntry.get(entry);
+  if (cached) return cached;
+  let declared;
+  try {
+    declared = require(entry);
+  } catch (cause) {
+    throw providerError(
+      'PULSE_PROVIDER_TOOLCHAIN_LOAD_FAILED',
+      `Pulse could not load provider toolchain "${packageName}/toolchain".`,
+      { selector, packageName, entrypoint: './toolchain' },
+      cause
+    );
+  }
+  let toolchain;
+  try {
+    toolchain = assertProviderToolchain(declared, {
+      packageName,
+      id: BUILTIN_PROVIDER_IDS.includes(selector) ? selector : undefined
+    });
+  } catch (cause) {
+    throw providerError(
+      'PULSE_PROVIDER_TOOLCHAIN_INVALID',
+      `Provider package "${packageName}" does not implement the Pulse provider toolchain contract.`,
+      { selector, packageName, entrypoint: './toolchain' },
+      cause
+    );
+  }
+  let driver;
+  try {
+    driver = assertProviderDriver(toolchain.createDriver(), { id: toolchain.id });
+  } catch (cause) {
+    if (cause && cause.code === 'PULSE_PROVIDER_TOOLCHAIN_INVALID') throw cause;
+    throw providerError(
+      'PULSE_PROVIDER_TOOLCHAIN_LOAD_FAILED',
+      `Provider package "${packageName}" failed while creating its Pulse driver.`,
+      { selector, packageName, entrypoint: './toolchain' },
+      cause
+    );
+  }
+  const loaded = Object.freeze({ toolchain, driver });
+  loadedByEntry.set(entry, loaded);
+  return loaded;
+}
+
+function resolveProviderToolchain(value, options = {}) {
+  const selector = normalizeSelector(value);
+  if (selector === 'none') {
+    return Object.freeze({
+      selector,
+      id: 'none',
+      packageName: null,
+      packageVersion: null,
+      contractVersion: null,
+      entrypoint: null,
+      official: true,
+      driver: noneDriver
+    });
+  }
+  const packageName = providerPackageName(selector);
+  const entry = resolveToolchainEntry(selector, packageName, options);
+  const loaded = loadProviderToolchain(selector, packageName, entry);
+  return Object.freeze({
+    selector,
+    id: loaded.driver.id,
+    packageName: loaded.toolchain.packageName,
+    packageVersion: loaded.toolchain.packageVersion,
+    contractVersion: loaded.toolchain.version,
+    entrypoint: './toolchain',
+    official: BUILTIN_PROVIDER_IDS.includes(selector),
+    driver: loaded.driver
+  });
+}
+
+function getProviderDriver(value, options = {}) {
+  return resolveProviderToolchain(value, options).driver;
+}
+
+function getProviderTargetDescriptor(provider, target = 'native', options = {}) {
+  const driver = typeof provider === 'string' ? getProviderDriver(provider, options) : provider;
+  const descriptor = driver.targets && driver.targets[String(target || 'native').toLowerCase()];
+  if (!descriptor) throw new TypeError(`Unknown Pulse target ${String(target)} for provider ${driver.id}.`);
+  return descriptor;
+}
+
+function getProviderTargetSupportDeclaration(provider, target = 'native', options = {}) {
+  const driver = typeof provider === 'string' ? getProviderDriver(provider, options) : provider;
+  return driver.targetSupport && driver.targetSupport[String(target || 'native').toLowerCase()] || null;
+}
+
+function providerTargetAvailability(provider, options = {}) {
+  const driver = typeof provider === 'string' ? getProviderDriver(provider, options) : provider;
+  const native = driver.targets && driver.targets.native;
+  const javascript = driver.targets && driver.targets.javascript;
+  const javascriptSupport = getProviderTargetSupportDeclaration(driver, 'javascript');
+  return Object.freeze({
+    native: Boolean(native && ['supported', 'compile-only'].includes(native.status)),
+    javascript: javascriptSupport
+      ? javascriptSupport.availability.generalAvailable === true
+      : Boolean(javascript && javascript.status === 'supported'),
+    descriptors: Object.freeze({ native, javascript })
+  });
+}
+
+function providerIds(options = {}) {
+  return Object.freeze(BUILTIN_PROVIDER_IDS.filter((id) => (
+    options.executable !== true || getProviderDriver(id).executable === true
+  )));
+}
+
+function providerConfigReferences() {
+  return Object.freeze(BUILTIN_PROVIDER_IDS
+    .map((id) => getProviderDriver(id))
+    .filter((driver) => driver.configReference)
+    .map((driver) => driver.configReference));
+}
+
+const drivers = {};
+for (const id of BUILTIN_PROVIDER_IDS) {
+  Object.defineProperty(drivers, id, {
+    enumerable: true,
+    get() { return getProviderDriver(id); }
+  });
+}
+Object.freeze(drivers);
+
+module.exports = Object.freeze({
+  PROVIDER_PACKAGE_SCOPE,
+  PROVIDER_PACKAGE_PREFIX,
+  BUILTIN_PROVIDER_IDS,
+  drivers,
+  providerPackageName,
+  resolveProviderToolchain,
+  getProviderDriver,
+  getProviderTargetDescriptor,
+  getProviderTargetSupportDeclaration,
+  providerTargetAvailability,
+  providerIds,
+  providerConfigReferences
+});

package/src/spine/async-surface-normalizer.js

@@ -0,0 +1,328 @@
+'use strict';
+
+const ts = require('typescript');
+const {
+  HANDLER_AUTHORING_MODES
+} = require('@pulse-compute/wasm-contracts/handler/surface-contract');
+const {
+  recognizeHandlerSurface,
+  extractKvNamespaceDeclaration,
+  unwrapExpression
+} = require('./handler-surface-authority.js');
+const {
+  createCanonicalDiagnostic,
+  createHandlerDiagnostic
+} = require('./diagnostic-authority.js');
+
+const ASYNC_SURFACE_NORMALIZER_VERSION = 'pulse.async-surface-normalizer.v2';
+
+function warning(frontend, sourceFile, node, code, message, detail = {}) {
+  return createCanonicalDiagnostic({
+    frontend,
+    sourceFile,
+    node,
+    code,
+    message,
+    detail,
+    severity: 'warning'
+  });
+}
+
+function modifiersWithoutAsync(node) {
+  const current = node.modifiers || [];
+  const next = current.filter((modifier) => modifier.kind !== ts.SyntaxKind.AsyncKeyword);
+  return next.length === current.length ? node.modifiers : next;
+}
+
+function updateFunctionWithoutAsync(node, body) {
+  const modifiers = modifiersWithoutAsync(node);
+  if (ts.isFunctionDeclaration(node)) {
+    return ts.factory.updateFunctionDeclaration(node, modifiers, node.asteriskToken, node.name, node.typeParameters, node.parameters, node.type, body);
+  }
+  if (ts.isFunctionExpression(node)) {
+    return ts.factory.updateFunctionExpression(node, modifiers, node.asteriskToken, node.name, node.typeParameters, node.parameters, node.type, body);
+  }
+  if (ts.isArrowFunction(node)) {
+    return ts.factory.updateArrowFunction(node, modifiers, node.typeParameters, node.parameters, node.type, node.equalsGreaterThanToken, body);
+  }
+  if (ts.isMethodDeclaration(node)) {
+    return ts.factory.updateMethodDeclaration(node, modifiers, node.asteriskToken, node.name, node.questionToken, node.typeParameters, node.parameters, node.type, body);
+  }
+  return node;
+}
+
+function directReturnExpression(node) {
+  let current = node;
+  let parent = current && current.parent;
+  while (parent && (
+    ts.isParenthesizedExpression(parent)
+    || ts.isAsExpression(parent)
+    || ts.isSatisfiesExpression?.(parent)
+    || ts.isNonNullExpression(parent)
+    || ts.isTypeAssertionExpression(parent)
+  )) {
+    current = parent;
+    parent = current.parent;
+  }
+  return Boolean(parent && ts.isReturnStatement(parent) && parent.expression === current);
+}
+
+function resolveHandlerAuthoringMode(options = {}) {
+  const explicit = options.handlerAuthoring;
+  if (explicit !== undefined) {
+    if (!Object.values(HANDLER_AUTHORING_MODES).includes(explicit)) {
+      throw new TypeError(`Unknown Pulse handler authoring mode: ${explicit}`);
+    }
+    return explicit;
+  }
+  return options.requireAsync === true
+    ? HANDLER_AUTHORING_MODES.ASYNC_REQUIRED
+    : HANDLER_AUTHORING_MODES.SYNCHRONOUS_COMPATIBILITY;
+}
+
+function normalizeManagedHandler(functionNode, options = {}) {
+  if (!functionNode || !ts.isFunctionLike(functionNode)) throw new TypeError('normalizeManagedHandler requires a function-like node.');
+  const sourceFile = options.sourceFile;
+  const ctxName = options.ctxName || 'ctx';
+  const nextName = options.nextName;
+  const frontend = options.frontend || 'canonical-source';
+  const strict = options.strict !== false;
+  const handlerAuthoring = resolveHandlerAuthoringMode(options);
+  const requireAsync = handlerAuthoring === HANDLER_AUTHORING_MODES.ASYNC_REQUIRED;
+  const requireEffectAwait = options.requireEffectAwait === true;
+  const diagnostics = [];
+  const warnings = [];
+  const changes = [];
+  let kvAliases = new Map();
+  const awaitedRoots = new WeakSet();
+  const parallelMemberRoots = new WeakSet();
+  const userAuthoredAsync = (functionNode.modifiers || []).some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword);
+  const enforceEffectAwait = userAuthoredAsync || requireEffectAwait;
+  let awaitCount = 0;
+  let effectAwaitCount = 0;
+  let syncAwaitCount = 0;
+  let missingEffectAwaitCount = 0;
+
+  if (requireAsync && !userAuthoredAsync) {
+    diagnostics.push(createHandlerDiagnostic({
+      frontend,
+      issue: 'handler.async.required',
+      sourceFile,
+      node: functionNode,
+      values: { role: options.role || 'handler' },
+      detail: { role: options.role || 'handler', handlerAuthoring }
+    }));
+  }
+
+  function surfaceFor(node, position) {
+    return recognizeHandlerSurface(node, {
+      ctxName,
+      kvAliases,
+      nextName,
+      role: options.role,
+      strict,
+      packageEffectForCall: options.packageEffectForCall,
+      unwrap: true,
+      position
+    });
+  }
+
+  const transformer = (context) => {
+    function visit(node) {
+      if (ts.isBlock(node)) {
+        const inherited = kvAliases; kvAliases = new Map(inherited);
+        try { return ts.visitEachChild(node, visit, context); } finally { kvAliases = inherited; }
+      }
+      if (ts.isVariableStatement(node)) {
+        const namespace = extractKvNamespaceDeclaration(node, ctxName, { unwrap: true });
+        for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name)) kvAliases.delete(declaration.name.text);
+        if (namespace) kvAliases.set(namespace.variableName, namespace.store);
+      }
+      if (node !== functionNode && ts.isFunctionLike(node)) {
+        const nestedAsync = (node.modifiers || []).some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword);
+        if (nestedAsync) diagnostics.push(createHandlerDiagnostic({
+          frontend,
+          issue: 'handler.nested-async-function.unsupported',
+          sourceFile,
+          node
+        }));
+        return node;
+      }
+
+      if (ts.isAwaitExpression(node)) {
+        awaitCount += 1;
+        const inner = unwrapExpression(node.expression);
+        const surface = surfaceFor(inner, 'await-expression');
+        if (!surface || surface.surfaceId === 'javascript.await' || surface.class === 'javascript-only') {
+          // The explicit JavaScript project path uses this normalized tree only
+          // for inspection. Its original async source executes through the
+          // application loader; Native compilation still rejects this boundary.
+          if (options.target === 'javascript') return ts.visitNode(node.expression, visit);
+          diagnostics.push(createHandlerDiagnostic({
+            frontend,
+            issue: 'handler.await.native-unsupported',
+            sourceFile,
+            node,
+            values: { expression: inner && inner.getText ? inner.getText(sourceFile) : '<unknown>' },
+            detail: { selectedTarget: options.target || 'native', automaticFallback: false }
+          }));
+          return ts.visitNode(node.expression, visit);
+        }
+        awaitedRoots.add(inner);
+        if (surface.surfaceId === 'ctx.parallel') {
+          const record = surface.detail && surface.detail.parallel && surface.detail.parallel.record;
+          if (record && ts.isObjectLiteralExpression(record)) {
+            for (const property of record.properties) {
+              if (ts.isPropertyAssignment(property)) parallelMemberRoots.add(unwrapExpression(property.initializer));
+            }
+          }
+        }
+        if (surface.classification && surface.classification.ok === false) {
+          diagnostics.push(createCanonicalDiagnostic({
+            frontend,
+            sourceFile,
+            node,
+            code: surface.classification.code,
+            message: surface.classification.message,
+            detail: { surfaceId: surface.surfaceId, strict }
+          }));
+          return ts.visitNode(node.expression, visit);
+        }
+        if (surface.surfaceId === 'router.next') {
+          diagnostics.push(createCanonicalDiagnostic({
+            frontend,
+            sourceFile,
+            node,
+            code: 'PULSE_ROUTER_NEXT_TERMINAL',
+            message: 'next() is a terminal Router control transfer and must be returned directly.',
+            detail: { surfaceId: surface.surfaceId }
+          }));
+          return ts.visitNode(node.expression, visit);
+        }
+        if (surface.awaitPolicy === 'synchronous-statement-only') {
+          diagnostics.push(createCanonicalDiagnostic({
+            frontend,
+            sourceFile,
+            node,
+            code: 'PULSE_LOG_AWAIT_FORBIDDEN',
+            message: `${surface.surfaceId} is synchronous, returns void, and must not be awaited.`,
+            detail: { surfaceId: surface.surfaceId }
+          }));
+          return ts.visitNode(node.expression, visit);
+        }
+        if (surface.class === 'effect' || surface.class === 'package-owned') {
+          effectAwaitCount += 1;
+          changes.push(Object.freeze({ kind: 'effect-await-erased', surfaceId: surface.surfaceId }));
+          return ts.visitNode(node.expression, visit);
+        }
+        if (surface.class === 'sync') {
+          syncAwaitCount += 1;
+          warnings.push(warning(
+            frontend,
+            sourceFile,
+            node,
+            'PULSE_AWAIT_SYNC_REDUNDANT',
+            `await is redundant for synchronous Pulse surface ${surface.surfaceId}; native lowering erases it.`,
+            { surfaceId: surface.surfaceId }
+          ));
+          changes.push(Object.freeze({ kind: 'sync-await-erased', surfaceId: surface.surfaceId }));
+          return ts.visitNode(node.expression, visit);
+        }
+        diagnostics.push(createHandlerDiagnostic({
+          frontend,
+          issue: 'handler.await.native-unsupported',
+          sourceFile,
+          node,
+          values: { expression: inner && inner.getText ? inner.getText(sourceFile) : '<unknown>' }
+        }));
+        return ts.visitNode(node.expression, visit);
+      }
+
+      if (ts.isCallExpression(node)) {
+        const surface = surfaceFor(node, directReturnExpression(node) ? 'return' : 'expression');
+        if (surface) {
+          const awaited = awaitedRoots.has(unwrapExpression(node));
+          if (surface.classification && surface.classification.ok === false && !awaited) {
+            diagnostics.push(createCanonicalDiagnostic({
+              frontend,
+              sourceFile,
+              node,
+              code: surface.classification.code,
+              message: surface.classification.message,
+              detail: { surfaceId: surface.surfaceId, strict }
+            }));
+          } else if (surface.surfaceId === 'router.next') {
+            // Router terminal validation owns the exact return-position checks.
+          } else if (enforceEffectAwait && (surface.class === 'effect' || surface.class === 'package-owned')
+            && !awaitedRoots.has(unwrapExpression(node)) && !parallelMemberRoots.has(unwrapExpression(node))) {
+            const returnAdopted = directReturnExpression(node) && (
+              surface.awaitPolicy === 'return-adopted-or-required'
+              || (surface.class === 'package-owned' && surface.detail && surface.detail.packageEffect && surface.detail.packageEffect.placement === 'return')
+            );
+            if (!returnAdopted) {
+              missingEffectAwaitCount += 1;
+              diagnostics.push(createCanonicalDiagnostic({
+                frontend,
+                sourceFile,
+                node,
+                code: 'PULSE_EFFECT_AWAIT_REQUIRED',
+                message: `Pulse effect ${surface.surfaceId} must be awaited before its value is consumed.`,
+                detail: { surfaceId: surface.surfaceId, awaitPolicy: surface.awaitPolicy }
+              }));
+            }
+          }
+          if (surface.surfaceId === 'ctx.parallel') {
+            // The outer combinator owns its statically keyed effect members. Visiting
+            // those calls as independent expressions would incorrectly diagnose each
+            // member as a missing await before Handler IR can validate the group.
+            return node;
+          }
+          // The recognized call owns its receiver chain. Visit only arguments so nested
+          // effects in argument expressions still receive deterministic diagnostics.
+          const argumentsArray = node.arguments.map((argument) => ts.visitNode(argument, visit));
+          if (argumentsArray.every((argument, index) => argument === node.arguments[index])) return node;
+          return ts.factory.updateCallExpression(node, node.expression, node.typeArguments, argumentsArray);
+        }
+      }
+
+      return ts.visitEachChild(node, visit, context);
+    }
+
+    return (root) => {
+      const body = root.body ? ts.visitNode(root.body, visit) : root.body;
+      const updated = updateFunctionWithoutAsync(root, body);
+      if (updated !== root && userAuthoredAsync) changes.push(Object.freeze({ kind: 'async-wrapper-erased' }));
+      return updated;
+    };
+  };
+
+  const result = ts.transform(functionNode, [transformer]);
+  const transformed = result.transformed[0];
+  result.dispose();
+  const normalized = changes.length > 0 ? transformed : functionNode;
+
+  return Object.freeze({
+    version: ASYNC_SURFACE_NORMALIZER_VERSION,
+    functionNode: normalized,
+    diagnostics: Object.freeze(diagnostics),
+    warnings: Object.freeze(warnings),
+    summary: Object.freeze({
+      changed: changes.length > 0,
+      userAuthoredAsync,
+      handlerAuthoring,
+      requireAsync,
+      requireEffectAwait: enforceEffectAwait,
+      awaitCount,
+      effectAwaitCount,
+      syncAwaitCount,
+      missingEffectAwaitCount,
+      changes: Object.freeze(changes)
+    })
+  });
+}
+
+module.exports = Object.freeze({
+  ASYNC_SURFACE_NORMALIZER_VERSION,
+  resolveHandlerAuthoringMode,
+  normalizeManagedHandler
+});