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

package/src/codegen/local-harness-ts.js

@@ -0,0 +1,453 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { PACKAGE_VERSION, normalizeArtifact } = require('../diagnostics.js');
+const { collectExpectedSlots } = require('./execution-harness-ts.js');
+
+const LOCAL_HARNESS_VERSION = 'pulsewasm.local-harness.v1';
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function tsJson(value) {
+  return JSON.stringify(value, null, 2)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+}
+
+function header(file = 'local harness') {
+  return [
+    '/*',
+    ' * Generated by PulseWasm Phase 9D.',
+    ' * Do not edit by hand.',
+    ' *',
+    ` * This ${file} is generated from execution-plan.json + handler-bindings.json.`,
+    ' * It provides a local validation surface around the generated routing core.',
+    ' */',
+    ''
+  ].join('\n');
+}
+
+function makeFile(file, text) {
+  return {
+    file,
+    bytes: Buffer.byteLength(text, 'utf8'),
+    sha256: sha256(text),
+    text
+  };
+}
+
+function buildLocalHarnessSource(expectedSlots) {
+  return `${header()}import { match } from './dispatch'
+import { EXECUTION_ENTRIES, EXECUTION_SCOPES } from './execution-plan'
+import {
+  createExecutionContext,
+  execute,
+  executeLifecycle,
+  type ExecuteOptions,
+  type ExecutionContext,
+  type ExecutionResult,
+  type ExecutionTraceEvent
+} from './execution-harness'
+import { getHandlerBySlot, assertHandlerBindingCoverage, type PulseHandler } from './handler-slots'
+
+export const RESULT_NONE = 0 as const
+export const RESULT_TEXT = 1 as const
+export const RESULT_JSON = 2 as const
+export const RESULT_BINARY = 3 as const
+export const RESULT_EMPTY = 4 as const
+
+export const DEFAULT_STATUS_NOT_FOUND = 404 as const
+export const DEFAULT_STATUS_INTERNAL_ERROR = 500 as const
+export const DEFAULT_STATUS_NO_CONTENT = 204 as const
+
+export const DEFAULT_ERROR_NO_RESULT = 'PULSEWASM_NO_RESULT' as const
+export const DEFAULT_ERROR_NOT_FOUND = 'PULSEWASM_NOT_FOUND' as const
+export const DEFAULT_ERROR_UNHANDLED = 'PULSEWASM_UNHANDLED_ERROR' as const
+export const DEFAULT_ERROR_BROADCASTER_MISSING = 'PULSEWASM_BROADCASTER_MISSING' as const
+
+export type PulseResultKind =
+  | typeof RESULT_NONE
+  | typeof RESULT_TEXT
+  | typeof RESULT_JSON
+  | typeof RESULT_BINARY
+  | typeof RESULT_EMPTY
+
+export type PulseResultRef = {
+  readonly statusCode: number
+  readonly bodyRef: unknown
+  readonly headersRef: Map<string, string>
+  readonly kind: PulseResultKind
+  readonly code?: string
+  readonly message?: string
+}
+
+export type PulseLocalContext = ExecutionContext & {
+  state: Map<string, unknown>
+  result?: PulseResultRef
+  channels: string[]
+  broadcasts: LocalBroadcastRecord[]
+}
+
+export type LocalBroadcastRecord = {
+  readonly channels: readonly string[]
+  readonly routeIndex?: number
+  readonly routeName?: string
+  readonly value?: unknown
+}
+
+export type Broadcaster = (
+  channels: readonly string[],
+  ctx: PulseLocalContext,
+  detail: { readonly routeEntry?: unknown; readonly execution: ExecutionResult }
+) => unknown
+
+export type LocalHarnessOptions = Omit<ExecuteOptions, 'ctx'> & {
+  readonly ctx?: PulseLocalContext | ExecutionContext
+  readonly broadcaster?: Broadcaster
+}
+
+export type LocalLifecycleOptions = Omit<ExecuteOptions, 'ctx'> & {
+  readonly ctx?: PulseLocalContext | ExecutionContext
+}
+
+export type LocalHarnessRun = {
+  readonly status: 'ok' | 'not-found' | 'error' | 'contract-violation'
+  readonly result: PulseResultRef
+  readonly ctx: PulseLocalContext
+  readonly execution?: ExecutionResult
+  readonly trace: readonly ExecutionTraceEvent[]
+  readonly executedSlots: readonly number[]
+  readonly channels: readonly string[]
+  readonly broadcasts: readonly LocalBroadcastRecord[]
+}
+
+export const EXPECTED_LOCAL_HARNESS_SLOTS = ${tsJson(expectedSlots)} as const
+
+function ensureSync(value: unknown, label: string): void {
+  if (value && typeof (value as { then?: unknown }).then === 'function') {
+    throw new Error('PulseWasm Phase 9D local harness received a Promise from ' + label)
+  }
+}
+
+function emptyHeaders(): Map<string, string> {
+  return new Map<string, string>()
+}
+
+export function makeEmptyResult(statusCode: number = DEFAULT_STATUS_NO_CONTENT): PulseResultRef {
+  return { statusCode, bodyRef: undefined, headersRef: emptyHeaders(), kind: RESULT_EMPTY }
+}
+
+export function makeTextResult(body: string, statusCode: number = 200): PulseResultRef {
+  return { statusCode, bodyRef: String(body), headersRef: emptyHeaders(), kind: RESULT_TEXT }
+}
+
+export function makeJsonResult(body: unknown, statusCode: number = 200): PulseResultRef {
+  return { statusCode, bodyRef: body, headersRef: emptyHeaders(), kind: RESULT_JSON }
+}
+
+export function makeErrorResult(code: string, message: string, statusCode: number = DEFAULT_STATUS_INTERNAL_ERROR): PulseResultRef {
+  return { statusCode, bodyRef: message, headersRef: emptyHeaders(), kind: RESULT_TEXT, code, message }
+}
+
+function isPulseResultRef(value: unknown): value is PulseResultRef {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    typeof (value as PulseResultRef).statusCode === 'number' &&
+    typeof (value as PulseResultRef).kind === 'number'
+  )
+}
+
+export function normalizeResult(value: unknown, defaultStatus: number = 200): PulseResultRef {
+  if (isPulseResultRef(value)) return value
+  if (typeof value === 'string') return makeTextResult(value, defaultStatus)
+  if (value instanceof Uint8Array) return { statusCode: defaultStatus, bodyRef: value, headersRef: emptyHeaders(), kind: RESULT_BINARY }
+  if (value == null) return makeEmptyResult(defaultStatus)
+  return makeJsonResult(value, defaultStatus)
+}
+
+function errorMessage(error: unknown): string {
+  if (error && typeof error === 'object' && typeof (error as { message?: unknown }).message === 'string') return (error as { message: string }).message
+  return String(error ?? 'Unhandled PulseWasm error')
+}
+
+function errorCode(error: unknown): string {
+  if (error && typeof error === 'object' && typeof (error as { code?: unknown }).code === 'string') return (error as { code: string }).code
+  return DEFAULT_ERROR_UNHANDLED
+}
+
+function errorStatus(error: unknown): number {
+  if (error && typeof error === 'object' && typeof (error as { statusCode?: unknown }).statusCode === 'number') return (error as { statusCode: number }).statusCode
+  return DEFAULT_STATUS_INTERNAL_ERROR
+}
+
+export function normalizeErrorResult(error: unknown): PulseResultRef {
+  return makeErrorResult(errorCode(error), errorMessage(error), errorStatus(error))
+}
+
+export function createLocalContext(method: string, requestPath: string, extra: Record<string, unknown> = {}): PulseLocalContext {
+  const base = createExecutionContext(method, requestPath, extra) as PulseLocalContext
+  const providedState = (extra as { state?: unknown }).state
+  base.state = providedState instanceof Map ? providedState as Map<string, unknown> : new Map<string, unknown>()
+  base.channels = Array.isArray((extra as { channels?: unknown }).channels) ? Array.from((extra as { channels: string[] }).channels) : []
+  base.broadcasts = Array.isArray((extra as { broadcasts?: unknown }).broadcasts) ? Array.from((extra as { broadcasts: LocalBroadcastRecord[] }).broadcasts) : []
+  return base
+}
+
+function asLocalContext(method: string, requestPath: string, ctx?: PulseLocalContext | ExecutionContext): PulseLocalContext {
+  if (ctx) {
+    const local = ctx as PulseLocalContext
+    local.method = String(method || '').toUpperCase()
+    local.path = requestPath
+    if (!(local.state instanceof Map)) local.state = new Map<string, unknown>()
+    if (!Array.isArray(local.channels)) local.channels = []
+    if (!Array.isArray(local.broadcasts)) local.broadcasts = []
+    return local
+  }
+  return createLocalContext(method, requestPath)
+}
+
+function entryAt(index: number): any | undefined {
+  return (EXECUTION_ENTRIES as readonly any[])[index]
+}
+
+function scopeById(scopeId: number | null | undefined): any | undefined {
+  if (!Number.isInteger(scopeId)) return undefined
+  return (EXECUTION_SCOPES as readonly any[]).find((scope) => scope.id === scopeId)
+}
+
+function lastRouteEntryFromTrace(trace: readonly ExecutionTraceEvent[]): any | undefined {
+  for (let i = trace.length - 1; i >= 0; i -= 1) {
+    const event = trace[i]
+    if (event.kind !== 'enter' || event.phase !== 'normal') continue
+    const entry = entryAt(event.index)
+    if (entry && entry.kind === 'route') return entry
+  }
+  return undefined
+}
+
+function normalizeChannels(value: unknown): string[] {
+  if (typeof value === 'string') return value.length > 0 ? [value] : []
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === 'string' && item.length > 0)
+  return []
+}
+
+function resolveChannelsFromExecution(execution: ExecutionResult, ctx: PulseLocalContext, resolver: (slot: number) => PulseHandler | undefined): { channels: string[]; routeEntry?: unknown; error?: PulseResultRef } {
+  const routeEntry = lastRouteEntryFromTrace(execution.trace)
+  if (!routeEntry) return { channels: [] }
+  const scope = scopeById(routeEntry.scopeId)
+  const channel = scope?.channel || routeEntry.routePlan?.channel
+  if (!channel) return { channels: [], routeEntry }
+  if (channel.kind === 'static') return { channels: normalizeChannels(channel.value), routeEntry }
+  if (!Number.isInteger(channel.slot)) {
+    return { channels: [], routeEntry, error: makeErrorResult('PULSEWASM_CHANNEL_HANDLER_MISSING', 'Channel routing has no concrete handler slot.', DEFAULT_STATUS_INTERNAL_ERROR) }
+  }
+  const handler = resolver(channel.slot)
+  if (!handler) {
+    return { channels: [], routeEntry, error: makeErrorResult('PULSEWASM_CHANNEL_HANDLER_MISSING', 'Channel routing referenced a missing handler binding.', DEFAULT_STATUS_INTERNAL_ERROR) }
+  }
+  const value = handler(ctx)
+  ensureSync(value, 'channel handler ' + String(channel.name || channel.id || channel.slot))
+  return { channels: normalizeChannels(value), routeEntry }
+}
+
+function finalizeRun(status: LocalHarnessRun['status'], result: PulseResultRef, ctx: PulseLocalContext, execution?: ExecutionResult, channels: string[] = []): LocalHarnessRun {
+  ctx.result = result
+  ctx.channels = channels
+  return {
+    status,
+    result,
+    ctx,
+    execution,
+    trace: execution?.trace || ctx.trace || [],
+    executedSlots: execution?.executedSlots || [],
+    channels,
+    broadcasts: ctx.broadcasts
+  }
+}
+
+export function assertLocalHarnessBindingCoverage(expectedSlots: readonly number[] = EXPECTED_LOCAL_HARNESS_SLOTS): void {
+  assertHandlerBindingCoverage(expectedSlots)
+}
+
+export function executeRequest(method: string, requestPath: string, options: LocalHarnessOptions = {}): LocalHarnessRun {
+  const normalizedMethod = String(method || '').toUpperCase()
+  const ctx = asLocalContext(normalizedMethod, requestPath, options.ctx)
+  const resolver = options.getHandlerBySlot || getHandlerBySlot
+  let execution: ExecutionResult
+
+  try {
+    execution = execute(normalizedMethod, requestPath, { ...options, ctx, getHandlerBySlot: resolver })
+  } catch (error) {
+    return finalizeRun('error', normalizeErrorResult(error), ctx)
+  }
+
+  if (execution.status === 'not-found') {
+    return finalizeRun('not-found', makeErrorResult(DEFAULT_ERROR_NOT_FOUND, 'No route handled the request.', DEFAULT_STATUS_NOT_FOUND), ctx, execution)
+  }
+
+  if (execution.status === 'error') {
+    return finalizeRun('error', normalizeErrorResult(execution.error), ctx, execution)
+  }
+
+  if (execution.status === 'halt') {
+    return finalizeRun('contract-violation', makeErrorResult(DEFAULT_ERROR_NO_RESULT, 'Handler halted without result or continuation.', DEFAULT_STATUS_INTERNAL_ERROR), ctx, execution)
+  }
+
+  if (execution.status !== 'response') {
+    return finalizeRun('error', makeErrorResult(DEFAULT_ERROR_NO_RESULT, 'Dispatch completed without a response result.', DEFAULT_STATUS_INTERNAL_ERROR), ctx, execution)
+  }
+
+  const channelResolution = resolveChannelsFromExecution(execution, ctx, resolver)
+  if (channelResolution.error) return finalizeRun('error', channelResolution.error, ctx, execution)
+  const channels = channelResolution.channels
+  if (channels.length > 0) {
+    if (!options.broadcaster) {
+      return finalizeRun('error', makeErrorResult(DEFAULT_ERROR_BROADCASTER_MISSING, 'Channel routing resolved channels, but no broadcaster adaptor was provided.', DEFAULT_STATUS_INTERNAL_ERROR), ctx, execution, channels)
+    }
+    try {
+      const value = options.broadcaster(channels, ctx, { routeEntry: channelResolution.routeEntry, execution })
+      ensureSync(value, 'broadcaster adaptor')
+      ctx.broadcasts.push({ channels, routeIndex: (channelResolution.routeEntry as { index?: number } | undefined)?.index, routeName: (channelResolution.routeEntry as { handler?: { name?: string } } | undefined)?.handler?.name, value })
+    } catch (error) {
+      return finalizeRun('error', normalizeErrorResult(error), ctx, execution, channels)
+    }
+  }
+
+  return finalizeRun('ok', normalizeResult(execution.value, 200), ctx, execution, channels)
+}
+
+function executeLifecycleEvent(method: string, requestPath: string, event: 'connect' | 'disconnect', options: LocalLifecycleOptions = {}): LocalHarnessRun {
+  const normalizedMethod = String(method || '').toUpperCase()
+  const ctx = asLocalContext(normalizedMethod, requestPath, options.ctx)
+  const matched = match(normalizedMethod, requestPath)
+  if (!matched) {
+    return finalizeRun('not-found', makeErrorResult(DEFAULT_ERROR_NOT_FOUND, 'No route matched lifecycle request.', DEFAULT_STATUS_NOT_FOUND), ctx)
+  }
+  try {
+    const execution = executeLifecycle(matched, event, { ...options, ctx, getHandlerBySlot: options.getHandlerBySlot || getHandlerBySlot })
+    return finalizeRun('ok', makeEmptyResult(DEFAULT_STATUS_NO_CONTENT), ctx, execution)
+  } catch (error) {
+    return finalizeRun('error', normalizeErrorResult(error), ctx)
+  }
+}
+
+export function executeConnect(method: string, requestPath: string, options: LocalLifecycleOptions = {}): LocalHarnessRun {
+  return executeLifecycleEvent(method, requestPath, 'connect', options)
+}
+
+export function executeDisconnect(method: string, requestPath: string, options: LocalLifecycleOptions = {}): LocalHarnessRun {
+  return executeLifecycleEvent(method, requestPath, 'disconnect', options)
+}
+`;
+}
+
+function buildTypeScriptLocalHarness(dispatchTable, handlerBindings, executionHarness, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const diagnostics = [];
+  const executionPlan = options.executionPlan;
+
+  if (!handlerBindings) {
+    diagnostics.push({
+      pass: 'local-harness',
+      code: 'PULSEWASM_LOCAL_HARNESS_REQUIRES_HANDLER_BINDINGS',
+      severity: 'error',
+      message: 'The Phase 9D local harness requires generated handler slot bindings.',
+      hint: 'Enable --emit-handler-bindings or use --emit-local-harness, which implies handler bindings.',
+      loc: { file: '<local-harness>' }
+    });
+  }
+
+  if (!executionHarness) {
+    diagnostics.push({
+      pass: 'local-harness',
+      code: 'PULSEWASM_LOCAL_HARNESS_REQUIRES_EXECUTION_HARNESS',
+      severity: 'error',
+      message: 'The Phase 9D local harness requires the generated execution harness.',
+      hint: 'Use --emit-local-harness, which implies --emit-execution-harness.',
+      loc: { file: '<local-harness>' }
+    });
+  }
+
+  if (!executionPlan) {
+    diagnostics.push({
+      pass: 'local-harness',
+      code: 'PULSEWASM_LOCAL_HARNESS_REQUIRES_EXECUTION_PLAN',
+      severity: 'error',
+      message: 'The Phase 9D local harness requires execution-plan.json.',
+      hint: 'Run the execution-plan pass before generated local harness emission.',
+      loc: { file: '<local-harness>' }
+    });
+  }
+
+  const expectedSlots = collectExpectedSlots(dispatchTable, executionPlan);
+  const files = [makeFile('generated/local-harness.ts', buildLocalHarnessSource(expectedSlots))];
+
+  const artifact = normalizeArtifact({
+    version: LOCAL_HARNESS_VERSION,
+    generatedBy: options.generatedBy || PACKAGE_VERSION,
+    source: dispatchTable?.source,
+    dispatchTableVersion: dispatchTable?.version,
+    executionPlanVersion: executionPlan?.version,
+    handlerBindingsVersion: handlerBindings?.artifact?.version,
+    executionHarnessVersion: executionHarness?.artifact?.version,
+    policy: {
+      phase: '9D',
+      sourceOfTruth: 'execution-plan.json + generated execution harness + generated handler slot bindings',
+      usesOriginalRouter: false,
+      runsWasm: false,
+      emitsWasm: false,
+      resultAbi: 'PulseResultRef v1',
+      stateBag: 'Map',
+      broadcasterRequiredWhenChannelsResolve: true,
+      lifecycleEntrypoints: ['executeConnect', 'executeDisconnect'],
+      requestEntrypoint: 'executeRequest',
+      hostBindings: false,
+      highLevelPulseWrapper: false
+    },
+    resultAbi: {
+      version: 'pulsewasm.result-abi.v1',
+      fields: ['statusCode', 'bodyRef', 'headersRef', 'kind'],
+      kinds: {
+        RESULT_NONE: 0,
+        RESULT_TEXT: 1,
+        RESULT_JSON: 2,
+        RESULT_BINARY: 3,
+        RESULT_EMPTY: 4
+      }
+    },
+    fallthrough: {
+      normal: { statusCode: 404, code: 'PULSEWASM_NOT_FOUND' },
+      error: { statusCode: 500, code: 'PULSEWASM_UNHANDLED_ERROR' },
+      contractViolation: { statusCode: 500, code: 'PULSEWASM_NO_RESULT' },
+      broadcasterMissing: { statusCode: 500, code: 'PULSEWASM_BROADCASTER_MISSING' }
+    },
+    output: {
+      language: 'typescript',
+      module: 'esm',
+      files: files.map(({ file, bytes, sha256: hash }) => ({ file, bytes, sha256: hash }))
+    },
+    summary: {
+      entries: executionPlan?.summary?.entries || 0,
+      routes: executionPlan?.summary?.routes || 0,
+      errors: executionPlan?.summary?.errors || 0,
+      scopes: executionPlan?.summary?.scopes || 0,
+      expectedHandlerSlots: expectedSlots.length,
+      resultAbi: true,
+      mapState: true,
+      broadcasterAdaptor: true,
+      lifecycleEntrypoints: 2,
+      diagnostics: diagnostics.length
+    }
+  }, cwd);
+
+  return { version: LOCAL_HARNESS_VERSION, artifact, files, diagnostics };
+}
+
+module.exports = {
+  LOCAL_HARNESS_VERSION,
+  buildTypeScriptLocalHarness
+};

