@pulse-compute/provider-node 1.0.0-beta.4 → 1.0.0-beta.6

package/src/runtime/s3-reader.js

@@ -38,34 +38,57 @@ function abortable(promise, signal) {
   });
 }
 async function readS3(effect, options, lookup) {
-  const operation = effect.operation, put = operation === 'putText';
+  const operation = effect.operation, put = operation === 'putText', bodyRead = operation === 'getBody';
   const payload = effect.payload || {};
-  if (!['head', 'getText', 'putText'].includes(operation) || effect.kind !== `s3.${operation}` || effect.capability !== effect.kind
+  if (!['head', 'getText', 'putText', 'getBody'].includes(operation) || effect.kind !== `s3.${operation}` || effect.capability !== effect.kind
     || effect.package !== '@pulse-compute/s3' || effect.contractId !== 'pulse.s3' || effect.providerKind !== 's3') throw new TypeError('Invalid S3 package effect authority.');
   let dispatched = false, status;
-  const failure = (reason) => put ? protocol.putFailure(reason, dispatched, status) : protocol.failure(reason, status);
+  const failure = (reason) => bodyRead ? new Response(null, { status: reason === 'timeout' ? 504 : 502, headers: { 'x-pulse-s3-error': reason } }) : put ? protocol.putFailure(reason, dispatched, status) : protocol.failure(reason, status);
   if (options.signal && options.signal.aborted) throw options.signal.reason || new Error('Request cancelled.');
   const configured = typeof payload.binding === 'string' && options.s3 && Object.hasOwn(options.s3, payload.binding) && options.s3[payload.binding];
   let binding;
   try { binding = protocol.normalizeBinding(configured); } catch { return failure('configuration'); }
+  const timeoutMs = Math.min(binding.timeoutMs, options.requestBudget?.remainingMs() ?? Infinity);
   const controller = new AbortController();
   const onAbort = () => controller.abort(options.signal.reason);
   if (options.signal) options.signal.addEventListener('abort', onAbort, { once: true });
+  const bodyAbort = () => controller.abort(options.responseSignal.reason);
+  if (options.responseSignal) {
+    options.responseSignal.addEventListener('abort', bodyAbort, { once: true });
+    if (options.responseSignal.aborted) bodyAbort();
+  }
   let timedOut = false;
-  const deadline = performance.now() + binding.timeoutMs;
+  const deadline = performance.now() + timeoutMs;
   const check = () => {
+    if (!transferred) options.requestBudget?.check();
     if (performance.now() >= deadline) { timedOut = true; controller.abort(); }
     if (controller.signal.aborted) throw controller.signal.reason || new Error('S3 deadline expired.');
   };
-  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, binding.timeoutMs);
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
   const wait = async (value) => { const result = await abortable(Promise.resolve(value), controller.signal); check(); return result; };
-  let response;
+  let response, transferred = false, cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    clearTimeout(timer);
+    if (options.signal) options.signal.removeEventListener('abort', onAbort);
+    options.responseSignal?.removeEventListener('abort', bodyAbort);
+    controller.abort();
+    if (response) { try { response.close(); } catch {} }
+  };
   try {
     const key = protocol.encodeKey(payload.key);
     if (key === null) return failure('invalid-key');
+    let readOptions;
+    if (bodyRead) {
+      try { readOptions = protocol.normalizeBodyOptions({ method: payload.method, ...(payload.range === undefined ? {} : { range: payload.range }), ...(payload.ifNoneMatch === undefined ? {} : { ifNoneMatch: payload.ifNoneMatch }) }); }
+      catch { return failure('configuration'); }
+    }
     let body, contentType;
     if (put) {
-      if (typeof payload.text !== 'string' || !payload.text.isWellFormed()) return failure('invalid-text');
+      if (typeof payload.text !== 'string') return failure('invalid-text');
+      if (payload.text.length > binding.maxTextBytes) return failure('too-large');
+      if (!payload.text.isWellFormed()) return failure('invalid-text');
       body = protocol.bytes(payload.text);
       if (body.length > binding.maxTextBytes) return failure('too-large');
       try { contentType = protocol.normalizePutOptions({ contentType: payload.contentType }).contentType; }
@@ -85,7 +108,7 @@ async function readS3(effect, options, lookup) {
     if (!crypto || !Array.isArray(algorithms) || ['SHA-256', 'HMAC-SHA256'].some((algorithm) => !algorithms.some((entry) => entry.algorithm === algorithm && entry.available && entry.realization === realization))) return failure('configuration');
     let request;
     try {
-      request = await wait(protocol.signRequest({ binding, method: put ? 'PUT' : operation === 'head' ? 'HEAD' : 'GET', encodedKey: key, accessId, secret, token, now: Date.now(), body, contentType }, crypto));
+      request = await wait(protocol.signRequest({ binding, method: bodyRead ? readOptions.method : put ? 'PUT' : operation === 'head' ? 'HEAD' : 'GET', encodedKey: key, accessId, secret, token, now: Date.now(), body, contentType, readOptions }, crypto));
     } catch (error) { check(); return failure('configuration'); }
     check();
     // The send primitive may have side effects even if it throws synchronously.
@@ -95,6 +118,15 @@ async function readS3(effect, options, lookup) {
       : await originRequest(request, controller.signal);
     status = response.status;
     check();
+    if (bodyRead) {
+      let metadata;
+      try { metadata = protocol.bodyResponseMetadata(status, response.headers, readOptions, binding.maxTextBytes); }
+      catch (error) { return failure(error.message === 'too-large' ? 'too-large' : 'protocol'); }
+      if (!metadata.body) return new Response(null, { status, headers: metadata.headers });
+      const stream = boundedBody(response, metadata.byteLength, binding.maxTextBytes, controller.signal, check, cleanup);
+      transferred = true;
+      return new Response(stream, { status, headers: metadata.headers });
+    }
     const rejected = put ? protocol.putStatusResult(status) : protocol.statusResult(status);
     if (rejected && (!put || rejected.status === 'unknown')) return rejected;
     const metadata = protocol.metadataFromHeaders(response.headers, operation === 'head');
@@ -122,10 +154,42 @@ async function readS3(effect, options, lookup) {
     if (options.signal && options.signal.aborted) throw options.signal.reason || error;
     return failure(timedOut ? 'timeout' : status === undefined ? 'transport' : 'protocol');
   } finally {
-    clearTimeout(timer);
-    if (options.signal) options.signal.removeEventListener('abort', onAbort);
-    controller.abort();
-    if (response) { try { await response.close(); } catch {} }
+    if (!transferred) cleanup();
   }
 }
+function boundedBody(response, expected, maximum, signal, check, cleanup) {
+  const iterator = response.body?.[Symbol.asyncIterator]();
+  let total = 0, ended = false, abort;
+  const finish = () => { ended = true; signal.removeEventListener('abort', abort); cleanup(); };
+  return new ReadableStream({
+    start(controller) {
+      abort = () => {
+        if (ended) return;
+        controller.error(new Error('S3 body transfer aborted.'));
+        finish();
+      };
+      signal.addEventListener('abort', abort, { once: true });
+      if (signal.aborted) abort();
+    },
+    async pull(controller) {
+      try {
+        check();
+        const item = iterator ? await iterator.next() : { done: true };
+        if (ended) return;
+        check();
+        if (item.done) {
+          if (total !== expected) throw new Error('S3 body length mismatch.');
+          controller.close(); finish(); return;
+        }
+        if (!(item.value instanceof Uint8Array)) throw new Error('Invalid S3 body bytes.');
+        total += item.value.byteLength;
+        if (total > maximum || total > expected) throw new Error('S3 body exceeds its bound.');
+        controller.enqueue(item.value);
+      } catch {
+        if (!ended) { controller.error(new Error('S3 body transfer failed.')); finish(); }
+      }
+    },
+    cancel() { finish(); }
+  }, { highWaterMark: 0 });
+}
 module.exports = { readS3, originRequest };

package/src/server/build.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { instantiateCanonicalNativeModule } = require('@pulse-compute/wasm-host-runtime/runtime/canonical-native-host');
+const { createNodeProviderAdapter } = require('../runtime/canonical-api-runtime.js');
+const { assertNodeJavascriptApplication } = require('../javascript/runtime-host.js');
+
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+const stable = value => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+  ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
+
+function loadBuild(options) {
+  const root = fs.realpathSync(options.buildDir);
+  function file(name) {
+    if (typeof name !== 'string' || !name || path.isAbsolute(name) || name.split(/[\\/]/).includes('..')) throw new TypeError('Invalid Node build file path.');
+    const absolute = fs.realpathSync(path.join(root, name));
+    if (!absolute.startsWith(root + path.sep) || !fs.statSync(absolute).isFile()) throw new TypeError('Node build file escapes buildDir.');
+    return absolute;
+  }
+  const json = name => JSON.parse(fs.readFileSync(file(name), 'utf8'));
+  const build = json('pulse-build.json');
+  if (build.version !== 'pulse.project-execution.v10' || build.status !== 'built' || build.provider !== 'node' || build.configuredTarget !== options.target) throw new TypeError('Node build provider/target mismatch.');
+  const capabilities = options.target === 'native' ? build.program?.capabilities : build.targetSupport?.project?.capabilities?.filter(item => item.required).map(item => item.id);
+  if ((Array.isArray(capabilities) ? capabilities : []).some(id => ['response.output', 'request.body.forward', 'request.body.transform', 's3.getBody'].includes(id))) {
+    throw new TypeError('This build needs a stream/body launcher extension outside NODE-01.');
+  }
+  if (options.target === 'javascript') {
+    const manifest = json(build.application.sourcePackage);
+    if (manifest.version !== 'pulse.node-javascript-source-package.v2' || manifest.provider !== 'node' || manifest.target !== 'javascript' || manifest.plan.planHash !== build.application.planHash) throw new TypeError('Invalid Node JavaScript source package.');
+    for (const module of manifest.modules) {
+      if (sha256(fs.readFileSync(file(module.output))) !== module.outputSha256) throw new TypeError('Node JavaScript module hash mismatch.');
+    }
+    const application = assertNodeJavascriptApplication(require(file(manifest.package.entry)));
+    const schemaCodecs = manifest.schemas.active ? require(file(manifest.package.schemaCodecs)) : undefined;
+    return { application, schemaCodecs, identity: build.application.planHash };
+  }
+  const portable = build.portable;
+  const plan = json(portable.plan);
+  const unsigned = { ...plan }; delete unsigned.planHash;
+  if (plan.planHash !== portable.planHash || sha256(stable(unsigned)) !== plan.planHash) throw new TypeError('Node Native plan hash mismatch.');
+  const wasm = fs.readFileSync(file(portable.wasm.file));
+  if (wasm.length !== portable.wasm.bytes || sha256(wasm) !== portable.wasm.sha256) throw new TypeError('Node Native Wasm hash mismatch.');
+  const realizationArtifacts = portable.packageRealizationArtifacts.file ? json(portable.packageRealizationArtifacts.file) : [];
+  if (sha256(stable(realizationArtifacts)) !== portable.packageRealizationArtifacts.sha256) throw new TypeError('Node Native package artifact hash mismatch.');
+  const native = { wasm, plan, realizationArtifacts };
+  const preflight = instantiateCanonicalNativeModule(native, { providerAdapter: createNodeProviderAdapter(), ...options });
+  preflight.close();
+  return { native, identity: plan.planHash };
+}
+
+module.exports = { loadBuild };

package/src/server/config.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { normalizeRequestDuration } = require('@pulse-compute/runtime/host');
+
+const defaults = Object.freeze({
+  host: '127.0.0.1', port: 8787, readinessPath: '/_pulse/ready',
+  maxDurationMs: 10000, shutdownTimeoutMs: 10000, headersTimeoutMs: 10000,
+  keepAliveTimeoutMs: 5000, maxRequestBodyBytes: 65536, maxFetchBodyBytes: 65536,
+  maxEffects: 128, maxConcurrentRequests: 128, maxConnections: 512, networkFetch: false, strict: true
+});
+
+function normalizeOptions(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('Node launcher options are required.');
+  const allowed = new Set([...Object.keys(defaults), 'target', 'buildDir', 'config', 'secrets', 'kv']);
+  for (const key of Reflect.ownKeys(input)) {
+    if (!allowed.has(key)) throw new TypeError('Unknown Node launcher option.');
+    if (!Object.hasOwn(Object.getOwnPropertyDescriptor(input, key), 'value')) throw new TypeError('Node launcher options must be data properties.');
+  }
+  const options = { ...defaults, ...input };
+  if (!['native', 'javascript'].includes(options.target)) throw new TypeError('Explicit Node target native or javascript is required.');
+  if (typeof options.buildDir !== 'string' || !options.buildDir) throw new TypeError('Node launcher buildDir is required.');
+  if (typeof options.host !== 'string' || !options.host.trim()) throw new TypeError('Node launcher host must be nonempty.');
+  if (typeof options.strict !== 'boolean') throw new TypeError('Node launcher strict must be boolean.');
+  if (typeof options.networkFetch !== 'boolean') throw new TypeError('Node launcher networkFetch must be boolean.');
+  if (typeof options.readinessPath !== 'string' || !/^\/[A-Za-z0-9_/-]+$/.test(options.readinessPath) || options.readinessPath.includes('//')) {
+    throw new TypeError('Node launcher readinessPath must be a non-root absolute path without a query.');
+  }
+  for (const key of ['port', 'shutdownTimeoutMs', 'headersTimeoutMs', 'keepAliveTimeoutMs', 'maxRequestBodyBytes', 'maxFetchBodyBytes', 'maxEffects', 'maxConcurrentRequests', 'maxConnections']) {
+    const maximum = key === 'port' ? 65535 : key.endsWith('Ms') ? 30000 : key.endsWith('Bytes') ? 2097152 : 65536;
+    if (!Number.isSafeInteger(options[key]) || options[key] < (key === 'port' ? 0 : 1) || options[key] > maximum) throw new TypeError(`Invalid Node launcher ${key}.`);
+  }
+  normalizeRequestDuration(options.maxDurationMs);
+  if (options.maxDurationMs === undefined) throw new TypeError('Node launcher requires a finite maxDurationMs.');
+  for (const key of ['config', 'secrets']) {
+    const value = options[key] ?? {};
+    if (!value || typeof value !== 'object' || Array.isArray(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value))) throw new TypeError(`Node launcher ${key} must be a string record.`);
+    const entries = [];
+    for (const name of Reflect.ownKeys(value)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, name);
+      if (typeof name !== 'string' || !Object.hasOwn(descriptor, 'value') || typeof descriptor.value !== 'string') throw new TypeError(`Node launcher ${key} must be a string record.`);
+      entries.push([name, descriptor.value]);
+    }
+    options[key] = Object.freeze(Object.fromEntries(entries));
+  }
+  // JSON seed data is process-local reference KV, never a durable store.
+  if (options.kv !== undefined) {
+    if (!options.kv || typeof options.kv !== 'object' || Array.isArray(options.kv)) throw new TypeError('Node launcher kv must be an object.');
+    require('../runtime/conditional-kv.js').createNodeKvReference({ kv: options.kv });
+    options.kv = structuredClone(options.kv);
+  }
+  return Object.freeze(options);
+}
+
+module.exports = { normalizeOptions };

package/src/server/index.d.ts

@@ -0,0 +1,53 @@
+/** Host integration only. Pass an immutable trusted directory emitted by pulse build. */
+export interface NodeLauncherOptions {
+  target: 'native' | 'javascript';
+  buildDir: string;
+  /** Default 127.0.0.1. Set explicitly for container ingress. */
+  host?: string;
+  /** Default 8787; 0 requests an ephemeral port. */
+  port?: number;
+  /** Reserved GET/HEAD endpoint; default /_pulse/ready. */
+  readinessPath?: string;
+  /** One request budget across body admission, effects and response completion. 1–30000; default 10000. */
+  maxDurationMs?: number;
+  /** Drain grace period, 1–30000; default 10000. */
+  shutdownTimeoutMs?: number;
+  /** Header admission timeout, 1–30000; default 10000. */
+  headersTimeoutMs?: number;
+  /** Idle keep-alive timeout, 1–30000; default 5000. */
+  keepAliveTimeoutMs?: number;
+  /** Each 1–2097152; defaults 65536. */
+  maxRequestBodyBytes?: number;
+  maxFetchBodyBytes?: number;
+  /** Each 1–65536; defaults 128, 128, 512 respectively. */
+  maxEffects?: number;
+  maxConcurrentRequests?: number;
+  maxConnections?: number;
+  /** Explicit outbound fetch authorization; default false. */
+  networkFetch?: boolean;
+  /** Strict structured JSON policy; default true. Development profile values are not loaded. */
+  strict?: boolean;
+  config?: Readonly<Record<string, string>>;
+  secrets?: Readonly<Record<string, string>>;
+  /** In-memory reference KV seed. Reset on restart; no durability promise. */
+  kv?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}
+export interface NodeLauncherStatus {
+  readonly state: 'created' | 'starting' | 'ready' | 'draining' | 'stopped';
+  readonly target: 'native' | 'javascript';
+  readonly buildId: string;
+  readonly activeRequests: number;
+  readonly address: Readonly<{ host: string; port: number }> | null;
+}
+export interface NodeLauncherCloseResult {
+  readonly forced: boolean;
+  readonly abortedRequests: number;
+}
+export interface NodeLauncher {
+  /** Resolves after validated host initialization and successful listen. Idempotent while ready/starting. */
+  start(): Promise<NodeLauncherStatus>;
+  /** Immediately withdraws readiness, then drains. Does not install process handlers or call process.exit. */
+  close(): Promise<NodeLauncherCloseResult>;
+  status(): NodeLauncherStatus;
+}
+export function createNodeLauncher(options: NodeLauncherOptions): NodeLauncher;

package/src/server/index.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const http = require('node:http');
+const { Readable } = require('node:stream');
+const { createRequestBudget } = require('@pulse-compute/runtime/host');
+const { executeCanonicalNativeModule } = require('@pulse-compute/wasm-host-runtime/runtime/canonical-native-host');
+const { createNodeProviderAdapter } = require('../runtime/canonical-api-runtime.js');
+const { createNodeKvReference } = require('../runtime/conditional-kv.js');
+const { createNodeJavascriptHandler, nodeRequestToWebRequest, writeWebResponseToNode } = require('../javascript/node-adapter.js');
+const { statusForError } = require('../javascript/lifecycle.js');
+const { normalizeOptions } = require('./config.js');
+const { loadBuild } = require('./build.js');
+
+function safeError(response, error) {
+  if (response.destroyed) return;
+  if (response.headersSent) { response.destroy(); return; }
+  const status = statusForError(error);
+  response.writeHead(status, { 'content-type': 'text/plain; charset=utf-8', connection: 'close' });
+  response.end(status === 504 ? 'Gateway Timeout' : status === 413 ? 'Payload Too Large' : status === 400 ? 'Bad Request' : 'Internal Server Error');
+}
+
+function nativeHandler(build, options) {
+  const providerAdapter = createNodeProviderAdapter(options);
+  return async (request, response, signal) => {
+    const budget = createRequestBudget({ ...options, signal });
+    try {
+      const adapted = await budget.race(nodeRequestToWebRequest(request, { ...options, signal: budget.signal }));
+      const input = { method: adapted.method, url: adapted.request.url, headers: adapted.headerPairs,
+        body: adapted.request.body ? Buffer.from(await budget.race(adapted.request.arrayBuffer())) : undefined };
+      const execution = await executeCanonicalNativeModule(build.native, {
+        ...options, providerAdapter, request: input, requestBudget: budget, signal: budget.signal,
+        maxBodyBytes: options.maxRequestBodyBytes
+      });
+      const result = execution.response;
+      const suppressed = adapted.method === 'HEAD' || [204, 205, 304].includes(result.status);
+      let body = result.bodyStream ?? result.body ?? null;
+      if (suppressed && result.bodyStream) {
+        if (typeof body.cancel === 'function') await body.cancel();
+        else body.destroy?.();
+      }
+      if (body && typeof body.pipe === 'function') body = Readable.toWeb(body);
+      const webResponse = new Response(suppressed ? null : body, { status: result.status, headers: result.headers });
+      await writeWebResponseToNode(webResponse, response, { requestMethod: adapted.method, requestBudget: budget, signal: budget.signal });
+    } finally { budget.close(); }
+  };
+}
+
+/** Create a production HTTP lifecycle over one immutable, trusted pulse build. */
+function createNodeLauncher(input) {
+  const options = normalizeOptions(input);
+  let state = 'created', generation, starting, stopping, lastClose = Object.freeze({ forced: false, abortedRequests: 0 });
+  // Snapshot the build once; restart is a fresh host generation, not hot reload.
+  const build = loadBuild(options);
+  // Validate host bindings before entering any lifecycle transition.
+  const { createNodeJavascriptBindingCapabilities } = require('../javascript/bindings-adapter.js');
+  createNodeJavascriptBindingCapabilities(options);
+  function status() {
+    const address = generation?.server.address();
+    return Object.freeze({ state, target: options.target, buildId: build.identity,
+      activeRequests: generation?.active.size || 0,
+      address: address && typeof address === 'object' ? Object.freeze({ host: address.address, port: address.port }) : null });
+  }
+  function start() {
+    if (state === 'ready') return Promise.resolve(status());
+    if (state === 'starting') return starting;
+    if (state === 'draining') return Promise.reject(new Error('Node launcher is draining; await close before start.'));
+    state = 'starting';
+    const active = new Set(), sockets = new Set();
+    const execution = { ...options, kvReference: createNodeKvReference({ kv: structuredClone(options.kv || {}) }),
+      fetchImplementation: options.networkFetch ? globalThis.fetch : undefined,
+      liveFetch: options.networkFetch, schemaCodecs: build.schemaCodecs };
+    const javascript = options.target === 'javascript' ? createNodeJavascriptHandler(build.application, execution) : null;
+    const native = options.target === 'native' ? nativeHandler(build, execution) : null;
+    const current = { active, sockets, server: null, onIdle: null };
+    const server = http.createServer({
+      headersTimeout: options.headersTimeoutMs, requestTimeout: Math.max(options.maxDurationMs, options.headersTimeoutMs),
+      keepAliveTimeout: options.keepAliveTimeoutMs, maxHeaderSize: 16384
+    }, (request, response) => {
+      const reject = (code, message) => { response.writeHead(code, { connection: 'close', 'content-type': 'text/plain; charset=utf-8' }); response.end(message); };
+      const pathname = (request.url || '/').split('?')[0];
+      if (pathname === options.readinessPath) {
+        response.setHeader('cache-control', 'no-store');
+        response.setHeader('connection', 'close');
+        if (!['GET', 'HEAD'].includes(request.method)) { response.setHeader('allow', 'GET, HEAD'); reject(405, 'Method Not Allowed'); return; }
+        response.statusCode = state === 'ready' && generation === current ? 200 : 503;
+        response.end(request.method === 'HEAD' ? undefined : response.statusCode === 200 ? 'ready' : 'not ready');
+        return;
+      }
+      if (state !== 'ready' || generation !== current || active.size >= options.maxConcurrentRequests) { reject(503, 'Service Unavailable'); return; }
+      const controller = new AbortController();
+      active.add(controller);
+      const disconnect = () => controller.abort(new Error('Node launcher request disconnected.'));
+      const closed = () => { if (!response.writableFinished) disconnect(); };
+      request.once('aborted', disconnect); response.once('close', closed);
+      // Each invocation owns its own cancellation signal, including forced drain.
+      const run = javascript
+        ? javascript(request, response, controller.signal)
+        : native(request, response, controller.signal);
+      Promise.resolve(run).catch(error => safeError(response, error)).finally(() => {
+        request.removeListener('aborted', disconnect); response.removeListener('close', closed);
+        active.delete(controller); current.onIdle?.();
+      });
+    });
+    current.server = server; generation = current;
+    server.maxConnections = options.maxConnections;
+    server.on('connection', socket => { sockets.add(socket); socket.once('close', () => sockets.delete(socket)); });
+    // This listener remains after listen to prevent an unhandled server error.
+    server.on('error', () => { if (state === 'ready' && generation === current) void close(); });
+    starting = new Promise((resolve, reject) => {
+      const error = () => { server.removeListener('listening', ready); state = 'stopped'; reject(new Error('Node launcher could not listen.')); };
+      const ready = () => { server.removeListener('error', error); state = 'ready'; resolve(status()); };
+      server.once('error', error); server.once('listening', ready);
+      try { server.listen(options.port, options.host); } catch (cause) { server.removeListener('error', error); error(); }
+    });
+    return starting;
+  }
+  function close() {
+    if (state === 'starting') return starting.then(() => close(), () => lastClose);
+    if (state === 'draining') return stopping;
+    if (state === 'created' || state === 'stopped') { state = 'stopped'; return Promise.resolve(lastClose); }
+    state = 'draining';
+    const current = generation;
+    stopping = new Promise(resolve => {
+      let closed = false, finished = false;
+      const finish = result => {
+        if (finished) return;
+        finished = true; clearTimeout(timer); current.onIdle = null;
+        state = 'stopped'; lastClose = Object.freeze(result); resolve(lastClose);
+      };
+      const check = () => { if (closed && current.active.size === 0) finish({ forced: false, abortedRequests: 0 }); };
+      const timer = setTimeout(() => {
+        const abortedRequests = current.active.size;
+        for (const controller of current.active) controller.abort(new Error('Node launcher drain deadline exceeded.'));
+        for (const socket of current.sockets) socket.destroy();
+        finish({ forced: true, abortedRequests });
+      }, options.shutdownTimeoutMs);
+      current.onIdle = check;
+      current.server.close(() => { closed = true; check(); });
+      current.server.closeIdleConnections();
+    });
+    return stopping;
+  }
+  return Object.freeze({ start, close, status });
+}
+
+module.exports = { createNodeLauncher };

package/src/toolchain.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const path = require('node:path');
+const { PulseRuntimeContractError: portableForwardingError } = require('@pulse-compute/runtime/host');
 const {
   PROVIDER_DRIVER_VERSION,
   PROVIDER_TARGET_RESULT_VERSION,
@@ -36,7 +37,11 @@ function genericProviderConfig(value) {
   const input = value && typeof value === 'object' ? value : {};
   const bindings = input.bindings || {};
   if (Object.keys(bindings).some((key) => key !== 's3')) throw new TypeError('Unknown Node binding field.');
-  return Object.freeze({ kind: 'node', bindings: Object.freeze({ s3: require('./config/s3.js').normalizeNodeS3(bindings.s3) }), local: Object.freeze({}) });
+  const maxDurationMs = require('@pulse-compute/runtime/host').normalizeRequestDuration(input.maxDurationMs);
+  const bodyForwarding = require('./javascript/incoming-body.js').normalizeBodyForwarding(input.bodyForwarding, maxDurationMs);
+  const generatedOutput = require('./runtime/generated-output.js').normalizeGeneratedOutput(input.generatedOutput, maxDurationMs);
+  const bodyTransform = require('./runtime/body-transform.js').normalizeBodyTransform(input.bodyTransform, { generatedOutput, maxDurationMs, bodyForwarding });
+  return Object.freeze({ ...(bodyTransform ? { bodyTransform } : {}), kind: 'node', maxDurationMs, ...(generatedOutput ? { generatedOutput } : {}), ...(bodyForwarding ? { bodyForwarding } : {}), bindings: Object.freeze({ s3: require('./config/s3.js').normalizeNodeS3(bindings.s3) }), local: Object.freeze({}) });
 }
 
 function nodeRealization(nativeArtifact) {
@@ -68,6 +73,9 @@ function nodeRealization(nativeArtifact) {
 function targetSupportContext(_compiled, _project, declaration) {
   const gates = declaration.availability && declaration.availability.gates || [];
   return Object.freeze({
+    bodyTransform: Boolean(_project?.providerConfig?.bodyTransform),
+    generatedOutput: Boolean(_project?.providerConfig?.generatedOutput),
+    bodyForwarding: Boolean(_project?.providerConfig?.bodyForwarding),
     bindingsRedaction: gates.some((entry) => entry.id === 'bindings-redaction' && entry.status === 'satisfied'),
     gripRealized: gates.some((entry) => entry.id === 'grip-readiness' && entry.evidence && entry.evidence.status === 'passed')
   });
@@ -144,18 +152,22 @@ function createDriver() {
     normalizeConfig: genericProviderConfig,
     configReference: Object.freeze({
       sections: [{ id: 'node', title: 'Node provider options', description: 'Provider-owned Node profile configuration.' }],
-      fields: [{ section: 'node', path: 'node.bindings.s3', type: 'Readonly<Record<string, S3Binding>>', default: '`{}`', scope: 'Node Native and JavaScript S3',
-        description: 'Maps literal logical names to fixed HTTPS endpoint, bucket, region, accessKeyIdSecret, secretAccessKeySecret, optional sessionTokenSecret, maxTextBytes (1–32768, default 32768) and timeoutMs (1–30000, default 10000).',
+      fields: [{ section:'node', path:'node.bodyTransform', type:'boolean', default:'omitted', scope:'Experimental Node UTF-8 transforms', description:'Opt-in finite request text chunks. Requires generatedOutput and maxDurationMs; incompatible with bodyForwarding. Input 65536 bytes, output 262144 bytes, at most 4 times delivered input bytes. Strict UTF-8, one reader/writer, EOF required before output.close().' }, { section:'node', path:'node.generatedOutput', type:'boolean', default:'omitted', scope:'Experimental Node generated output', description:'Opt-in finite UTF-8 output. Requires node.maxDurationMs. Each write is at most 16384 bytes; at most 64 writes and 1048576 bytes total. Use STR-03B for exact-candidate installed qualification.' }, { section:'node', path:'node.bodyForwarding', type:'{ maxBytes: number }', default:'omitted', scope:'Node incoming forwarding', description:'Opt-in single-use incoming POST forwarding. maxBytes is a positive safe integer limiting each transfer direction; requires node.maxDurationMs. Pulse emits chunks up to 16384 bytes and retains at most 65536 bytes per pump. Native uses exact Wasm execution and excludes structured request reads in the same application.' }, { section:'node', path:'node.maxDurationMs', type:'integer', allowed:'1–30000', default:'omitted', scope:'HTTP request execution', description:'One provider-owned monotonic budget shared by request effects and continuations; expiry does not prove rollback of dispatched writes.' }, { section: 'node', path: 'node.bindings.s3', type: 'Readonly<Record<string, S3Binding>>', default: '`{}`', scope: 'Node Native and JavaScript S3',
+        description: 'Maps literal logical names to fixed HTTPS endpoint, bucket, region, accessKeyIdSecret, secretAccessKeySecret, optional sessionTokenSecret, maxTextBytes (1–2097152, default 32768) and timeoutMs (1–30000, default 10000).',
         security: 'Only named credential references are configuration. Runtime keys cannot override authority.' }]
     }),
     defaultLocalNetworkFetch: true,
-    projectConfigDocument(config) { return Object.keys(config.bindings.s3).length ? config : undefined; },
+    projectConfigDocument(config) { return (Object.keys(config.bindings.s3).length || config.maxDurationMs !== undefined) ? config : undefined; },
     initTemplate() {
       return Object.freeze({ profileFragment: '', dependencies: Object.freeze({}) });
     },
     executionOptions(config, values) {
       return Object.freeze({
         ...values,
+        maxDurationMs: config.maxDurationMs,
+        generatedOutput: config.generatedOutput,
+        bodyTransform: config.bodyTransform,
+        bodyForwarding: config.bodyForwarding,
         s3: config.bindings.s3,
         s3FetchImplementation: values.s3FetchImplementation || require('./javascript/fetch-adapter.js').createNodeJavascriptFixtureFetch(
           values.fetches || {}, values.fetchImplementation || (values.liveFetch === true ? globalThis.fetch : undefined),
@@ -220,11 +232,17 @@ function createDriver() {
     }),
     execute: nodeRuntime.executeCanonicalProgram,
     prepareNativeExecution(invocation) {
-      const { executeCanonicalNativeModule } = require('@pulse-compute/wasm-host-runtime/runtime/canonical-native-host');
       const native = { ...invocation.nativeArtifact, plan: invocation.applicationPlan };
-      return (options) => executeCanonicalNativeModule(native, options);
+      return (options) => require('./runtime/generated-output-test.js').executeNative(native, options, require('./runtime/incoming-body.js').executeNativeWithIncomingBody);
     },
+    createGeneratedOutput: require('./runtime/generated-output.js').createGeneratedOutput,
+    prepareNativeRequest: require('./runtime/incoming-body.js').prepareNativeRequest,
     createLoweringPlan(metadata, config = {}) {
+      if (metadata.capabilities?.includes('request.body.transform') && !config.bodyTransform) throw new portableForwardingError('PULSE_TRANSFORM_UNAVAILABLE', 'Configure node.bodyTransform, node.generatedOutput and node.maxDurationMs.');
+      if (metadata.capabilities?.includes('response.output') && !config.generatedOutput) throw new portableForwardingError('PULSE_OUTPUT_UNAVAILABLE', 'Configure node.generatedOutput and node.maxDurationMs.');
+      if (metadata.capabilities?.includes('request.body.forward')) {
+        if (!config.bodyForwarding) throw new portableForwardingError('PULSE_REQUEST_FORWARDING_UNAVAILABLE', 'Configure node.bodyForwarding and node.maxDurationMs.');
+      }
       require('./config/s3.js').validateNodeS3Operations(metadata, config.bindings || {});
       return canonicalProvider.createProviderLoweringPlan(metadata, nodeRuntime.NODE_PROVIDER_DESCRIPTOR, {
         grip: 'node-reference-broadcaster'