@pulse-compute/wasm-host-runtime 0.0.0 → 1.0.0-beta.1

package/src/compiler/streaming-passthrough.js

@@ -0,0 +1,212 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { getDefaultArtifactsDir } = require('@pulse-compute/wasm-build-support/artifacts-dir');
+const crypto = require('node:crypto');
+const { PACKAGE_VERSION, normalizeArtifact, normalizeDiagnostic } = require('@pulse-compute/wasm-contracts/diagnostics');
+const {
+  STREAMING_PASSTHROUGH_VERSION,
+  STREAM_RESULT_ABI_VERSION,
+  RESPONSE_PASSTHROUGH_POLICY_VERSION,
+  STREAMING_PHASE,
+  STREAMING_SMOKE_VERSION,
+  streamResultAbiFields,
+  responsePassthroughPolicyFields
+} = loadContractsStreamingPassthrough();
+
+function loadContractsStreamingPassthrough() {
+  try {
+    return require('@pulse-compute/wasm-contracts/host/streaming-passthrough');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/host/streaming-passthrough.js');
+    }
+    throw error;
+  }
+}
+
+function diagnosticFromParts(parts) {
+  return normalizeDiagnostic({ severity: 'error', loc: { file: '<generated>' }, ...parts });
+}
+
+function sha256Text(text) { return crypto.createHash('sha256').update(text, 'utf8').digest('hex'); }
+function sha256Buffer(buffer) { return crypto.createHash('sha256').update(buffer).digest('hex'); }
+
+function headerValues(headers, name) {
+  const lower = String(name).toLowerCase();
+  return (headers || []).filter(([key]) => String(key).toLowerCase() === lower).map(([, value]) => value);
+}
+
+function buildMarkdown(artifact) {
+  const lines = [];
+  lines.push('# PulseWasm Streaming / Response Pass-through ABI v1');
+  lines.push('');
+  lines.push(`Generated by: \`${artifact.generatedBy}\``);
+  lines.push(`Phase: \`${artifact.policy.phase}\``);
+  lines.push('');
+  lines.push('## Locked positions');
+  lines.push('');
+  for (const item of artifact.lockedPositions) lines.push(`- ${item}`);
+  lines.push('');
+  lines.push('## Result kinds');
+  lines.push('');
+  for (const [name, value] of Object.entries(artifact.resultKinds)) lines.push(`- \`${name} = ${value}\``);
+  lines.push('');
+  lines.push('## ABI');
+  lines.push('');
+  for (const item of artifact.streamResultAbi.exports) lines.push(`- \`${item}\``);
+  lines.push('');
+  lines.push('## Header merge policy');
+  lines.push('');
+  for (const item of artifact.responsePassthroughPolicy.headerMergeRules) lines.push(`- ${item}`);
+  lines.push('');
+  lines.push('## Non-goals');
+  lines.push('');
+  for (const item of artifact.nonGoals) lines.push(`- ${item}`);
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function makeStreamResultAbi({ generatedBy, wasmHostAbi }) {
+  return normalizeArtifact({
+    version: STREAM_RESULT_ABI_VERSION,
+    generatedBy,
+    ...streamResultAbiFields({ sourceWasmHostAbiVersion: wasmHostAbi?.artifact?.version })
+  });
+}
+
+function makeResponsePassthroughPolicy({ generatedBy }) {
+  return normalizeArtifact({
+    version: RESPONSE_PASSTHROUGH_POLICY_VERSION,
+    generatedBy,
+    ...responsePassthroughPolicyFields()
+  });
+}
+
+function runStreamingSmoke({ hostRuntimeKernel, nodeAdapter, wasmPath, wasmHostAbi, deploymentPosture }) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsewasm-streaming-'));
+  const hostDir = path.join(tempDir, 'host');
+  const nodeDir = path.join(tempDir, 'node');
+  fs.mkdirSync(hostDir, { recursive: true });
+  fs.mkdirSync(nodeDir, { recursive: true });
+  fs.writeFileSync(path.join(hostDir, 'host-runtime-kernel.cjs'), hostRuntimeKernel.files.find((file) => file.file === 'generated/host/host-runtime-kernel.cjs').text, 'utf8');
+  fs.writeFileSync(path.join(nodeDir, 'node-adapter.cjs'), nodeAdapter.files.find((file) => file.file === 'generated/node/node-adapter.cjs').text, 'utf8');
+  const hostModule = require(path.join(hostDir, 'host-runtime-kernel.cjs'));
+  const nodeModule = require(path.join(nodeDir, 'node-adapter.cjs'));
+
+  const observed = { streamHandlerCalled: 0 };
+  const handlers = {
+    auth(ctx) { ctx.next(); },
+    gateway(ctx) { ctx.next(); },
+    realtimeHandler(ctx) { ctx.text(200, `realtime:${ctx.param('id')}`); },
+    computeHandler(ctx) {
+      observed.streamHandlerCalled += 1;
+      ctx.responseHeader.delete('Server');
+      ctx.responseHeader.set('Cache-Control', 'public, max-age=120');
+      ctx.responseHeader.append('Grip-Channel', 'asset:override');
+      return {
+        kind: 'response',
+        response: {
+          status: 206,
+          headers: [
+            ['Content-Type', 'application/octet-stream'],
+            ['Cache-Control', 'public, max-age=60'],
+            ['Grip-Channel', 'asset'],
+            ['Grip-Channel', 'asset:42'],
+            ['Server', 'origin']
+          ],
+          bodyStream: { kind: 'mock-stream', chunks: ['asset:', '42'] }
+        }
+      };
+    },
+    bundleChannel() { return 'bundleChannel'; },
+    onConnect() {},
+    onDisconnect() {}
+  };
+
+  const runtime = hostModule.createPulseWasmHostRuntime({ wasmPath, wasmHostAbi, deploymentPosture, handlers, broadcaster: { broadcast() {} } });
+  const streamResult = runtime.executeRequest({ method: 'POST', path: '/compute/42' });
+  const res = { statusCode: 0, headers: [], body: '', setHeader(name, value) { if (Array.isArray(value)) for (const item of value) this.headers.push([name, item]); else this.headers.push([name, value]); }, write(chunk) { this.body += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk); }, end(body) { if (body !== undefined) this.write(body); } };
+  nodeModule.writeNodeResponse(res, streamResult);
+
+  const checks = [
+    { name: 'stream_result_kind', expected: 'stream', actual: streamResult.kind },
+    { name: 'stream_result_status', expected: 206, actual: streamResult.status },
+    { name: 'stream_handler_called', expected: 1, actual: observed.streamHandlerCalled },
+    { name: 'stream_body_not_copied_to_wasm', expected: 1, actual: streamResult.body === undefined ? 1 : 0 },
+    { name: 'node_stream_body_forwarded', expected: 'asset:42', actual: res.body },
+    { name: 'backend_content_type_preserved', expected: 'application/octet-stream', actual: headerValues(streamResult.headers, 'Content-Type')[0] },
+    { name: 'cache_control_overridden', expected: 'public, max-age=120', actual: headerValues(streamResult.headers, 'Cache-Control')[0] },
+    { name: 'server_deleted', expected: 0, actual: headerValues(streamResult.headers, 'Server').length },
+    { name: 'grip_channel_repeated_preserved', expected: 3, actual: headerValues(streamResult.headers, 'Grip-Channel').length },
+    { name: 'result_stream_ref_visible', expected: 1, actual: streamResult.responseRef > 0 || streamResult.streamRef > 0 ? 1 : 0 }
+  ].map((check) => ({ ...check, status: check.actual === check.expected ? 'ok' : 'error', message: check.actual === check.expected ? undefined : `Expected ${check.expected}, got ${check.actual}.` }));
+  return { version: STREAMING_SMOKE_VERSION, generatedBy: PACKAGE_VERSION, checks, failedChecks: checks.filter((check) => check.status !== 'ok'), summary: { executed: true, checks: checks.length, failedChecks: checks.filter((check) => check.status !== 'ok').length }, streamResult: { status: streamResult.status, kind: streamResult.kind, headers: streamResult.headers, responseRef: streamResult.responseRef, streamRef: streamResult.streamRef }, nodeResponse: { statusCode: res.statusCode, headers: res.headers, body: res.body } };
+}
+
+function buildStreamingPassthrough({ wasmHostAbi, wasmHostBridge, hostRuntimeKernel, nodeAdapter, requestResultHeaders }, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const outDir = options.outDir || getDefaultArtifactsDir(cwd);
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const diagnostics = [];
+  if (!wasmHostAbi || !wasmHostAbi.artifact) diagnostics.push(diagnosticFromParts({ phase: 'streaming-passthrough', code: 'PULSEWASM_STREAMING_ABI_REQUIRED', message: 'Phase 12D requires wasm-host-abi.json.', hint: 'Enable --emit-wasm-host-abi.' }));
+  if (!wasmHostBridge || !wasmHostBridge.artifact) diagnostics.push(diagnosticFromParts({ phase: 'streaming-passthrough', code: 'PULSEWASM_STREAMING_BRIDGE_REQUIRED', message: 'Phase 12D requires wasm-host-bridge.json.', hint: 'Enable --emit-wasm-host-bridge.' }));
+  if (!hostRuntimeKernel || !hostRuntimeKernel.artifact) diagnostics.push(diagnosticFromParts({ phase: 'streaming-passthrough', code: 'PULSEWASM_STREAMING_HOST_RUNTIME_REQUIRED', message: 'Phase 12D requires host-runtime-kernel.json.', hint: 'Enable --emit-host-runtime-kernel.' }));
+  if (!nodeAdapter || !nodeAdapter.artifact) diagnostics.push(diagnosticFromParts({ phase: 'streaming-passthrough', code: 'PULSEWASM_STREAMING_NODE_ADAPTER_REQUIRED', message: 'Phase 12D requires node-adapter.json.', hint: 'Enable --emit-node-adapter.' }));
+  const wasmFile = path.join(outDir, 'generated/wasm-bridge/pulsewasm-host-bridge.wasm');
+  if (!fs.existsSync(wasmFile)) diagnostics.push(diagnosticFromParts({ phase: 'streaming-passthrough', code: 'PULSEWASM_STREAMING_WASM_NOT_FOUND', message: 'Phase 12D expected the host bridge Wasm file to exist.', details: { wasmFile } }));
+
+  const streamResultAbi = makeStreamResultAbi({ generatedBy, wasmHostAbi });
+  const responsePassthroughPolicy = makeResponsePassthroughPolicy({ generatedBy });
+  let smoke;
+  if (diagnostics.length === 0) {
+    try {
+      smoke = runStreamingSmoke({ hostRuntimeKernel, nodeAdapter, wasmPath: wasmFile, wasmHostAbi: wasmHostAbi.artifact, deploymentPosture: options.deploymentPosture?.artifact || options.deploymentPosture || { engine: 'wasm' } });
+      if (smoke.failedChecks.length > 0) diagnostics.push(diagnosticFromParts({ phase: 'streaming-passthrough', code: 'PULSEWASM_STREAMING_SMOKE_FAILED', message: 'Phase 12D streaming/pass-through smoke failed.', details: { failedChecks: smoke.failedChecks } }));
+    } catch (error) {
+      diagnostics.push(diagnosticFromParts({ phase: 'streaming-passthrough', code: 'PULSEWASM_STREAMING_SMOKE_EXECUTION_FAILED', message: 'Phase 12D streaming/pass-through smoke execution failed.', details: { message: error && error.message ? error.message : String(error), stack: error && error.stack ? error.stack : undefined } }));
+    }
+  }
+
+  const artifact = normalizeArtifact({
+    version: STREAMING_PASSTHROUGH_VERSION,
+    generatedBy,
+    status: diagnostics.length ? 'error' : 'ok',
+    sourceWasmHostAbiVersion: wasmHostAbi?.artifact?.version,
+    sourceWasmHostBridgeVersion: wasmHostBridge?.artifact?.version,
+    sourceHostRuntimeKernelVersion: hostRuntimeKernel?.artifact?.version,
+    sourceNodeAdapterVersion: nodeAdapter?.artifact?.version,
+    policy: { phase: STREAMING_PHASE, sourceOfTruth: 'stream-result-abi.json + response-passthrough-policy.json + host runtime stream smoke', platformBindings: false, assetSemantics: false, binaryBufferAbi: false, requestBodyParsing: false },
+    lockedPositions: [
+      'RESULT_STREAM is implemented as the primary payload pass-through primitive.',
+      'RESULT_BINARY remains reserved as an edge-case finite buffer path.',
+      'Host owns stream bytes; Wasm owns opaque response/stream refs only.',
+      'pulse_result_from_response(ctxRef, responseRef) is the primary pass-through primitive.',
+      'pulse_result_stream(ctxRef, statusCode, streamRef) is the secondary explicit stream primitive.',
+      'Response pass-through preserves backend headers, applies set/append/delete mutations, and preserves repeated headers.',
+      'Request body parsing and binary request parsing remain untouched.'
+    ],
+    resultKinds: streamResultAbi.resultKinds,
+    streamResultAbi,
+    responsePassthroughPolicy,
+    smoke: smoke || { checks: [], failedChecks: [] },
+    nonGoals: [
+      'No pulse.assets implementation.',
+      'No binary request parsing.',
+      'No user-authored Uint8Array DSL.',
+      'No range requests.',
+      'No compression.',
+      'No cache metadata engine.',
+      'No streaming JSON parser.',
+      'No GRIP implementation.',
+      'No platform adapters.'
+    ],
+    summary: { streamImplemented: true, binaryReserved: true, smokeExecuted: Boolean(smoke), checks: smoke?.checks?.length || 0, failedChecks: smoke?.failedChecks?.length || 0, failedSmokeChecks: smoke?.failedChecks?.length || 0, hostOwnsStream: true, wasmOwnsBytes: false, assetsImplemented: false, platformBindings: false, nodeAdapterStreamForwarding: Boolean(smoke && smoke.nodeResponse && smoke.nodeResponse.body === 'asset:42'), streamBody: smoke?.nodeResponse?.body, diagnostics: diagnostics.length }
+  }, cwd);
+
+  return { artifact, streamResultAbi, responsePassthroughPolicy, smoke: smoke || { checks: [], failedChecks: [] }, files: [{ file: 'generated/host/streaming-passthrough.md', text: buildMarkdown(artifact) }], diagnostics: diagnostics.map((diag, index) => normalizeDiagnostic(diag, index)) };
+}
+
+module.exports = { STREAMING_PASSTHROUGH_VERSION, STREAM_RESULT_ABI_VERSION, RESPONSE_PASSTHROUGH_POLICY_VERSION, STREAMING_SMOKE_VERSION, buildStreamingPassthrough };