package/src/codegen/pulse-wrapper.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { PACKAGE_VERSION, normalizeArtifact, normalizeDiagnostic } = require('../diagnostics.js');
+
+const WRAPPER_INTEGRATION_VERSION = 'pulsewasm.wrapper-integration.v1';
+const PULSE_BUILD_OUTPUT_VERSION = 'pulsewasm.pulse-build-output.v1';
+const PULSE_DEV_RUNTIME_VERSION = 'pulsewasm.pulse-dev-runtime.v1';
+const PHASE = '13A';
+
+function sha256Text(text) { return crypto.createHash('sha256').update(String(text || ''), 'utf8').digest('hex'); }
+function makeFile(file, text) { return { file, text, bytes: Buffer.byteLength(text, 'utf8'), sha256: sha256Text(text) }; }
+function diagnostic(code, message, hint, details) {
+  return normalizeDiagnostic({ phase: 'pulse-wrapper', severity: 'error', code, message, hint, details, loc: { file: '<pulse-wrapper>' } });
+}
+function readOutputBuffer(output) { return output && output.file && fs.existsSync(output.file) ? fs.readFileSync(output.file) : undefined; }
+function writeTempFile(root, file, textOrBuffer) {
+  const abs = path.join(root, file);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, textOrBuffer);
+  return abs;
+}
+function jsonText(value) { return `${JSON.stringify(value, null, 2)}\n`; }
+function normalizeHeaders(headers) { return (headers || []).map((pair) => [String(pair[0]), String(pair[1])]); }
+
+function buildWrapperSource() {
+  return `/* Generated by PulseWasm Phase 13A.\n * High-level Pulse wrapper integration over the compiled-Wasm local runtime.\n */\n'use strict';\nconst fs = require('node:fs');\nconst path = require('node:path');\n\nfunction defineConfig(configOrFactory) { return configOrFactory; }\nfunction readJson(file) { return JSON.parse(fs.readFileSync(file, 'utf8')); }\nfunction defaultArtifactDir() { return path.resolve(__dirname, '../..'); }\nfunction artifactDirFrom(options) { return path.resolve(options && options.artifactDir ? options.artifactDir : defaultArtifactDir()); }\nfunction artifactPath(artifactDir, file) { return path.join(artifactDir, file); }\nfunction safeReadJson(artifactDir, file) { const target = artifactPath(artifactDir, file); return fs.existsSync(target) ? readJson(target) : undefined; }\n\nfunction createPulseBuildOutput(options = {}) {\n  const artifactDir = artifactDirFrom(options);\n  const resolvedConfig = safeReadJson(artifactDir, 'resolved-config.json');\n  const deploymentPosture = safeReadJson(artifactDir, 'deployment-posture.json');\n  const buildManifest = safeReadJson(artifactDir, 'build-manifest.json');\n  const artifacts = {\n    resolvedConfig: 'resolved-config.json',\n    deploymentPosture: 'deployment-posture.json',\n    compiledWasmRuntime: 'compiled-wasm-runtime.json',\n    compiledWasmHostRuntime: 'compiled-wasm-host-runtime.json',\n    compiledWasmNodeAdapter: 'compiled-wasm-node-adapter.json',\n    compiledWasmRuntimeSmoke: 'compiled-wasm-runtime-smoke.json',\n    wasm: 'generated/compiled-wasm-runtime/pulsewasm-compiled-runtime.wasm',\n    hostRuntime: 'generated/host/compiled-wasm-host-runtime.cjs',\n    nodeAdapter: 'generated/node/compiled-wasm-node-adapter.cjs'\n  };\n  return {\n    version: 'pulsewasm.pulse-build-output.runtime.v1',\n    artifactDir,\n    profile: resolvedConfig && resolvedConfig.profile,\n    runtime: resolvedConfig && resolvedConfig.runtime,\n    engine: deploymentPosture && deploymentPosture.engine,\n    handlerExecutionMode: resolvedConfig && resolvedConfig.runtime && resolvedConfig.runtime.handlerExecutionMode,\n    deploymentPosture,\n    buildManifest,\n    artifacts\n  };\n}\n\nfunction createPulseDevRuntime(options = {}) {\n  const artifactDir = artifactDirFrom(options);\n  const buildOutput = createPulseBuildOutput({ artifactDir });\n  const posture = options.deploymentPosture || buildOutput.deploymentPosture || { engine: 'wasm' };\n  if ((posture.engine || 'wasm') === 'js' && !options.allowJsEngine) {\n    const err = new Error('Pulse dev runtime refuses JS engine posture for the Wasm wrapper path.');\n    err.code = 'PULSEWASM_WRAPPER_ENGINE_MISMATCH';\n    throw err;\n  }\n  const hostRuntimePath = options.hostRuntimePath || artifactPath(artifactDir, buildOutput.artifacts.hostRuntime);\n  const nodeAdapterPath = options.nodeAdapterPath || artifactPath(artifactDir, buildOutput.artifacts.nodeAdapter);\n  const wasmPath = options.wasmPath || artifactPath(artifactDir, buildOutput.artifacts.wasm);\n  if (!fs.existsSync(hostRuntimePath)) { const err = new Error('Missing compiled-wasm host runtime artifact.'); err.code = 'PULSEWASM_WRAPPER_HOST_RUNTIME_MISSING'; throw err; }\n  if (!fs.existsSync(nodeAdapterPath)) { const err = new Error('Missing compiled-wasm Node adapter artifact.'); err.code = 'PULSEWASM_WRAPPER_NODE_ADAPTER_MISSING'; throw err; }\n  if (!fs.existsSync(wasmPath)) { const err = new Error('Missing compiled-wasm runtime .wasm artifact.'); err.code = 'PULSEWASM_WRAPPER_WASM_MISSING'; throw err; }\n  const { createPulseWasmCompiledHostRuntime } = require(hostRuntimePath);\n  const { createPulseWasmCompiledNodeAdapter, createNodeHandler, createNodeServer } = require(nodeAdapterPath);\n  const runtime = createPulseWasmCompiledHostRuntime({\n    wasmPath,\n    deploymentPosture: posture,\n    hostResponses: options.hostResponses\n  });\n  const nodeAdapter = createPulseWasmCompiledNodeAdapter({ runtime });\n  return {\n    version: 'pulsewasm.pulse-dev-runtime.runtime.v1',\n    engine: posture.engine || 'wasm',\n    handlerExecutionMode: 'compiled-wasm',\n    buildOutput,\n    runtime,\n    nodeAdapter,\n    executeRequest(input) { return runtime.executeRequest(input); },\n    executeConnect(input) { return runtime.executeConnect(input); },\n    executeDisconnect(input) { return runtime.executeDisconnect(input); },\n    createNodeHandler(options = {}) { return createNodeHandler(runtime, options); },\n    createNodeServer(options = {}) { return createNodeServer(runtime, options); },\n    close() { if (runtime.close) return runtime.close(); }\n  };\n}\n\nfunction createPulseNodeHandler(options = {}) {\n  return createPulseDevRuntime(options).createNodeHandler(options);\n}\n\nmodule.exports = {\n  defineConfig,\n  createPulseBuildOutput,\n  createPulseDevRuntime,\n  createPulseNodeHandler\n};\n`;
+}
+
+function buildMarkdown(artifact) {
+  const lines = [];
+  lines.push('# PulseWasm Phase 13A — High-Level Wrapper Integration');
+  lines.push('');
+  lines.push('The wrapper is a thin paved path over the existing compiled-Wasm local runtime. It consumes artifacts; it does not redefine extraction, handler lowering, sidecar semantics, effects, or platform behavior.');
+  lines.push('');
+  lines.push('## Locked config shape');
+  lines.push('');
+  lines.push('- Root config defines source topology only: `entry`, `rootRouter`, and `profiles`.');
+  lines.push('- `PULSE_PROFILE` / CLI profile selects the active profile.');
+  lines.push('- Profile `runtime` defines engine, handler execution mode, timeouts, payload, and capabilities.');
+  lines.push('- Profiles may not change route topology.');
+  lines.push('');
+  lines.push('## Wrapper exports');
+  for (const name of artifact.wrapper.exports) lines.push(`- \`${name}\``);
+  lines.push('');
+  lines.push('## Smoke');
+  lines.push(`- Checks: \`${artifact.summary.smokeChecks}\``);
+  lines.push(`- Failed checks: \`${artifact.summary.failedSmokeChecks}\``);
+  return `${lines.join('\n')}\n`;
+}
+
+function runWrapperSmoke({ wrapperSource, compiledWasmRuntime, resolvedConfig, deploymentPosture }) {
+  const checks = [];
+  const failedChecks = [];
+  function check(name, actual, expected) {
+    const passed = actual === expected;
+    const record = { name, actual, expected, passed };
+    checks.push(record);
+    if (!passed) failedChecks.push(record);
+  }
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsewasm-13a-wrapper-'));
+  try {
+    writeTempFile(tmp, 'generated/pulse/pulse-wrapper.cjs', wrapperSource);
+    for (const file of compiledWasmRuntime.files || []) writeTempFile(tmp, file.file, file.text);
+    for (const output of compiledWasmRuntime.outputFiles || []) {
+      const buffer = readOutputBuffer(output);
+      if (buffer) writeTempFile(tmp, output.file.replace(/^.*?generated\//, 'generated/'), buffer);
+    }
+    writeTempFile(tmp, 'resolved-config.json', jsonText(resolvedConfig));
+    writeTempFile(tmp, 'deployment-posture.json', jsonText(deploymentPosture));
+    writeTempFile(tmp, 'build-manifest.json', jsonText({ version: 'pulsewasm.wrapper-smoke-manifest.v1' }));
+    const wrapper = require(path.join(tmp, 'generated/pulse/pulse-wrapper.cjs'));
+    check('defineConfig_function', typeof wrapper.defineConfig, 'function');
+    check('createPulseBuildOutput_function', typeof wrapper.createPulseBuildOutput, 'function');
+    check('createPulseDevRuntime_function', typeof wrapper.createPulseDevRuntime, 'function');
+    const output = wrapper.createPulseBuildOutput({ artifactDir: tmp });
+    check('build_output_profile', output.profile, resolvedConfig.profile);
+    check('build_output_engine', output.engine, 'wasm');
+    check('build_output_handler_mode', output.handlerExecutionMode, 'compiled-wasm');
+    const dev = wrapper.createPulseDevRuntime({ artifactDir: tmp });
+    check('dev_runtime_engine', dev.engine, 'wasm');
+    check('dev_runtime_handler_mode', dev.handlerExecutionMode, 'compiled-wasm');
+    const schemaOk = dev.executeRequest({ method: 'POST', path: '/users', bodyText: '{"name":"Ada","age":37,"active":true}' });
+    check('schema_success_status', schemaOk.status, 201);
+    check('schema_success_kind', schemaOk.kind, 'json');
+    const schemaBad = dev.executeRequest({ method: 'POST', path: '/users', bodyText: '{"name":"Ada","age":"bad","active":true}' });
+    check('schema_error_status', schemaBad.status, 400);
+    const extension = dev.executeRequest({ method: 'GET', path: '/extension' });
+    check('extension_status', extension.status, 220);
+    const stream = dev.nodeAdapter.executeRequest({ method: 'GET', path: '/stream' });
+    check('stream_kind', stream.kind, 'stream');
+    check('stream_response_ref', stream.responseRef, 77);
+    check('no_js_handlers_required', dev.runtime.handlerExecutionMode, 'compiled-wasm');
+    try {
+      wrapper.createPulseDevRuntime({ artifactDir: tmp, deploymentPosture: { engine: 'js' } });
+      check('js_posture_rejected', false, true);
+    } catch (error) {
+      check('js_posture_rejected', error.code === 'PULSEWASM_WRAPPER_ENGINE_MISMATCH', true);
+    }
+  } catch (error) {
+    failedChecks.push({ name: 'wrapper_smoke_exception', actual: error && error.message ? error.message : String(error), expected: 'no exception', passed: false });
+  }
+  return { checks, failedChecks, tmp };
+}
+
+function buildPulseWrapperIntegration(inputs = {}, options = {}) {
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const resolvedConfig = options.resolvedConfig || inputs.resolvedConfig || {};
+  const compiledWasmRuntime = inputs.compiledWasmRuntime;
+  const deploymentPosture = inputs.deploymentPosture?.artifact || inputs.deploymentPosture || { engine: 'wasm', wasmOptimized: true };
+  const diagnostics = [];
+  if (!compiledWasmRuntime || !compiledWasmRuntime.artifact) {
+    diagnostics.push(diagnostic('PULSEWASM_WRAPPER_COMPILED_RUNTIME_REQUIRED', 'Phase 13A requires compiled-wasm-runtime.json.', 'Enable --emit-compiled-wasm-runtime before --emit-pulse-wrapper.'));
+  }
+  if ((resolvedConfig.version || '') !== 'pulsewasm.resolved-config.v2') {
+    diagnostics.push(diagnostic('PULSEWASM_WRAPPER_CONFIG_V2_REQUIRED', 'Phase 13A requires resolved-config.v2.', 'Use config with root entry/rootRouter/profiles and runtime settings under the selected profile.'));
+  }
+  const wrapperSource = buildWrapperSource();
+  let smoke = { checks: [], failedChecks: [] };
+  if (diagnostics.length === 0) {
+    smoke = runWrapperSmoke({ wrapperSource, compiledWasmRuntime, resolvedConfig, deploymentPosture });
+    if (smoke.failedChecks.length > 0) {
+      diagnostics.push(diagnostic('PULSEWASM_WRAPPER_SMOKE_FAILED', 'Pulse wrapper integration smoke checks failed.', 'Inspect wrapper-integration.json smoke checks.', { failedChecks: smoke.failedChecks }));
+    }
+  }
+
+  const buildOutput = normalizeArtifact({
+    version: PULSE_BUILD_OUTPUT_VERSION,
+    generatedBy,
+    phase: PHASE,
+    profile: resolvedConfig.profile,
+    entry: resolvedConfig.entry,
+    rootRouter: resolvedConfig.rootRouter,
+    runtime: resolvedConfig.runtime,
+    engine: deploymentPosture.engine || 'wasm',
+    handlerExecutionMode: resolvedConfig.runtime?.handlerExecutionMode || 'compiled-wasm',
+    artifacts: {
+      resolvedConfig: 'resolved-config.json',
+      deploymentPosture: 'deployment-posture.json',
+      compiledWasmRuntime: 'compiled-wasm-runtime.json',
+      wasm: 'generated/compiled-wasm-runtime/pulsewasm-compiled-runtime.wasm',
+      wrapper: 'generated/pulse/pulse-wrapper.cjs'
+    }
+  });
+  const devRuntime = normalizeArtifact({
+    version: PULSE_DEV_RUNTIME_VERSION,
+    generatedBy,
+    phase: PHASE,
+    engine: deploymentPosture.engine || 'wasm',
+    handlerExecutionMode: 'compiled-wasm',
+    nodeAdapter: true,
+    compiledWasmRuntime: true,
+    jsUserHandlerImports: false,
+    noAutomaticFallback: true,
+    summary: {
+      requestPathProven: diagnostics.length === 0,
+      schemaRouteProven: smoke.checks.some((check) => check.name === 'schema_success_status' && check.passed),
+      extensionRouteProven: smoke.checks.some((check) => check.name === 'extension_status' && check.passed),
+      streamRouteProven: smoke.checks.some((check) => check.name === 'stream_kind' && check.passed)
+    }
+  });
+  const artifact = normalizeArtifact({
+    version: WRAPPER_INTEGRATION_VERSION,
+    generatedBy,
+    phase: PHASE,
+    status: diagnostics.length === 0 ? 'ok' : 'error',
+    policy: {
+      wrapperIsThin: true,
+      consumesArtifacts: true,
+      redefinesSemantics: false,
+      platformAdapter: false,
+      automaticJsFallback: false,
+      configContract: 'root topology + profile runtime settings'
+    },
+    config: {
+      version: resolvedConfig.version,
+      entry: resolvedConfig.entry,
+      rootRouter: resolvedConfig.rootRouter,
+      profile: resolvedConfig.profile,
+      runtime: resolvedConfig.runtime,
+      selectedProfileFieldPresent: Object.prototype.hasOwnProperty.call(resolvedConfig, 'selectedProfile'),
+      profileSourceFieldPresent: Object.prototype.hasOwnProperty.call(resolvedConfig, 'profileSource')
+    },
+    wrapper: {
+      file: 'generated/pulse/pulse-wrapper.cjs',
+      exports: ['defineConfig', 'createPulseBuildOutput', 'createPulseDevRuntime', 'createPulseNodeHandler']
+    },
+    smoke,
+    summary: {
+      smokeChecks: smoke.checks.length,
+      failedSmokeChecks: smoke.failedChecks.length,
+      profile: resolvedConfig.profile,
+      engine: deploymentPosture.engine || 'wasm',
+      handlerExecutionMode: resolvedConfig.runtime?.handlerExecutionMode || 'compiled-wasm',
+      compiledWasmRuntime: Boolean(compiledWasmRuntime?.artifact),
+      nodeAdapterPath: true,
+      noJsHandlerImports: true,
+      automaticFallback: false
+    },
+    diagnostics
+  });
+  return {
+    artifact,
+    buildOutput,
+    devRuntime,
+    files: [
+      makeFile('generated/pulse/pulse-wrapper.cjs', wrapperSource),
+      makeFile('generated/host/pulse-wrapper-integration.md', buildMarkdown(artifact))
+    ],
+    diagnostics
+  };
+}
+
+module.exports = { buildPulseWrapperIntegration };

package/src/codegen/request-result-headers.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-host-runtime/compiler/request-result-headers');