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

package/README.md

@@ -1,3 +1,49 @@
 # @pulse-compute/wasm-host-runtime
 
-This is an inert namespace-bootstrap package. It contains no executable code.
+<!-- pulse-package-status:start -->
+> **Support tier:** Implementation/transitive surface<br>
+> **Audience:** Pulse host-runtime and provider maintainers.<br>
+> **Install directly:** No for application projects; it is installed transitively.<br>
+> **Supported entry points:** `None for application authors.`<br>
+> **Stability:** Internal compiler/runtime interface synchronized with this release set.<br>
+> **npm:** [`@pulse-compute/wasm-host-runtime`](https://www.npmjs.com/package/@pulse-compute/wasm-host-runtime)<br>
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.2/packages/implementation-packages/)
+>
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.2` package policy.
+<!-- pulse-package-status:end -->
+
+Package-owned PulseWasm host-runtime build-time builders and local runtime helpers.
+
+## Runtime surface
+
+The package root re-exports the package-owned compiler and runtime surfaces:
+
+- `compiler` / `@pulse-compute/wasm-host-runtime/compiler`
+- `runtime` / `@pulse-compute/wasm-host-runtime/runtime`
+
+## Compiler/build-time surface
+
+Host-runtime builders now live in this package instead of `@pulse-compute/wasm-compiler` internals:
+
+- `wasmHostAbi`
+- `wasmHostBridge`
+- `requestResultHeaders`
+- `channelBroadcaster`
+- `jsonBody`
+- `backendCapabilities`
+- `hostRuntimeKernel`
+- `streamingPassthrough`
+- `compiledWasmRuntime`
+
+The compiler orchestrator imports these builders from `@pulse-compute/wasm-host-runtime/compiler`.
+
+## Runtime helpers
+
+Local runtime helpers are exposed under `@pulse-compute/wasm-host-runtime/runtime`:
+
+- `compiledWasmHostRuntimeKv`
+- `kvProvider`
+
+## Dependencies
+
+This package depends on contracts and build-support. It must not depend on `@pulse-compute/wasm-compiler`.

package/package.json

@@ -1,15 +1,55 @@
 {
   "name": "@pulse-compute/wasm-host-runtime",
-  "version": "0.0.0",
-  "description": "Inert namespace bootstrap for Pulse.",
+  "version": "1.0.0-beta.2",
   "license": "Apache-2.0",
+  "engines": {
+    "node": "^22.14.0 || ^24.0.0"
+  },
+  "description": "Platform-neutral PulseWasm host runtime package-owned builders and runtime helpers.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./compiler": "./src/compiler/index.js",
+    "./compiler/host-runtime-kernel": "./src/compiler/host-runtime-kernel.js",
+    "./compiler/wasm-host-abi": "./src/compiler/wasm-host-abi.js",
+    "./compiler/wasm-host-bridge": "./src/compiler/wasm-host-bridge.js",
+    "./compiler/request-result-headers": "./src/compiler/request-result-headers.js",
+    "./compiler/channel-broadcaster": "./src/compiler/channel-broadcaster.js",
+    "./compiler/streaming-passthrough": "./src/compiler/streaming-passthrough.js",
+    "./compiler/json-body": "./src/compiler/json-body.js",
+    "./compiler/backend-capabilities": "./src/compiler/backend-capabilities.js",
+    "./compiler/compiled-wasm-runtime": "./src/compiler/compiled-wasm-runtime.js",
+    "./runtime": "./src/runtime/index.js",
+    "./runtime/compiled-wasm-host-runtime-kv": "./src/runtime/compiled-wasm-host-runtime-kv.js",
+    "./runtime/kv-provider": "./src/runtime/kv-provider.js",
+    "./runtime/continuation-registry": "./src/runtime/continuation-registry.js",
+    "./runtime/canonical-api-runtime": "./src/runtime/canonical-api-runtime.js",
+    "./runtime/canonical-native-host": "./src/runtime/canonical-native-host.js"
+  },
+  "dependencies": {
+    "@pulse-compute/crypto": "1.0.0-beta.2",
+    "@pulse-compute/runtime": "1.0.0-beta.2",
+    "@pulse-compute/wasm-build-support": "1.0.0-beta.2",
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.2",
+    "@pulse-compute/wasm-schema-json": "1.0.0-beta.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
+    "src",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "bootstrap"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulse-compute/pulse.git",
+    "directory": "wasm/packages/host-runtime"
+  },
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.2/packages/implementation-packages/",
+  "bugs": {
+    "url": "https://github.com/pulse-compute/pulse/issues"
   }
-}
+}

package/src/compiler/backend-capabilities.js

@@ -0,0 +1,372 @@
+'use strict';
+
+const { PACKAGE_VERSION, normalizeArtifact, normalizeDiagnostic } = require('@pulse-compute/wasm-contracts/diagnostics');
+const { selectRuntimeEngine } = loadContractsJsonBody();
+const {
+  BACKEND_CAPABILITIES_VERSION,
+  BACKEND_CAPABILITIES_PHASE,
+  DEFAULT_BACKEND_TIMEOUT_MS,
+  METHOD_NAMES,
+  normalizeBackendMethods
+} = loadContractsBackendCapabilities();
+
+function loadContractsJsonBody() {
+  try {
+    return require('@pulse-compute/wasm-contracts/host/json-body');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/host/json-body.js');
+    }
+    throw error;
+  }
+}
+
+function loadContractsBackendCapabilities() {
+  try {
+    return require('@pulse-compute/wasm-contracts/host/backend-capabilities');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/host/backend-capabilities.js');
+    }
+    throw error;
+  }
+}
+
+function plainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function configArtifact(options = {}) {
+  return options.resolvedConfig?.artifact || options.resolvedConfig || {};
+}
+
+function isEnvArtifact(value) {
+  return value && typeof value === 'object' && typeof value.$env === 'string';
+}
+
+function makeDiagnostic(code, message, hint, details) {
+  return normalizeDiagnostic({
+    severity: 'error',
+    phase: 'backend-capabilities',
+    code,
+    message,
+    hint,
+    details,
+    loc: { file: '<config-or-handler>' }
+  });
+}
+
+function sourceDescriptor(value, options = {}) {
+  if (options.envRef) {
+    return {
+      source: 'env',
+      name: options.envRef.name,
+      secret: Boolean(options.envRef.secret),
+      redacted: Boolean(options.envRef.redacted),
+      resolved: Boolean(options.envRef.resolved),
+      compiledIntoBinary: false
+    };
+  }
+  if (isEnvArtifact(value)) {
+    return {
+      source: 'env',
+      name: value.$env,
+      secret: Boolean(value.secret),
+      redacted: Boolean(value.redacted),
+      resolved: Boolean(value.resolved),
+      compiledIntoBinary: false
+    };
+  }
+  if (value && typeof value === 'object' && typeof value.fromEnv === 'string') {
+    return {
+      source: 'env',
+      name: value.fromEnv,
+      secret: options.secret !== false,
+      redacted: options.secret !== false,
+      resolved: false,
+      compiledIntoBinary: false
+    };
+  }
+  if (typeof value === 'string') {
+    return {
+      source: 'literal',
+      value,
+      secret: Boolean(options.secret),
+      redacted: Boolean(options.secret),
+      compiledIntoBinary: !options.secret
+    };
+  }
+  return { source: 'unsupported', value: value === undefined ? null : value, compiledIntoBinary: false };
+}
+
+function findEnvRefForTail(envRefByPath, tailSegments) {
+  const tail = tailSegments.join('.');
+  for (const [pathKey, ref] of envRefByPath.entries()) {
+    if (pathKey === tail || pathKey.endsWith('.' + tail)) return ref;
+  }
+  return undefined;
+}
+
+function normalizeHeaderConfig(headers, backendKey, envRefByPath) {
+  const out = [];
+  const obj = plainObject(headers);
+  for (const [name, raw] of Object.entries(obj)) {
+    const envRef = findEnvRefForTail(envRefByPath, ['backends', backendKey, 'headers', name]) || findEnvRefForTail(envRefByPath, ['capabilities', 'backends', backendKey, 'headers', name]);
+    const descriptor = sourceDescriptor(raw, { secret: /authorization|token|secret|key|password/i.test(name), envRef });
+    const item = { ...descriptor, name };
+    if (descriptor.source === 'env' && descriptor.name) item.env = descriptor.name;
+    out.push(item);
+  }
+  return out;
+}
+
+function normalizeBackends(config) {
+  const backends = [];
+  const diagnostics = [];
+  const envRefByPath = new Map();
+  for (const ref of config.env?.references || []) {
+    if (Array.isArray(ref.path)) envRefByPath.set(ref.path.join('.'), ref);
+  }
+  const runtime = plainObject(config.runtime);
+  const capabilities = plainObject(runtime.capabilities);
+  const rawBackends = plainObject(capabilities.backends || runtime.backends || config.backends);
+  for (const [key, raw] of Object.entries(rawBackends)) {
+    const value = plainObject(raw);
+    const allowedMethods = normalizeBackendMethods(value.allowedMethods);
+    const timeoutMs = value.timeoutMs === undefined || value.timeoutMs === null ? DEFAULT_BACKEND_TIMEOUT_MS : Number(value.timeoutMs);
+    const backend = {
+      key,
+      baseUrl: sourceDescriptor(value.baseUrl, { secret: false, envRef: findEnvRefForTail(envRefByPath, ['backends', key, 'baseUrl']) || findEnvRefForTail(envRefByPath, ['capabilities', 'backends', key, 'baseUrl']) }),
+      allowedMethods,
+      timeoutMs,
+      headers: normalizeHeaderConfig(value.headers, key, envRefByPath),
+      policy: {
+        declared: true,
+        staticKey: true,
+        secretsCompiledIntoBinary: false
+      }
+    };
+    if (!key || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_BACKEND_KEY_INVALID',
+        `Backend key ${JSON.stringify(key)} is not a valid static identifier-like key.`,
+        'Use keys like usersApi or payments.',
+        { key }
+      ));
+    }
+    if (backend.baseUrl.source === 'unsupported') {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_BACKEND_BASE_URL_INVALID',
+        `Backend ${key} must declare a literal or env-backed baseUrl.`,
+        'Use baseUrl: env("USERS_API_BASE_URL") or a literal URL.',
+        { key }
+      ));
+    }
+    if (allowedMethods.length === 0) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_BACKEND_METHODS_REQUIRED',
+        `Backend ${key} must declare allowedMethods.`,
+        'Use allowedMethods: ["GET", "POST"].',
+        { key }
+      ));
+    }
+    for (const method of allowedMethods) {
+      if (!METHOD_NAMES.has(method)) {
+        diagnostics.push(makeDiagnostic(
+          'PULSEWASM_BACKEND_METHOD_INVALID',
+          `Backend ${key} declares unsupported method ${JSON.stringify(method)}.`,
+          'Use standard uppercase HTTP methods.',
+          { key, method }
+        ));
+      }
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || Math.floor(timeoutMs) !== timeoutMs) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_BACKEND_TIMEOUT_INVALID',
+        `Backend ${key} timeoutMs must be a positive integer.`,
+        `Use a positive timeout such as ${DEFAULT_BACKEND_TIMEOUT_MS}.`,
+        { key, timeoutMs }
+      ));
+    }
+    backends.push(backend);
+  }
+  return { backends, diagnostics };
+}
+
+function collectFetchUsages(handlerEval) {
+  const usages = [];
+  const items = [];
+  for (const handler of handlerEval?.handlers || []) items.push(handler);
+  for (const dep of handlerEval?.dependencyEvaluations || []) items.push(dep);
+  for (const evaluation of items) {
+    for (const fetch of evaluation.fetches || []) {
+      usages.push({
+        handlerId: evaluation.handlerId,
+        handler: evaluation.handlerName,
+        roles: evaluation.roles || [],
+        backend: fetch.backend,
+        method: fetch.method,
+        path: fetch.path,
+        static: Boolean(fetch.static),
+        loc: fetch.loc
+      });
+    }
+  }
+  return usages;
+}
+
+function validateUsages(usages, backends, engine) {
+  const diagnostics = [];
+  const byKey = new Map(backends.map((backend) => [backend.key, backend]));
+  for (const usage of usages) {
+    if (!usage.backend) continue;
+    const backend = byKey.get(usage.backend);
+    if (!backend) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_UNDECLARED_BACKEND',
+        `Handler ${usage.handler} uses undeclared backend ${JSON.stringify(usage.backend)}.`,
+        'Declare the backend in defineConfig.backends before using ctx.fetch().',
+        usage
+      ));
+      continue;
+    }
+    if (usage.method && !backend.allowedMethods.includes(usage.method)) {
+      diagnostics.push(makeDiagnostic(
+        'PULSEWASM_BACKEND_METHOD_NOT_ALLOWED',
+        `Handler ${usage.handler} uses ${usage.method} for backend ${usage.backend}, but it is not allowed.`,
+        `Add ${usage.method} to defineConfig.backends.${usage.backend}.allowedMethods or use an allowed method.`,
+        { usage, allowedMethods: backend.allowedMethods }
+      ));
+    }
+  }
+  if (engine.engine === 'wasm' && usages.length > 0) {
+    diagnostics.push(makeDiagnostic(
+      'PULSEWASM_FETCH_EFFECT_UNSUPPORTED',
+      'ctx.fetch requires the Wasm host effect runtime, which is not enabled yet.',
+      'Use runtime.engine = "js" manually, remove ctx.fetch from Wasm-targeted handlers, or wait for the future Wasm fetch-effect runtime.',
+      { usages: usages.map((usage) => ({ handler: usage.handler, backend: usage.backend, method: usage.method, path: usage.path })) }
+    ));
+  }
+  return diagnostics;
+}
+
+function buildMarkdown(artifact) {
+  const lines = [];
+  lines.push('# PulseWasm Backend Capability / ctx.fetch Contract 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('## Backends');
+  lines.push('');
+  if (artifact.backends.length === 0) lines.push('- none declared');
+  for (const backend of artifact.backends) {
+    lines.push(`- \`${backend.key}\`: methods \`${backend.allowedMethods.join(', ') || '<none>'}\`, timeout \`${backend.timeoutMs}\`ms`);
+  }
+  lines.push('');
+  lines.push('## ctx.fetch usages');
+  lines.push('');
+  if (artifact.usages.length === 0) lines.push('- none detected');
+  for (const usage of artifact.usages) {
+    lines.push(`- \`${usage.handler}\` -> \`${usage.backend}\` \`${usage.method || '?'} ${usage.path || '?'}\``);
+  }
+  lines.push('');
+  lines.push('## Diagnostics');
+  lines.push('');
+  if (artifact.diagnostics.length === 0) lines.push('- none');
+  for (const diag of artifact.diagnostics) lines.push(`- \`${diag.code}\`: ${diag.message}`);
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function buildBackendCapabilities(dispatchTable, executionPlan, handlerEval, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const config = configArtifact(options);
+  const engine = selectRuntimeEngine(config);
+  const normalized = normalizeBackends(config);
+  const usages = collectFetchUsages(handlerEval);
+  const usageDiagnostics = validateUsages(usages, normalized.backends, engine);
+  const diagnostics = [...normalized.diagnostics, ...usageDiagnostics];
+
+  const artifact = normalizeArtifact({
+    version: BACKEND_CAPABILITIES_VERSION,
+    generatedBy,
+    source: dispatchTable?.source,
+    policy: {
+      phase: BACKEND_CAPABILITIES_PHASE,
+      status: 'locked-contract',
+      sanctionedPath: 'ctx.fetch("backendKey", { method, path })',
+      declarationSurface: 'defineConfig.backends',
+      appFetchOutbound: false,
+      globalFetchAllowed: false,
+      arbitraryNetworkImportsAllowed: false,
+      wasmFetchEffectImplemented: false,
+      jsEngineEscapeHatch: 'manual-only'
+    },
+    lockedPositions: [
+      'defineConfig.backends declares outbound backend capabilities.',
+      'ctx.fetch consumes declared outbound backend capabilities during active execution.',
+      'Global fetch and networking libraries are forbidden in PulseWasm handlers.',
+      'backend key, method, and request object are static in v1.',
+      'Wasm fetch execution is reserved for a future host effect/resume runtime.',
+      'JS engine usage is manual escape hatch debt; fallback is never automatic.'
+    ],
+    runtime: {
+      engine: engine.engine,
+      engineSource: engine.source,
+      manualEscapeHatch: engine.engine === 'js',
+      automaticFallback: false
+    },
+    defaults: {
+      timeoutMs: DEFAULT_BACKEND_TIMEOUT_MS
+    },
+    backends: normalized.backends,
+    usages,
+    diagnostics,
+    diagnosticsPolicy: {
+      errors: [
+        'PULSEWASM_FETCH_EFFECT_UNSUPPORTED',
+        'PULSEWASM_UNDECLARED_BACKEND',
+        'PULSEWASM_DYNAMIC_BACKEND_KEY',
+        'PULSEWASM_DYNAMIC_FETCH_REQUEST',
+        'PULSEWASM_BACKEND_METHOD_NOT_ALLOWED',
+        'PULSEWASM_FORBIDDEN_GLOBAL_FETCH',
+        'PULSEWASM_FORBIDDEN_NETWORK_IMPORT'
+      ],
+      debt: ['PULSEWASM_FETCH_REQUIRES_JS_ENGINE']
+    },
+    futureWasmEffectAbi: {
+      implementedIn10G: false,
+      reservedShape: 'pulse_fetch_start(ctxRef, backendKeyRef, requestRef) -> FetchEffectRef',
+      resumeRuntimeRequired: true
+    },
+    summary: {
+      backends: normalized.backends.length,
+      usages: usages.length,
+      engine: engine.engine,
+      wasmFetchEffectImplemented: false,
+      wasmModeBlockedByFetch: engine.engine === 'wasm' && usages.length > 0,
+      jsEscapeHatchDebt: engine.engine === 'js' && usages.length > 0,
+      diagnostics: diagnostics.length
+    }
+  }, cwd);
+
+  return {
+    artifact,
+    files: [{ file: 'generated/host/backend-capabilities.md', text: buildMarkdown(artifact) }],
+    diagnostics
+  };
+}
+
+module.exports = {
+  BACKEND_CAPABILITIES_VERSION,
+  DEFAULT_BACKEND_TIMEOUT_MS,
+  buildBackendCapabilities,
+  collectFetchUsages,
+  normalizeBackends
+};

