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

package/src/host/backend-capabilities.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const BACKEND_CAPABILITIES_VERSION = 'pulsewasm.backend-capabilities.v1';
+const BACKEND_CAPABILITIES_PHASE = '10G';
+const DEFAULT_BACKEND_TIMEOUT_MS = 1500;
+const METHOD_NAMES = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+
+function normalizeBackendMethods(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((method) => String(method || '').toUpperCase()).filter(Boolean);
+}
+
+function isSupportedBackendMethod(method) {
+  return METHOD_NAMES.has(String(method || '').toUpperCase());
+}
+
+module.exports = {
+  BACKEND_CAPABILITIES_VERSION,
+  BACKEND_CAPABILITIES_PHASE,
+  DEFAULT_BACKEND_TIMEOUT_MS,
+  METHOD_NAMES,
+  normalizeBackendMethods,
+  isSupportedBackendMethod
+};

package/src/host/capabilities.js

@@ -0,0 +1,273 @@
+'use strict';
+
+const HOST_CAPABILITIES_VERSION = 'pulsewasm.host-capabilities.v1';
+const WASI_PROVIDER_MAP_VERSION = 'pulsewasm.wasi-provider-map.v1';
+const CAPABILITY_PROVIDER_REPORT_VERSION = 'pulsewasm.capability-provider-report.v1';
+const HOST_CAPABILITY_CONTRACT_VERSION = 'pulsewasm.host-capability-contract.v1';
+
+const CAPABILITY_DEFINITIONS = [
+  {
+    capability: 'headers',
+    category: 'request-result',
+    status: 'implemented',
+    provider: { kind: 'host-runtime', name: 'pulse-host-headers' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Ordered multi-value request/response headers are already exposed through the host ABI.'
+  },
+  {
+    capability: 'result',
+    category: 'request-result',
+    status: 'implemented',
+    provider: { kind: 'host-runtime', name: 'pulse-result-builders' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Text, JSON text, and empty result builders are available; binary remains reserved.'
+  },
+  {
+    capability: 'params',
+    category: 'routing',
+    status: 'implemented',
+    provider: { kind: 'routing-core', name: 'pulse-params-view' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Params are backed by compiled path metadata and request-path slices.'
+  },
+  {
+    capability: 'state',
+    category: 'runtime',
+    status: 'implemented-proof',
+    provider: { kind: 'host-runtime', name: 'pulse-state-adapter' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Node/local proof uses a Map-backed state adapter; production storage remains replaceable.'
+  },
+  {
+    capability: 'error',
+    category: 'runtime',
+    status: 'implemented',
+    provider: { kind: 'host-runtime', name: 'pulse-error-refs' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Structured error refs with code, message, statusCode, and optional cause.'
+  },
+  {
+    capability: 'lifecycle',
+    category: 'runtime',
+    status: 'implemented',
+    provider: { kind: 'execution-plan', name: 'pulse-lifecycle-dispatch' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Connect/disconnect lifecycle hooks are explicit host runtime entrypoints.'
+  },
+  {
+    capability: 'channel',
+    category: 'routing-control',
+    status: 'implemented',
+    provider: { kind: 'routing-core', name: 'pulse-channel-resolution' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Static and handler-produced channels normalize to an ordered channel list surface.'
+  },
+  {
+    capability: 'broadcaster',
+    category: 'routing-control',
+    status: 'implemented-proof',
+    provider: { kind: 'host-adapter', name: 'pulse-broadcaster-adaptor' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: false,
+    notes: 'Broadcaster is an injected host adapter. Missing broadcaster fails explicitly when channels resolve.'
+  },
+  {
+    capability: 'body',
+    category: 'payload',
+    status: 'contract-implemented-lazy-text',
+    provider: { kind: 'host-runtime', name: 'pulse-body-adaptor' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Body access is explicit and lazy. Streaming/binary body is reserved.'
+  },
+  {
+    capability: 'json',
+    category: 'payload',
+    status: 'contract-implemented-generic-default',
+    provider: { kind: 'payload-runtime', name: 'pulse-json-adaptor' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Generic JSON is the ergonomic default; schema JSON sidecars are a future optimization lane.'
+  },
+  {
+    capability: 'clock',
+    category: 'time',
+    status: 'provider-mapped-not-wired',
+    provider: { kind: 'wasi-provider', name: 'wasi:clocks', role: 'preferred monotonic deadline/sleep provider' },
+    providerFallback: { kind: 'host-adapter', name: 'pulse-host-clock', role: 'Node/local proof fallback until WASI/component wiring exists' },
+    effectRuntimeRequired: false,
+    publicHandlerSurface: false,
+    notes: 'Pulse exposes clock/deadline capability; WASI is a provider, not app ergonomics.'
+  },
+  {
+    capability: 'assets',
+    category: 'resource',
+    status: 'reserved-host-capability-payload-streaming-required',
+    provider: { kind: 'host-adapter', name: 'pulse-assets-provider' },
+    providerCandidates: [
+      { kind: 'host-adapter', name: 'static-file-provider' },
+      { kind: 'host-adapter', name: 'object-store-provider' }
+    ],
+    effectRuntimeRequired: false,
+    publicHandlerSurface: true,
+    notes: 'Assets are a reserved host capability/adaptor surface. They are not a v1 core effect kind; streaming/binary payload mechanics remain a future payload ABI.'
+  },
+  {
+    capability: 'backend-fetch',
+    category: 'network-effect',
+    status: 'reserved-effect-runtime-required',
+    provider: { kind: 'host-effect', name: 'pulse-backend-fetch-effect' },
+    providerCandidates: [
+      { kind: 'host-adapter', name: 'declared-backend-http-client' },
+      { kind: 'wasi-provider', name: 'wasi:http', role: 'candidate provider once component/HTTP wiring is explicit' }
+    ],
+    effectRuntimeRequired: true,
+    publicHandlerSurface: true,
+    notes: 'ctx.fetch is declared and visible, but Wasm execution awaits the effect runtime.'
+  },
+  {
+    capability: 'timer',
+    category: 'time-effect',
+    status: 'reserved-effect-runtime-required',
+    provider: { kind: 'wasi-provider', name: 'wasi:clocks', role: 'preferred monotonic sleep/deadline provider' },
+    providerFallback: { kind: 'host-adapter', name: 'pulse-host-scheduler' },
+    effectRuntimeRequired: true,
+    publicHandlerSurface: true,
+    notes: 'Sleep/timeouts are explicit effects, not language async.'
+  }
+];
+
+const PROVIDER_DEFINITIONS = [
+  {
+    id: 'pulse-host-headers',
+    kind: 'host-runtime',
+    capabilities: ['headers'],
+    status: 'implemented',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-result-builders',
+    kind: 'host-runtime',
+    capabilities: ['result'],
+    status: 'implemented',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-params-view',
+    kind: 'routing-core',
+    capabilities: ['params'],
+    status: 'implemented',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-state-adapter',
+    kind: 'host-runtime',
+    capabilities: ['state'],
+    status: 'implemented-proof',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-error-refs',
+    kind: 'host-runtime',
+    capabilities: ['error'],
+    status: 'implemented',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-lifecycle-dispatch',
+    kind: 'execution-plan',
+    capabilities: ['lifecycle'],
+    status: 'implemented',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-channel-resolution',
+    kind: 'routing-core',
+    capabilities: ['channel'],
+    status: 'implemented',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-broadcaster-adaptor',
+    kind: 'host-adapter',
+    capabilities: ['broadcaster'],
+    status: 'implemented-proof',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-body-adaptor',
+    kind: 'host-runtime',
+    capabilities: ['body'],
+    status: 'contract-implemented-lazy-text',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-json-adaptor',
+    kind: 'payload-runtime',
+    capabilities: ['json'],
+    status: 'contract-implemented-generic-default',
+    publicAppApi: false
+  },
+  {
+    id: 'wasi:clocks',
+    kind: 'wasi-provider',
+    capabilities: ['clock', 'timer'],
+    status: 'mapped-not-wired',
+    publicAppApi: false,
+    role: 'monotonic deadlines/sleep provider; wall-clock only for timestamps if explicitly needed'
+  },
+  {
+    id: 'pulse-assets-provider',
+    kind: 'host-adapter',
+    capabilities: ['assets'],
+    status: 'reserved-host-capability-payload-streaming-required',
+    publicAppApi: false
+  },
+  {
+    id: 'pulse-backend-fetch-effect',
+    kind: 'host-effect',
+    capabilities: ['backend-fetch'],
+    status: 'reserved-effect-runtime-required',
+    publicAppApi: false
+  },
+  {
+    id: 'wasi:http',
+    kind: 'wasi-provider-candidate',
+    capabilities: ['backend-fetch', 'body'],
+    status: 'candidate-only-not-default',
+    publicAppApi: false,
+    role: 'future provider candidate; not a handler-facing API and not wired in Phase 11E'
+  }
+];
+
+function knownHostCapabilities() {
+  return CAPABILITY_DEFINITIONS.map((capability) => capability.capability).sort();
+}
+
+function isKnownHostCapability(name) {
+  return knownHostCapabilities().includes(name);
+}
+
+function providerForCapability(name) {
+  const capability = CAPABILITY_DEFINITIONS.find((entry) => entry.capability === name);
+  return capability && capability.provider ? capability.provider : null;
+}
+
+module.exports = {
+  HOST_CAPABILITIES_VERSION,
+  WASI_PROVIDER_MAP_VERSION,
+  CAPABILITY_PROVIDER_REPORT_VERSION,
+  HOST_CAPABILITY_CONTRACT_VERSION,
+  CAPABILITY_DEFINITIONS,
+  PROVIDER_DEFINITIONS,
+  knownHostCapabilities,
+  isKnownHostCapability,
+  providerForCapability
+};

package/src/host/channel-broadcaster.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const CHANNEL_BROADCASTER_VERSION = 'pulsewasm.channel-broadcaster.v1';
+const CHANNEL_BROADCASTER_PHASE = '10E';
+
+const CHANNEL_ABI_EXPORTS = Object.freeze([
+  'pulse_channel_count(channelsRef) -> i32',
+  'pulse_channel_ref_at(channelsRef, index) -> StringRef',
+  'pulse_string_ptr(stringRef) -> i32',
+  'pulse_string_len(stringRef) -> i32'
+]);
+
+const CHANNEL_MISSING_HANDLER_CODE = 'PULSEWASM_CHANNEL_HANDLER_MISSING';
+const CHANNEL_INVALID_RESULT_CODE = 'PULSEWASM_CHANNEL_RESULT_INVALID';
+const BROADCASTER_MISSING_CODE = 'PULSEWASM_BROADCASTER_MISSING';
+
+function channelAbiContract() {
+  return {
+    handlerSignature: 'ChannelHandler = (ctxRef: i32) -> ChannelsRef(i32)',
+    channelsRef: 'opaque i32 reference to an ordered channel list; 0 means no channels',
+    ordered: true,
+    repeatedAllowed: true,
+    emptyListBehavior: 'equivalent to 0 / no broadcaster call',
+    exports: CHANNEL_ABI_EXPORTS.slice(),
+    staticChannelLowering: 'static string channels lower to a ChannelsRef with one StringRef entry',
+    handlerChannelLowering: 'handler channel slots invoke ChannelHandler and normalize its ChannelsRef return',
+    validation: {
+      missingChannelHandler: CHANNEL_MISSING_HANDLER_CODE,
+      invalidChannelResult: CHANNEL_INVALID_RESULT_CODE
+    }
+  };
+}
+
+function broadcasterImportContract(options = {}) {
+  return {
+    module: 'pulsewasm_broadcaster',
+    name: 'broadcast',
+    signature: '(channelsRef: i32, ctxRef: i32) -> ErrorRef(i32)',
+    returnPolicy: '0 = ok; non-zero = ErrorRef and dispatch/result fail with that error',
+    requiredWhenChannelsResolve: Boolean(options.requiredWhenChannelsResolve),
+    missingFailure: {
+      code: BROADCASTER_MISSING_CODE,
+      message: 'Channel routing resolved channels, but no broadcaster adaptor was provided.',
+      statusCode: 500
+    },
+    failureBehavior: 'non-zero ErrorRef becomes active error/result failure at adaptor boundary',
+    sideEffects: 'adaptor-defined; may attach GRIP/Fanout broadcaster behavior later'
+  };
+}
+
+module.exports = {
+  CHANNEL_BROADCASTER_VERSION,
+  CHANNEL_BROADCASTER_PHASE,
+  CHANNEL_ABI_EXPORTS,
+  CHANNEL_MISSING_HANDLER_CODE,
+  CHANNEL_INVALID_RESULT_CODE,
+  BROADCASTER_MISSING_CODE,
+  channelAbiContract,
+  broadcasterImportContract
+};

package/src/host/json-body.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const JSON_BODY_VERSION = 'pulsewasm.json-body.v1';
+const JSON_BODY_PHASE = '10F';
+const DEPLOYMENT_POSTURE_VERSION = 'pulsewasm.deployment-posture.v1';
+
+const JSON_TARGETS = new Set(['generic', 'schema', 'none', 'auto', 'parser']);
+const ENGINE_TARGETS = new Set(['wasm', 'js']);
+const DEFAULT_JSON_MAX_BYTES = 1_048_576;
+
+const JSON_ABI_EXPORTS = Object.freeze([
+  'pulse_request_body_text(ctxRef) -> StringRef',
+  'pulse_request_body_len(ctxRef) -> i32',
+  'pulse_request_json_parse(ctxRef) -> JsonParseResultRef',
+  'pulse_json_result_ok(resultRef) -> i32',
+  'pulse_json_result_value(resultRef) -> JsonValueRef',
+  'pulse_json_result_error(resultRef) -> ErrorRef',
+  'pulse_json_kind(valueRef) -> i32',
+  'pulse_json_object_has(valueRef, keyPtr, keyLen) -> i32',
+  'pulse_json_object_get(valueRef, keyPtr, keyLen) -> JsonValueRef',
+  'pulse_json_array_len(valueRef) -> i32',
+  'pulse_json_array_get(valueRef, index) -> JsonValueRef',
+  'pulse_json_as_string(valueRef) -> StringRef',
+  'pulse_json_as_f64(valueRef) -> f64',
+  'pulse_json_as_bool(valueRef) -> i32',
+  'pulse_result_json_text(ctxRef, statusCode, jsonPtr, jsonLen) -> void'
+]);
+
+function plainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function selectRuntimeEngine(config) {
+  const runtime = plainObject(config.runtime);
+  const explicit = typeof runtime.engine === 'string' && runtime.engine !== '';
+  if (explicit) return { engine: runtime.engine, source: 'config.runtime.engine', explicit: true };
+  if (typeof config.target === 'string' && config.target === 'js') return { engine: 'js', source: 'config.target', explicit: false };
+  return { engine: 'wasm', source: config.target ? 'default-from-non-js-target' : 'default', explicit: false };
+}
+
+function selectJsonConfig(config) {
+  const runtime = plainObject(config.runtime);
+  const payload = plainObject(runtime.payload);
+  const json = plainObject(payload.json || config.json);
+  const explicitTarget = typeof json.target === 'string' && json.target !== '';
+  const target = explicitTarget ? json.target : 'generic';
+  const maxBytes = json.maxBytes === undefined || json.maxBytes === null ? DEFAULT_JSON_MAX_BYTES : Number(json.maxBytes);
+  return {
+    raw: json,
+    target,
+    explicitTarget,
+    targetSource: explicitTarget ? 'runtime.payload.json.target' : 'default',
+    maxBytes,
+    maxBytesSource: json.maxBytes === undefined || json.maxBytes === null ? 'default' : 'runtime.payload.json.maxBytes',
+    schemas: Array.isArray(json.schemas) ? json.schemas : [],
+    parser: typeof json.parser === 'string' && json.parser ? json.parser : undefined
+  };
+}
+
+function isSupportedJsonTarget(target) {
+  return JSON_TARGETS.has(target);
+}
+
+function isSupportedRuntimeEngine(engine) {
+  return ENGINE_TARGETS.has(engine);
+}
+
+module.exports = {
+  JSON_BODY_VERSION,
+  JSON_BODY_PHASE,
+  DEPLOYMENT_POSTURE_VERSION,
+  JSON_TARGETS,
+  ENGINE_TARGETS,
+  DEFAULT_JSON_MAX_BYTES,
+  JSON_ABI_EXPORTS,
+  selectRuntimeEngine,
+  selectJsonConfig,
+  isSupportedJsonTarget,
+  isSupportedRuntimeEngine
+};

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

@@ -0,0 +1,38 @@
+'use strict';
+
+const REQUEST_RESULT_HEADERS_VERSION = 'pulsewasm.request-result-headers.v2';
+const REQUEST_RESULT_HEADERS_PHASE = '12D';
+
+const HEADER_ABI_EXPORTS = Object.freeze([
+  'pulse_request_header_first(ctxRef, namePtr, nameLen) -> StringRef',
+  'pulse_request_header_count(ctxRef, namePtr, nameLen) -> i32',
+  'pulse_request_header_at(ctxRef, namePtr, nameLen, index) -> StringRef',
+  'pulse_response_header_set(ctxRef, namePtr, nameLen, valuePtr, valueLen) -> void',
+  'pulse_response_header_append(ctxRef, namePtr, nameLen, valuePtr, valueLen) -> void',
+  'pulse_response_header_delete(ctxRef, namePtr, nameLen) -> void',
+  'pulse_result_header_count() -> i32',
+  'pulse_result_header_name_ptr(index) -> i32',
+  'pulse_result_header_name_len(index) -> i32',
+  'pulse_result_header_value_ptr(index) -> i32',
+  'pulse_result_header_value_len(index) -> i32',
+  'pulse_result_header_mode(index) -> i32',
+  'pulse_result_header_delete_count() -> i32',
+  'pulse_result_header_delete_name_ptr(index) -> i32',
+  'pulse_result_header_delete_name_len(index) -> i32'
+]);
+
+function handlerVisibleHeaderAbiExports() {
+  return HEADER_ABI_EXPORTS.slice(0, 6);
+}
+
+function hostResultHeaderAbiExports() {
+  return HEADER_ABI_EXPORTS.slice(6);
+}
+
+module.exports = {
+  REQUEST_RESULT_HEADERS_VERSION,
+  REQUEST_RESULT_HEADERS_PHASE,
+  HEADER_ABI_EXPORTS,
+  handlerVisibleHeaderAbiExports,
+  hostResultHeaderAbiExports
+};

package/src/host/streaming-passthrough.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const { RESULT_KINDS } = require('./wasm-host-abi.js');
+
+const STREAMING_PASSTHROUGH_VERSION = 'pulsewasm.streaming-passthrough.v1';
+const STREAM_RESULT_ABI_VERSION = 'pulsewasm.stream-result-abi.v1';
+const RESPONSE_PASSTHROUGH_POLICY_VERSION = 'pulsewasm.response-passthrough-policy.v1';
+const STREAMING_PHASE = '12D';
+const STREAMING_SMOKE_VERSION = 'pulsewasm.streaming-passthrough-smoke.v1';
+
+const STREAM_RESULT_ABI_EXPORTS = Object.freeze([
+  'pulse_result_from_response(ctxRef, responseRef) -> void',
+  'pulse_result_stream(ctxRef, statusCode, streamRef) -> void',
+  'pulse_result_stream_ref() -> HostStreamRef',
+  'pulse_result_response_ref() -> HostResponseRef'
+]);
+
+const RESPONSE_HEADER_MERGE_RULES = Object.freeze([
+  'Preserve backend/platform response headers by default.',
+  'Apply response header delete operations first by ASCII case-insensitive name.',
+  'Apply response header set operations as overrides by ASCII case-insensitive name.',
+  'Apply response header append operations as ordered additions.',
+  'Preserve repeated headers such as Grip-Channel.'
+]);
+
+function streamResultAbiFields(options = {}) {
+  return {
+    sourceWasmHostAbiVersion: options.sourceWasmHostAbiVersion,
+    policy: {
+      phase: STREAMING_PHASE,
+      status: 'locked-contract-and-local-proof',
+      resultBinaryReserved: true,
+      resultStreamImplemented: true,
+      wasmOwnsBytes: false,
+      hostOwnsStream: true
+    },
+    resultKinds: RESULT_KINDS,
+    refs: {
+      HostResponseRef: 'opaque i32/usize owned by host; valid for active request/result lifetime only',
+      HostStreamRef: 'opaque i32/usize owned by host; valid for active request/result lifetime only'
+    },
+    exports: STREAM_RESULT_ABI_EXPORTS.slice(),
+    hostResultShape: {
+      kind: 'stream',
+      status: 'backend response status or explicit stream status',
+      headers: 'ordered repeated headers after pass-through merge',
+      bodyStream: 'host-owned stream / platform response body handle',
+      body: 'undefined; bytes are not copied through Wasm'
+    }
+  };
+}
+
+function responsePassthroughPolicyFields() {
+  return {
+    policy: {
+      phase: STREAMING_PHASE,
+      hostOwnsStream: true,
+      headerMergeIsOrdered: true,
+      platformBindings: false,
+      assetSemantics: false
+    },
+    headerMergeRules: RESPONSE_HEADER_MERGE_RULES.slice(),
+    streamOwnership: {
+      owner: 'host',
+      wasmRepresentation: 'opaque ref only',
+      hostCopiesBytesIntoWasm: false,
+      resultExtraction: 'host maps ref back to host stream/response and copies no body bytes',
+      lifetime: 'active request/result lifetime'
+    },
+    failureAndCancellation: {
+      beforeResponseStarts: 'normal Pulse error/result path',
+      afterResponseStarts: 'host/platform transport policy',
+      clientDisconnect: 'host cancels stream if platform supports cancellation',
+      contextExpiresBeforeStreamStarts: '504 PULSEWASM_CONTEXT_TIMEOUT',
+      contextExpiresAfterStreamStarts: 'host/platform policy'
+    }
+  };
+}
+
+module.exports = {
+  STREAMING_PASSTHROUGH_VERSION,
+  STREAM_RESULT_ABI_VERSION,
+  RESPONSE_PASSTHROUGH_POLICY_VERSION,
+  STREAMING_PHASE,
+  STREAMING_SMOKE_VERSION,
+  STREAM_RESULT_ABI_EXPORTS,
+  RESPONSE_HEADER_MERGE_RULES,
+  streamResultAbiFields,
+  responsePassthroughPolicyFields
+};