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

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

@@ -0,0 +1,467 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { PACKAGE_VERSION, normalizeArtifact } = require('../diagnostics.js');
+const { EXECUTION_PLAN_VERSION } = loadContractsExecutionPlan();
+
+const EXECUTION_HARNESS_VERSION = 'pulsewasm.execution-harness.v2';
+
+function loadContractsExecutionPlan() {
+  try {
+    return require('@pulse-compute/wasm-contracts/execution-plan');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/execution-plan.js');
+    }
+    throw error;
+  }
+}
+
+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 = 'execution harness') {
+  return [
+    '/*',
+    ' * Generated by PulseWasm Phase 8E.',
+    ' * Do not edit by hand.',
+    ' *',
+    ` * This ${file} is generated from execution-plan.json + handler-bindings.json.`,
+    ' * It executes ordered entry metadata and must not use the original Router.',
+    ' */',
+    ''
+  ].join('\n');
+}
+
+function makeFile(file, text) {
+  return {
+    file,
+    bytes: Buffer.byteLength(text, 'utf8'),
+    sha256: sha256(text),
+    text
+  };
+}
+
+function uniqueNumbers(values) {
+  return Array.from(new Set(values.filter((value) => Number.isInteger(value)))).sort((a, b) => a - b);
+}
+
+function collectExpectedSlots(dispatchTable, executionPlan) {
+  const slots = [];
+  if (executionPlan && Array.isArray(executionPlan.entries)) {
+    for (const entry of executionPlan.entries) {
+      if (Number.isInteger(entry.handler?.slot)) slots.push(entry.handler.slot);
+      if (Number.isInteger(entry.channel?.slot)) slots.push(entry.channel.slot);
+    }
+    for (const scope of executionPlan.scopes || []) {
+      for (const step of scope.connect || []) if (Number.isInteger(step.slot)) slots.push(step.slot);
+      for (const step of scope.disconnect || []) if (Number.isInteger(step.slot)) slots.push(step.slot);
+      if (Number.isInteger(scope.channel?.slot)) slots.push(scope.channel.slot);
+    }
+    return uniqueNumbers(slots);
+  }
+
+  for (const route of dispatchTable?.routes || []) {
+    for (const step of route.execution?.normal || []) if (Number.isInteger(step.slot)) slots.push(step.slot);
+    for (const step of route.execution?.error || []) if (Number.isInteger(step.slot)) slots.push(step.slot);
+    for (const step of route.execution?.lifecycle?.connect || []) if (Number.isInteger(step.slot)) slots.push(step.slot);
+    for (const step of route.execution?.lifecycle?.disconnect || []) if (Number.isInteger(step.slot)) slots.push(step.slot);
+    const channel = route.execution?.channel;
+    if (channel && channel.kind === 'handler' && Number.isInteger(channel.slot)) slots.push(channel.slot);
+  }
+  return uniqueNumbers(slots);
+}
+
+function buildExecutionPlanSource(executionPlan) {
+  return `${header('execution plan module')}export const EXECUTION_PLAN_VERSION = ${tsJson(executionPlan?.version || EXECUTION_PLAN_VERSION)} as const\n\nexport const EXECUTION_PLAN = ${tsJson(executionPlan || { entries: [], scopes: [] })} as const\n\nexport const EXECUTION_ENTRIES = EXECUTION_PLAN.entries\n\nexport const EXECUTION_SCOPES = EXECUTION_PLAN.scopes\n`;
+}
+
+function buildExecutionHarnessSource(expectedSlots) {
+  return `${header()}import { match, matchPathPattern } from './dispatch'
+import type { DispatchMatch, HandlerUse } from './types'
+import { EXECUTION_ENTRIES, EXECUTION_SCOPES } from './execution-plan'
+import { getHandlerBySlot, assertHandlerBindingCoverage, type PulseHandler } from './handler-slots'
+
+export type ExecutionMode = 'entry-scan'
+export type ExecutionPhase = 'normal' | 'error' | 'lifecycle:connect' | 'lifecycle:disconnect' | 'channel'
+export type ExecutionStatus = 'response' | 'halt' | 'continue' | 'error' | 'not-found'
+
+export type ExecutionTraceEvent = {
+  readonly kind: 'enter' | 'next' | 'exit' | 'halt' | 'skip' | 'channel' | 'scope' | 'mount'
+  readonly phase: ExecutionPhase
+  readonly index: number
+  readonly slot?: number
+  readonly handlerId?: string
+  readonly name?: string
+  readonly error?: boolean
+}
+
+export type ExecutionContext = {
+  readonly method: string
+  readonly path: string
+  params: Record<string, string>
+  locals: Record<string, unknown>
+  trace: ExecutionTraceEvent[]
+  scope?: unknown
+  activeError?: unknown
+  [key: string]: unknown
+}
+
+export type HandlerResolver = (slot: number) => PulseHandler | undefined
+
+export type ExecuteOptions = {
+  readonly ctx?: ExecutionContext
+  readonly getHandlerBySlot?: HandlerResolver
+  readonly trace?: ExecutionTraceEvent[]
+}
+
+export type ExecutionResult = {
+  readonly status: ExecutionStatus
+  readonly value?: unknown
+  readonly error?: unknown
+  readonly ctx: ExecutionContext
+  readonly trace: readonly ExecutionTraceEvent[]
+  readonly completed: boolean
+  readonly executedSlots: readonly number[]
+  readonly finalIndex: number
+}
+
+export const EXPECTED_HANDLER_SLOTS = ${tsJson(expectedSlots)} as const
+
+type AnyEntry = typeof EXECUTION_ENTRIES[number]
+type AnyScope = typeof EXECUTION_SCOPES[number]
+
+function slotFor(step: HandlerUse | { readonly slot?: number | null; readonly name?: string; readonly id?: string; readonly handlerId?: string }, phase: ExecutionPhase): number {
+  if (!Number.isInteger(step.slot)) {
+    throw new Error('Missing handler slot for ' + phase + ' step ' + String(step.name || step.handlerId || step.id || '<unknown>'))
+  }
+  return step.slot as number
+}
+
+function handlerIdFor(step: HandlerUse | { readonly id?: string; readonly handlerId?: string }): string | undefined {
+  return step.handlerId || step.id
+}
+
+function ensureSync(result: unknown, name: string | undefined): void {
+  if (result && typeof (result as { then?: unknown }).then === 'function') {
+    throw new Error('PulseWasm v1 execution harness received a Promise from handler ' + String(name || '<unknown>'))
+  }
+}
+
+function traceEvent(kind: ExecutionTraceEvent['kind'], phase: ExecutionPhase, index: number, step?: { readonly slot?: number | null; readonly id?: string; readonly handlerId?: string; readonly name?: string }, error?: boolean): ExecutionTraceEvent {
+  return {
+    kind,
+    phase,
+    index,
+    slot: step && Number.isInteger(step.slot) ? step.slot as number : undefined,
+    handlerId: step ? handlerIdFor(step) : undefined,
+    name: step?.name,
+    error
+  }
+}
+
+function scopeById(scopeId: number | null | undefined): AnyScope | undefined {
+  if (!Number.isInteger(scopeId)) return undefined
+  return (EXECUTION_SCOPES as readonly AnyScope[]).find((scope) => scope.id === scopeId)
+}
+
+function mergeParams(target: Record<string, string>, next: Record<string, string>): void {
+  for (const [key, value] of Object.entries(next || {})) target[key] = value
+}
+
+function matchEntryPattern(entry: AnyEntry, requestPath: string): { params: Record<string, string>; rest: string } | null {
+  const pattern = (entry as { pattern?: unknown }).pattern
+  if (!pattern) return { params: {}, rest: requestPath }
+  return matchPathPattern(pattern as never, requestPath)
+}
+
+function createTraceBackedContext(method: string, requestPath: string, extra: Record<string, unknown> = {}): ExecutionContext {
+  return {
+    ...extra,
+    method: String(method || '').toUpperCase(),
+    path: requestPath,
+    params: { ...(extra.params as Record<string, string> || {}) },
+    locals: Object.assign({}, extra.locals || {}),
+    trace: []
+  }
+}
+
+export function createExecutionContext(method: string, requestPath: string, extra: Record<string, unknown> = {}): ExecutionContext {
+  return createTraceBackedContext(method, requestPath, extra)
+}
+
+export function assertExecutionBindingCoverage(expectedSlots: readonly number[] = EXPECTED_HANDLER_SLOTS): void {
+  assertHandlerBindingCoverage(expectedSlots)
+}
+
+export function execute(method: string, requestPath: string, options: ExecuteOptions = {}): ExecutionResult {
+  const normalizedMethod = String(method || '').toUpperCase()
+  const ctx = options.ctx || createExecutionContext(normalizedMethod, requestPath)
+  ctx.method = normalizedMethod
+  ctx.path = requestPath
+  const trace = options.trace || ctx.trace || []
+  ctx.trace = trace
+  const resolver = options.getHandlerBySlot || getHandlerBySlot
+  const executedSlots: number[] = []
+
+  function done(status: ExecutionStatus, finalIndex: number, value?: unknown, error?: unknown): ExecutionResult {
+    return { status, value, error, ctx, trace, completed: status === 'response' || status === 'halt' || status === 'error' || status === 'not-found', executedSlots, finalIndex }
+  }
+
+  function scan(startIndex: number, activeError?: unknown): ExecutionResult {
+    let index = startIndex
+    while (index < EXECUTION_ENTRIES.length) {
+      const entry = EXECUTION_ENTRIES[index] as AnyEntry
+      const kind = (entry as { kind: string }).kind
+      const nextIndex = Number((entry as { nextIndex?: number }).nextIndex ?? index + 1)
+
+      if (activeError !== undefined) {
+        if (kind !== 'error') {
+          trace.push(traceEvent('skip', 'error', index, undefined, true))
+          index = kind === 'mount' ? Number((entry as { parentContinueIndex?: number }).parentContinueIndex ?? nextIndex) : nextIndex
+          continue
+        }
+
+        const handlerUse = (entry as { handler?: HandlerUse }).handler
+        if (!handlerUse) {
+          index = nextIndex
+          continue
+        }
+        const slot = slotFor(handlerUse, 'error')
+        const handler = resolver(slot)
+        if (!handler) throw new Error('Missing generated error handler binding for slot ' + slot)
+        executedSlots.push(slot)
+        ctx.scope = scopeById((entry as { scopeId?: number }).scopeId)
+        ctx.activeError = activeError
+        trace.push(traceEvent('enter', 'error', index, handlerUse, true))
+        let didNext = false
+        let nextResult: ExecutionResult | undefined
+        const next = (nextError?: unknown): unknown => {
+          didNext = true
+          trace.push(traceEvent('next', nextError === undefined ? 'normal' : 'error', index, handlerUse, nextError !== undefined))
+          nextResult = scan(nextIndex, nextError)
+          return nextResult.value
+        }
+        try {
+          const out = handler(activeError, ctx, next)
+          ensureSync(out, handlerUse.name || handlerIdFor(handlerUse))
+          trace.push(traceEvent('exit', 'error', index, handlerUse, activeError !== undefined))
+          if (out !== undefined) return done('response', index, out)
+          if (didNext) return nextResult || done('continue', nextIndex)
+          index = nextIndex
+          continue
+        } catch (err) {
+          activeError = err
+          index = nextIndex
+          continue
+        }
+      }
+
+      if (kind === 'error') {
+        index = nextIndex
+        continue
+      }
+
+      if (kind === 'channel' || kind === 'lifecycle') {
+        trace.push(traceEvent('scope', 'normal', index))
+        index = nextIndex
+        continue
+      }
+
+      if (kind === 'mount') {
+        const matched = matchEntryPattern(entry, requestPath)
+        if (!matched) {
+          trace.push(traceEvent('mount', 'normal', index))
+          index = Number((entry as { parentContinueIndex?: number }).parentContinueIndex ?? nextIndex)
+        } else {
+          mergeParams(ctx.params, matched.params)
+          index = Number((entry as { childStartIndex?: number }).childStartIndex ?? nextIndex)
+        }
+        continue
+      }
+
+      if (kind !== 'use' && kind !== 'route') {
+        index = nextIndex
+        continue
+      }
+
+      if (kind === 'route' && String((entry as { method?: string }).method || '').toUpperCase() !== normalizedMethod) {
+        index = nextIndex
+        continue
+      }
+
+      const matched = matchEntryPattern(entry, requestPath)
+      if (!matched) {
+        index = nextIndex
+        continue
+      }
+      mergeParams(ctx.params, matched.params)
+      const handlerUse = (entry as { handler?: HandlerUse }).handler
+      if (!handlerUse) {
+        index = nextIndex
+        continue
+      }
+      const slot = slotFor(handlerUse, kind === 'route' ? 'normal' : 'normal')
+      const handler = resolver(slot)
+      if (!handler) throw new Error('Missing generated handler binding for slot ' + slot)
+      executedSlots.push(slot)
+      ctx.scope = scopeById((entry as { scopeId?: number }).scopeId)
+      trace.push(traceEvent('enter', 'normal', index, handlerUse))
+      let didNext = false
+      let nextResult: ExecutionResult | undefined
+      const next = (err?: unknown): unknown => {
+        didNext = true
+        trace.push(traceEvent('next', err === undefined ? 'normal' : 'error', index, handlerUse, err !== undefined))
+        nextResult = scan(nextIndex, err)
+        return nextResult.value
+      }
+      try {
+        const out = handler(ctx, next)
+        ensureSync(out, handlerUse.name || handlerIdFor(handlerUse))
+        trace.push(traceEvent('exit', 'normal', index, handlerUse))
+        if (out !== undefined) return done('response', index, out)
+        if (didNext) return nextResult || done('continue', nextIndex)
+        trace.push(traceEvent('halt', 'normal', index, handlerUse))
+        return done('halt', index)
+      } catch (err) {
+        return scan(nextIndex, err)
+      }
+    }
+    if (activeError !== undefined) return done('error', index, undefined, activeError)
+    return done('not-found', index)
+  }
+
+  return scan(0, undefined)
+}
+
+export function executeMatch(matchResult: DispatchMatch, options: ExecuteOptions = {}): ExecutionResult {
+  const requestPath = (matchResult as unknown as { requestPath?: string }).requestPath || matchResult.path
+  return execute(matchResult.method, requestPath, options)
+}
+
+export function executeLifecycle(matchResult: DispatchMatch, event: 'connect' | 'disconnect', options: ExecuteOptions = {}): ExecutionResult {
+  const ctx = options.ctx || createExecutionContext(matchResult.method, (matchResult as unknown as { requestPath?: string }).requestPath || matchResult.path)
+  const steps = event === 'connect' ? matchResult.execution.lifecycle.connect : matchResult.execution.lifecycle.disconnect
+  const trace = options.trace || ctx.trace || []
+  ctx.trace = trace
+  const resolver = options.getHandlerBySlot || getHandlerBySlot
+  const executedSlots: number[] = []
+  for (let i = 0; i < steps.length; i += 1) {
+    const step = steps[i]
+    const slot = slotFor(step, event === 'connect' ? 'lifecycle:connect' : 'lifecycle:disconnect')
+    const handler = resolver(slot)
+    if (!handler) throw new Error('Missing generated lifecycle handler binding for slot ' + slot)
+    executedSlots.push(slot)
+    trace.push(traceEvent('enter', event === 'connect' ? 'lifecycle:connect' : 'lifecycle:disconnect', i, step))
+    const out = handler(ctx, () => undefined)
+    ensureSync(out, step.name || handlerIdFor(step))
+    trace.push(traceEvent('exit', event === 'connect' ? 'lifecycle:connect' : 'lifecycle:disconnect', i, step))
+  }
+  return { status: 'continue', ctx, trace, completed: true, executedSlots, finalIndex: steps.length }
+}
+
+export function resolveChannel(matchResult: DispatchMatch, options: ExecuteOptions = {}): unknown {
+  const channel = matchResult.execution.channel
+  if (!channel) return undefined
+  if (channel.kind === 'static') return channel.value
+
+  const resolver = options.getHandlerBySlot || getHandlerBySlot
+  const slot = slotFor(channel as HandlerUse, 'channel')
+  const handler = resolver(slot)
+  if (!handler) throw new Error('Missing generated channel handler binding for slot ' + slot)
+  const ctx = options.ctx || createExecutionContext(matchResult.method, (matchResult as unknown as { requestPath?: string }).requestPath || matchResult.path)
+  const trace = options.trace || ctx.trace || []
+  trace.push(traceEvent('channel', 'channel', 0, channel as HandlerUse))
+  const result = handler(ctx)
+  ensureSync(result, (channel as HandlerUse).name || handlerIdFor(channel as HandlerUse))
+  return result
+}
+
+export { match }
+`;
+}
+
+function buildTypeScriptExecutionHarness(dispatchTable, handlerBindings, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const diagnostics = [];
+  const executionPlan = options.executionPlan;
+
+  if (!handlerBindings) {
+    diagnostics.push({
+      pass: 'execution-harness',
+      code: 'PULSEWASM_EXECUTION_HARNESS_REQUIRES_HANDLER_BINDINGS',
+      severity: 'error',
+      message: 'The generated execution harness requires generated handler slot bindings.',
+      hint: 'Enable --emit-handler-bindings or use --emit-execution-harness, which implies handler bindings.',
+      loc: { file: '<execution-harness>' }
+    });
+  }
+
+  if (!executionPlan) {
+    diagnostics.push({
+      pass: 'execution-harness',
+      code: 'PULSEWASM_EXECUTION_HARNESS_REQUIRES_EXECUTION_PLAN',
+      severity: 'error',
+      message: 'The Phase 8E execution harness requires execution-plan.json.',
+      hint: 'Run the execution-plan pass before generated harness emission.',
+      loc: { file: '<execution-harness>' }
+    });
+  }
+
+  const expectedSlots = collectExpectedSlots(dispatchTable, executionPlan);
+  const files = [
+    makeFile('generated/execution-plan.ts', buildExecutionPlanSource(executionPlan)),
+    makeFile('generated/execution-harness.ts', buildExecutionHarnessSource(expectedSlots))
+  ];
+
+  const artifact = normalizeArtifact({
+    version: EXECUTION_HARNESS_VERSION,
+    generatedBy: options.generatedBy || PACKAGE_VERSION,
+    source: dispatchTable?.source,
+    dispatchTableVersion: dispatchTable?.version,
+    executionPlanVersion: executionPlan?.version,
+    handlerBindingsVersion: handlerBindings?.artifact?.version,
+    policy: {
+      phase: '8E',
+      sourceOfTruth: 'execution-plan.json + handler-bindings.json',
+      usesOriginalRouter: false,
+      requiresHandlerBindings: true,
+      defaultExecutionMode: 'entry-scan',
+      preservesRouteNext: true,
+      preservesNextErrorTransition: true,
+      generatedDispatchExecutes: true,
+      wasmCodegen: false
+    },
+    expectedHandlerSlots: expectedSlots,
+    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,
+      handlerBindings: handlerBindings?.artifact?.summary?.bindings || 0,
+      diagnostics: diagnostics.length
+    }
+  }, cwd);
+
+  return { version: EXECUTION_HARNESS_VERSION, artifact, files, diagnostics };
+}
+
+module.exports = {
+  EXECUTION_HARNESS_VERSION,
+  buildTypeScriptExecutionHarness,
+  collectExpectedSlots
+};