package/src/compiler/channel-broadcaster.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const { PACKAGE_VERSION, normalizeArtifact } = require('@pulse-compute/wasm-contracts/diagnostics');
+const {
+  CHANNEL_BROADCASTER_VERSION,
+  CHANNEL_BROADCASTER_PHASE,
+  BROADCASTER_MISSING_CODE,
+  channelAbiContract,
+  broadcasterImportContract
+} = loadContractsChannelBroadcaster();
+
+function loadContractsChannelBroadcaster() {
+  try {
+    return require('@pulse-compute/wasm-contracts/host/channel-broadcaster');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/host/channel-broadcaster.js');
+    }
+    throw error;
+  }
+}
+
+function channelKind(channel) {
+  if (!channel) return 'none';
+  if (channel.kind === 'handler') return 'handler';
+  if (channel.kind === 'static') return 'static';
+  return channel.kind || 'unknown';
+}
+
+function collectChannelUses(dispatchTable, executionPlan) {
+  const routeUses = [];
+  for (const route of dispatchTable?.routes || []) {
+    const channel = route.execution?.channel || route.channel;
+    if (!channel) continue;
+    routeUses.push({
+      kind: 'route',
+      runtimeId: route.runtimeId,
+      stableId: route.stableId,
+      method: route.method,
+      path: route.path,
+      channelKind: channelKind(channel),
+      slot: Number.isInteger(channel.slot) ? channel.slot : undefined,
+      handlerId: channel.id || channel.handlerId,
+      name: channel.name,
+      staticValue: channel.kind === 'static' ? channel.value : undefined
+    });
+  }
+
+  const scopeUses = [];
+  for (const scope of executionPlan?.scopes || []) {
+    if (!scope.channel) continue;
+    const channel = scope.channel;
+    scopeUses.push({
+      kind: 'scope',
+      scopeId: scope.id,
+      channelKind: channelKind(channel),
+      slot: Number.isInteger(channel.slot) ? channel.slot : undefined,
+      handlerId: channel.id || channel.handlerId,
+      name: channel.name,
+      staticValue: channel.kind === 'static' ? channel.value : undefined
+    });
+  }
+
+  return { routeUses, scopeUses };
+}
+
+function buildMarkdown(artifact) {
+  const lines = [];
+  lines.push('# PulseWasm Channel / Broadcaster Adaptor Contract 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('## Channel representation');
+  lines.push('');
+  lines.push(`- Channel handler signature: \`${artifact.channelAbi.handlerSignature}\``);
+  lines.push(`- ChannelsRef: \`${artifact.channelAbi.channelsRef}\``);
+  lines.push(`- Ordered: \`${artifact.channelAbi.ordered}\``);
+  lines.push(`- Empty channel list behavior: \`${artifact.channelAbi.emptyListBehavior}\``);
+  lines.push('');
+  lines.push('## Host-visible channel exports');
+  lines.push('');
+  for (const item of artifact.channelAbi.exports) lines.push(`- \`${item}\``);
+  lines.push('');
+  lines.push('## Broadcaster import');
+  lines.push('');
+  lines.push(`- Module: \`${artifact.broadcaster.module}\``);
+  lines.push(`- Name: \`${artifact.broadcaster.name}\``);
+  lines.push(`- Signature: \`${artifact.broadcaster.signature}\``);
+  lines.push(`- Return policy: \`${artifact.broadcaster.returnPolicy}\``);
+  lines.push(`- Required when channels resolve: \`${artifact.broadcaster.requiredWhenChannelsResolve}\``);
+  lines.push('');
+  lines.push('## Failure');
+  lines.push('');
+  lines.push(`- Code: \`${artifact.broadcaster.missingFailure.code}\``);
+  lines.push(`- Status: \`${artifact.broadcaster.missingFailure.statusCode}\``);
+  lines.push(`- Message: \`${artifact.broadcaster.missingFailure.message}\``);
+  lines.push('');
+  lines.push('## GRIP / headers');
+  lines.push('');
+  lines.push('Channel resolution does not invent a separate GRIP side channel. GRIP/Fanout framing remains expressed through normal ordered response headers such as `Grip-Hold` and repeated `Grip-Channel`.');
+  lines.push('');
+  lines.push('## Summary');
+  lines.push('');
+  for (const [key, value] of Object.entries(artifact.summary)) lines.push(`- ${key}: \`${value}\``);
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function buildChannelBroadcaster(dispatchTable, executionPlan, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const channelHandlers = Number(dispatchTable?.summary?.channelHandlers || 0);
+  const staticChannels = Number(dispatchTable?.summary?.staticChannels || 0);
+  const { routeUses, scopeUses } = collectChannelUses(dispatchTable, executionPlan);
+  const channelsMayResolve = routeUses.length > 0 || scopeUses.length > 0 || channelHandlers > 0 || staticChannels > 0;
+
+  const artifact = normalizeArtifact({
+    version: CHANNEL_BROADCASTER_VERSION,
+    generatedBy,
+    source: dispatchTable?.source,
+    policy: {
+      phase: CHANNEL_BROADCASTER_PHASE,
+      status: 'locked-contract-and-local-bridge-proof',
+      sourceOfTruth: [
+        'dispatch-table.json',
+        'execution-plan.json',
+        'wasm-host-abi.json',
+        'request-result-headers.json',
+        'pulsewasm channel/broadcaster adaptor contract v1'
+      ],
+      contractOnly: true,
+      platformBindings: false,
+      gripImplementation: false,
+      broadcasterAdaptorRequired: channelsMayResolve,
+      silentIgnoreForbidden: true
+    },
+    lockedPositions: [
+      'Channel resolution is a real routing artifact.',
+      'Channel handlers return ChannelsRef through the locked ChannelHandler ABI.',
+      'ChannelsRef is an ordered list of one or more StringRef channel names.',
+      'Static channels and handler-produced channels are normalized to the same ChannelsRef surface.',
+      'If no channel resolves, no broadcaster call occurs.',
+      'If one or more channels resolve and a broadcaster adaptor exists, broadcaster.broadcast(channelsRef, ctxRef) is invoked.',
+      'If one or more channels resolve and the broadcaster adaptor is missing, the runtime/host bridge fails explicitly.',
+      'Broadcaster failure returns an ErrorRef through the broadcaster return value.',
+      'GRIP/Fanout framing remains represented through normal ordered response headers, not a hidden side channel.'
+    ],
+    channelAbi: channelAbiContract(),
+    broadcaster: broadcasterImportContract({ requiredWhenChannelsResolve: channelsMayResolve }),
+    grip: {
+      implementedHere: false,
+      framedThroughHeaders: true,
+      headers: ['Grip-Hold', 'Grip-Channel'],
+      repeatedGripChannelPreserved: true,
+      adaptorFuture: 'GRIP/Fanout adaptor may translate ChannelsRef into ordered response headers and/or platform broadcaster calls.'
+    },
+    channelUses: {
+      routes: routeUses,
+      scopes: scopeUses
+    },
+    summary: {
+      routes: Array.isArray(dispatchTable?.routes) ? dispatchTable.routes.length : 0,
+      executionEntries: Array.isArray(executionPlan?.entries) ? executionPlan.entries.length : 0,
+      scopes: Array.isArray(executionPlan?.scopes) ? executionPlan.scopes.length : 0,
+      routeChannelUses: routeUses.length,
+      scopeChannelUses: scopeUses.length,
+      channelHandlers,
+      staticChannels,
+      channelsMayResolve,
+      broadcasterRequiredWhenChannelsResolve: channelsMayResolve,
+      missingBroadcasterFailureCode: BROADCASTER_MISSING_CODE,
+      gripHeadersModeledThroughHeaders: true,
+      platformBindings: false
+    }
+  }, cwd);
+
+  return {
+    artifact,
+    files: [
+      { file: 'generated/host/channel-broadcaster.md', text: buildMarkdown(artifact) }
+    ],
+    diagnostics: []
+  };
+}
+
+module.exports = {
+  CHANNEL_BROADCASTER_VERSION,
+  buildChannelBroadcaster
+};