package/src/compiler/wasm-host-abi.js

@@ -0,0 +1,314 @@
+'use strict';
+
+const { PACKAGE_VERSION, normalizeArtifact } = require('@pulse-compute/wasm-contracts/diagnostics');
+const {
+  ABI_VERSION,
+  ABI_PHASE,
+  METHOD_CODES,
+  RESULT_KINDS,
+  NEXT_OUTCOMES,
+  buildWasmHostAbiExportGroups,
+  flattenWasmHostAbiExports
+} = loadContractsWasmHostAbi();
+
+function loadContractsWasmHostAbi() {
+  try {
+    return require('@pulse-compute/wasm-contracts/host/wasm-host-abi');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/host/wasm-host-abi.js');
+    }
+    throw error;
+  }
+}
+
+function roleSignature(role) {
+  if (role === 'error') return '(errRef: i32, ctxRef: i32, nextRef: i32) -> void';
+  if (role === 'channel') return '(ctxRef: i32) -> i32';
+  return '(ctxRef: i32, nextRef: i32) -> void';
+}
+
+function primaryRole(slot) {
+  const roles = slot.roles || [];
+  if (roles.includes('error')) return 'error';
+  if (roles.includes('channel')) return 'channel';
+  if (roles.includes('route')) return 'route';
+  if (roles.includes('middleware')) return 'middleware';
+  if (roles.includes('lifecycle')) return 'lifecycle';
+  return roles[0] || 'unknown';
+}
+
+function buildHandlerImports(dispatchTable) {
+  return (dispatchTable.handlerSlots || []).map((slot) => {
+    const role = primaryRole(slot);
+    return {
+      module: 'pulsewasm_handlers',
+      name: slot.name,
+      slot: slot.slot,
+      handlerId: slot.id,
+      roles: slot.roles || [],
+      primaryRole: role,
+      signature: roleSignature(role),
+      missingPolicy: 'build-time error; no runtime fallback'
+    };
+  });
+}
+
+
+function formatParam(param) {
+  return `${param.name}: ${param.type}`;
+}
+
+function functionSignature(item) {
+  if (item.returns === 'memory') return `${item.name}: memory`;
+  const params = (item.params || []).map(formatParam).join(', ');
+  return `${item.name}(${params}) -> ${item.returns || 'void'}`;
+}
+
+function buildMarkdown(artifact) {
+  const exports = artifact.exports.flatMap((group) => group.functions.map((item) => ({ group: group.name, ...item })));
+  const lines = [];
+  lines.push('# PulseWasm Wasm Host ABI Contract v4');
+  lines.push('');
+  lines.push(`Generated by: \`${artifact.generatedBy}\``);
+  lines.push(`Phase: \`${artifact.policy.phase}\``);
+  lines.push('');
+  lines.push('## Status');
+  lines.push('');
+  lines.push('Locked as a contract artifact. Phase 12D includes streaming / response pass-through ABI contract, but still does not implement WIT or platform bindings.');
+  lines.push('');
+  lines.push('## Memory and string policy');
+  lines.push('');
+  lines.push(`- Encoding: \`${artifact.memory.stringEncoding}\``);
+  lines.push(`- Host strings: \`${artifact.memory.hostStringRepresentation}\``);
+  lines.push(`- Internal AS strings: \`${artifact.memory.internalStringRepresentation}\``);
+  lines.push(`- Ownership: \`${artifact.memory.ownership}\``);
+  lines.push('');
+  lines.push('## Wasm exports');
+  lines.push('');
+  for (const item of exports) {
+    lines.push(`- \`${functionSignature(item)}\` _(${item.group})_`);
+  }
+  lines.push('');
+  lines.push('## Handler imports');
+  lines.push('');
+  for (const item of artifact.imports.handlers) {
+    lines.push(`- \`pulsewasm_handlers.${item.name}: ${item.signature}\` — slot ${item.slot}, role ${item.primaryRole}`);
+  }
+  lines.push('');
+  lines.push('## Broadcaster import');
+  lines.push('');
+  lines.push(`- \`${artifact.imports.broadcaster.module}.${artifact.imports.broadcaster.name}: ${artifact.imports.broadcaster.signature}\``);
+  lines.push(`- Required when channels resolve: \`${artifact.imports.broadcaster.requiredWhenChannelsResolve}\``);
+  lines.push('');
+  lines.push('## Defaults');
+  lines.push('');
+  lines.push(`- Normal fallthrough: \`${artifact.defaults.normalFallthrough.statusCode}\``);
+  lines.push(`- Error fallthrough: \`${artifact.defaults.errorFallthrough.statusCode}\``);
+  lines.push(`- Contract violation: \`${artifact.defaults.contractViolation.statusCode} ${artifact.defaults.contractViolation.code}\``);
+  lines.push('');
+  lines.push('## Non-goals');
+  lines.push('');
+  for (const item of artifact.nonGoals) lines.push(`- ${item}`);
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function buildWasmHostAbi(dispatchTable, executionPlan, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const exportGroups = buildWasmHostAbiExportGroups();
+  const flatExports = flattenWasmHostAbiExports(exportGroups);
+  const handlerImports = buildHandlerImports(dispatchTable || {});
+  const channelHandlers = Number(dispatchTable?.summary?.channelHandlers || 0);
+  const lifecycleLinks = Number(dispatchTable?.summary?.lifecycleLinks || 0);
+
+  const artifact = normalizeArtifact({
+    version: ABI_VERSION,
+    generatedBy,
+    source: dispatchTable?.source,
+    policy: {
+      phase: ABI_PHASE,
+      status: 'locked-contract',
+      sourceOfTruth: [
+        'pulsewasm-runtime-abi-boundary-contract-v1.md',
+        'dispatch-table.json',
+        'execution-plan.json'
+      ],
+      contractOnly: true,
+      jsonBodyAbi: true,
+      streamResultAbi: true,
+      hostBridgeImplemented: false,
+      wasmExecutionChanged: false,
+      platformBindings: false,
+      wit: false,
+      wasiHttp: false,
+      dynamicHandlerLookup: false
+    },
+    primitives: {
+      Pointer: 'i32',
+      ByteLength: 'i32',
+      MethodCode: 'i32',
+      StatusCode: 'i32',
+      StringRef: 'i32',
+      HostResponseRef: 'i32',
+      HostStreamRef: 'i32',
+      ErrorRef: 'i32',
+      ResultRef: 'i32',
+      ChannelsRef: 'i32',
+      CtxRef: 'i32',
+      NextRef: 'i32'
+    },
+    memory: {
+      exportedMemory: 'memory',
+      stringEncoding: 'utf8',
+      hostStringRepresentation: 'ptr + byteLen',
+      internalStringRepresentation: 'AssemblyScript string',
+      ownership: 'host writes through pulse_alloc; wasm owns refs returned by ctx/result/error/channel operations until reset',
+      resetInvalidatesRefs: true,
+      componentModelDeferred: true
+    },
+    headers: {
+      firstClass: true,
+      storage: 'ordered repeated header entries with ASCII case-insensitive lookup',
+      requestHeaders: 'read-only to handlers; host/adaptor seeded',
+      responseHeaders: 'mutable through set/append/delete; exported by ordered iteration',
+      gripFraming: 'expressed through normal response headers such as Grip-Hold and repeated Grip-Channel',
+      bodyPolicy: 'request body deferred; RESULT_TEXT, RESULT_EMPTY, RESULT_JSON text helper, and RESULT_STREAM implemented; RESULT_BINARY reserved'
+    },
+    constants: {
+      methodCodes: METHOD_CODES,
+      resultKinds: RESULT_KINDS,
+      nextOutcomes: NEXT_OUTCOMES
+    },
+    exports: Object.entries(exportGroups).map(([name, functions]) => ({ name, functions })),
+    exportCount: flatExports.length,
+    imports: {
+      handlers: handlerImports,
+      broadcaster: {
+        module: 'pulsewasm_broadcaster',
+        name: 'broadcast',
+        signature: '(channelsRef: i32, ctxRef: i32) -> i32',
+        returnPolicy: '0 = ok; non-zero = ErrorRef',
+        requiredWhenChannelsResolve: true,
+        missingBroadcasterFailure: {
+          code: 'PULSEWASM_BROADCASTER_MISSING',
+          message: 'Channel routing resolved channels, but no broadcaster adaptor was provided.',
+          statusCode: 500
+        }
+      }
+    },
+    importCount: handlerImports.length + 1,
+    ctxOperations: {
+      param: 'pulse_ctx_param(ctxRef, namePtr, nameLen) -> StringRef',
+      requestHeaderFirst: 'pulse_request_header_first(ctxRef, namePtr, nameLen) -> StringRef',
+      requestHeaderCount: 'pulse_request_header_count(ctxRef, namePtr, nameLen) -> i32',
+      requestHeaderAt: 'pulse_request_header_at(ctxRef, namePtr, nameLen, index) -> StringRef',
+      responseHeaderSet: 'pulse_response_header_set(ctxRef, namePtr, nameLen, valuePtr, valueLen)',
+      responseHeaderAppend: 'pulse_response_header_append(ctxRef, namePtr, nameLen, valuePtr, valueLen)',
+      responseHeaderDelete: 'pulse_response_header_delete(ctxRef, namePtr, nameLen)',
+      stateGet: 'pulse_ctx_state_get(ctxRef, keyPtr, keyLen) -> StringRef',
+      stateSet: 'pulse_ctx_state_set(ctxRef, keyPtr, keyLen, valuePtr, valueLen)',
+      resultText: 'pulse_result_text(ctxRef, statusCode, bodyPtr, bodyLen)',
+      resultJsonText: 'pulse_result_json_text(ctxRef, statusCode, jsonPtr, jsonLen)',
+      resultEmpty: 'pulse_result_empty(ctxRef, statusCode)',
+      next: 'pulse_next(ctxRef)',
+      nextError: 'pulse_next_error(ctxRef, errorRef)'
+    },
+    errorAbi: {
+      shape: {
+        codeRef: 'StringRef',
+        messageRef: 'StringRef',
+        statusCode: 'i32',
+        causeRef: 'ErrorRef | 0'
+      },
+      constructors: ['pulse_error', 'pulse_error_with_cause'],
+      throwRejected: true,
+      tryCatchRejected: true,
+      cleanTransition: 'pulse_next_error(ctxRef, errorRef)'
+    },
+    resultAbi: {
+      shape: {
+        statusCode: 'i32',
+        bodyRef: 'StringRef | BytesRef | 0',
+        headersRef: 'HeadersRef | 0',
+        kind: 'i32'
+      },
+      implemented: ['RESULT_TEXT', 'RESULT_JSON', 'RESULT_EMPTY', 'RESULT_STREAM'],
+      declaredReserved: ['RESULT_BINARY']
+    },
+    lifecycle: {
+      explicitEntrypoints: ['pulse_execute_connect', 'pulse_execute_disconnect'],
+      matchingInput: 'methodCode + full request path',
+      hiddenInsideRequestDispatch: false,
+      lifecycleLinks
+    },
+    mountPolicy: {
+      canonicalPathInput: 'full request path',
+      semanticRelativeTrimming: false,
+      continuation: 'execution-plan childStartIndex / parentContinueIndex / nextIndex'
+    },
+    streaming: {
+      resultStreamImplemented: true,
+      resultBinaryReserved: true,
+      wasmOwnsBytes: false,
+      hostOwnsStream: true,
+      primaryPrimitive: 'pulse_result_from_response(ctxRef, responseRef)',
+      secondaryPrimitive: 'pulse_result_stream(ctxRef, statusCode, streamRef)',
+      headerMergePolicy: 'backend response headers preserved, response header set overrides, append adds, delete removes by case-insensitive name'
+    },
+    defaults: {
+      normalFallthrough: { statusCode: 404, kind: 'RESULT_EMPTY' },
+      errorFallthrough: { statusCode: 500, kind: 'RESULT_TEXT' },
+      contractViolation: {
+        statusCode: 500,
+        code: 'PULSEWASM_NO_RESULT',
+        message: 'Handler halted without result or continuation.'
+      }
+    },
+    debugProductionPolicy: {
+      debugMayInclude: ['route stable IDs', 'handler IDs', 'handler names', 'diagnostic strings', 'artifact version metadata'],
+      productionShouldStripTo: ['numeric route IDs', 'method codes', 'path segment tables', 'param tables', 'handler slots', 'scope tables', 'entry transition tables', 'minimal matching strings'],
+      productionStrippingImplemented: false
+    },
+    nonGoals: [
+      'No WIT shape yet',
+      'No wasi:http binding shape yet',
+      'No platform adapter yet',
+      'No high-level Pulse wrapper port',
+      'No schema-generated JSON parser implementation yet',
+      'No binary body ABI implementation yet',
+      'No async strategy',
+      'No production memory optimizer'
+    ],
+    summary: {
+      exports: flatExports.length,
+      handlerImports: handlerImports.length,
+      imports: handlerImports.length + 1,
+      headerExports: exportGroups.headers.length,
+      jsonBodyExports: exportGroups.jsonBody.length,
+      routes: dispatchTable?.summary?.routes || 0,
+      executionEntries: executionPlan?.summary?.entries || 0,
+      channelHandlers,
+      broadcasterRequiredWhenChannelsResolve: channelHandlers > 0,
+      lifecycleLinks,
+      contractOnly: true,
+      jsonBodyAbi: true
+    }
+  }, cwd);
+
+  const markdown = buildMarkdown(artifact);
+  return {
+    artifact,
+    markdown,
+    files: [
+      { file: 'generated/host/wasm-host-abi.md', text: markdown }
+    ],
+    diagnostics: []
+  };
+}
+
+module.exports = {
+  ABI_VERSION,
+  buildWasmHostAbi
+};