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

package/src/handler/beta-lifecycle-golden.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const BETA_LIFECYCLE_GOLDEN_VERSION = 'pulsewasm.beta-lifecycle-golden.v1';
+const BETA_LIFECYCLE_GOLDEN_PHASE = '51';
+const BETA_LIFECYCLE_GOLDEN_ARTIFACT = 'beta-lifecycle-golden.json';
+const BETA_LIFECYCLE_GOLDEN_CONTRACT_ID = 'pulse.beta-lifecycle-golden';
+
+const BETA_LIFECYCLE_GOLDEN_AUTHORING_SUBSET = Object.freeze({
+  asyncAwait: false,
+  promises: false,
+  loops: false,
+  dynamicBackends: false,
+  dynamicAssetKeys: false,
+  arbitraryObjectLowering: false,
+  automaticSchemaGeneration: false,
+  binaryBodies: false,
+  streams: false,
+  multipart: false,
+  uploads: false,
+  generalObjectStoreSemantics: false
+});
+
+const BETA_LIFECYCLE_GOLDEN_SCOPE = Object.freeze({
+  betaApp: 'examples/beta-lifecycle/app.js',
+  referenceApp: 'examples/reference-node-lifecycle/app.js',
+  assetsPackageOutApp: 'examples/assets-package-out/app.js',
+  command: 'node wasm/scripts/run-wasm-tests.cjs --profile release --no-report',
+  publicSurfaceOnly: true,
+  compilerOrchestrates: true,
+  packageOwnedLowering: true,
+  packageOutDiscovery: true,
+  providersOwnProviderBehavior: true,
+  nodeReferenceLifecycle: 'implemented',
+  nodeCompiledWasmResolveResume: 'implemented',
+  nodeCompiledWasmAssets: 'implemented-narrow-terminal-get-head-text',
+  fastlyReferenceLifecycle: 'symbolic-parity',
+  fastlyPostJsonRequestBodies: 'plan-only',
+  fastlyCompiledWasmAssets: 'plan-only',
+  noReferenceAppSpecialPath: true,
+  noBetaAppSpecialPath: true,
+  noHiddenEagerWork: true,
+  noUserAuthoredAsync: true,
+  promises: false,
+  asyncAwait: false,
+  asyncify: false,
+  authoringSubset: BETA_LIFECYCLE_GOLDEN_AUTHORING_SUBSET
+});
+
+const BETA_LIFECYCLE_GOLDEN_POLICY = Object.freeze({
+  purpose: 'beta-quality lifecycle harness for trying small apps across backend effects, schema JSON, package-owned lowerers, and provider readiness',
+  productionCompletenessRequired: false,
+  productionAssetServingTarget: false,
+  simpleUserFunctionLoweringIntentional: true,
+  appBoundary: 'beta/reference apps use only public router, ctx, and package lowerable facades',
+  harnessBoundary: 'tests and proof builders may orchestrate origins, package-out fixtures, providers, and CLI commands',
+  requiredCommand: 'node wasm/scripts/run-wasm-tests.cjs --profile release --no-report',
+  validates: Object.freeze([
+    'combined beta lifecycle example app',
+    'reference Node lifecycle golden lane',
+    'assets package-owned lowering',
+    'assets package-out discovery',
+    'assets compiled-Wasm sidecar readiness',
+    'assets sidecar compile/link proof',
+    'Node compiled-Wasm assets lifecycle proof',
+    'Fastly lifecycle parity classification',
+    'Fastly assets package-out parity classification',
+    'CLI plan/doctor/build for the combined beta app',
+    'router.head public route method support',
+    'route/method consistency for HEAD asset routes',
+    'docs for beta authoring subset and diagnostics',
+    'canonical alpha artifact path hygiene'
+  ]),
+  authoringSubset: BETA_LIFECYCLE_GOLDEN_AUTHORING_SUBSET,
+  outOfScope: Object.freeze([
+    'production asset CDN semantics',
+    'binary asset bodies',
+    'compiled-Wasm stream asset bodies',
+    'range requests',
+    'uploads',
+    'cache invalidation',
+    'arbitrary third-party lowerer execution',
+    'async/await lowering',
+    'Promise lowering',
+    'automatic schema generation',
+    'arbitrary JavaScript object lowering'
+  ])
+});
+
+module.exports = {
+  BETA_LIFECYCLE_GOLDEN_VERSION,
+  BETA_LIFECYCLE_GOLDEN_PHASE,
+  BETA_LIFECYCLE_GOLDEN_ARTIFACT,
+  BETA_LIFECYCLE_GOLDEN_CONTRACT_ID,
+  BETA_LIFECYCLE_GOLDEN_AUTHORING_SUBSET,
+  BETA_LIFECYCLE_GOLDEN_SCOPE,
+  BETA_LIFECYCLE_GOLDEN_POLICY
+};

package/src/handler/canonical-native-plan.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const CANONICAL_NATIVE_PLAN_VERSION = 'pulse.canonical-native-plan.v2';
+const CANONICAL_NATIVE_PLAN_HASH_ALGORITHM = 'sha256';
+const CANONICAL_NATIVE_PLAN_OWNERSHIP_VERSION = 'pulse.canonical-native-ownership.v1';
+
+const CANONICAL_NATIVE_STATEMENT_KINDS = Object.freeze([
+  'local',
+  'effect',
+  'effect-group',
+  'if',
+  'return',
+  'expression'
+]);
+
+const CANONICAL_NATIVE_EXPRESSION_KINDS = Object.freeze([
+  'literal',
+  'undefined',
+  'local',
+  'context-read',
+  'array',
+  'object',
+  'template',
+  'binary',
+  'unary',
+  'conditional',
+  'property',
+  'element',
+  'intrinsic',
+  'method-call',
+  'assignment',
+  'update',
+  'spread'
+]);
+
+const CANONICAL_NATIVE_CONTEXT_READS = Object.freeze([
+  'req.method',
+  'req.url',
+  'req.path',
+  'req.headers',
+  'event.payload'
+]);
+
+const CANONICAL_NATIVE_INTRINSICS = Object.freeze([
+  'request.header',
+  'request.text',
+  'request.json',
+  'response.json',
+  'response.text',
+  'response.custom',
+  'kv.namespace',
+  'state.get',
+  'state.set',
+  'logging.emit',
+  'event.runtime-id',
+  'router.match',
+  'router.param',
+  'grip.is-websocket',
+  'grip.subscribe',
+  'grip.handoff'
+]);
+
+const CANONICAL_NATIVE_DECODER_KINDS = Object.freeze([
+  'json',
+  'text'
+]);
+
+const CANONICAL_NATIVE_RESULT_MODES = Object.freeze([
+  'bind',
+  'bind-group',
+  'discard',
+  'return'
+]);
+
+const CANONICAL_NATIVE_VALUE_KINDS = Object.freeze([
+  'unknown',
+  'undefined',
+  'null',
+  'boolean',
+  'number',
+  'string',
+  'string-or-undefined',
+  'headers',
+  'array',
+  'object',
+  'json',
+  'json-or-undefined',
+  'fetch-response',
+  'kv-namespace',
+  'pulse-result',
+  'opaque-response',
+  'structured-response',
+  'ack'
+]);
+
+const CANONICAL_NATIVE_PLAN_DIAGNOSTIC_CODES = Object.freeze({
+  COMPILED_PROGRAM_REQUIRED: 'PULSE_CANONICAL_NATIVE_COMPILED_PROGRAM_REQUIRED',
+  GENERATED_HANDLER_MISSING: 'PULSE_CANONICAL_NATIVE_HANDLER_MISSING',
+  GENERATED_HANDLER_DUPLICATE: 'PULSE_CANONICAL_NATIVE_HANDLER_DUPLICATE',
+  STATEMENT_UNSUPPORTED: 'PULSE_CANONICAL_NATIVE_STATEMENT_UNSUPPORTED',
+  EXPRESSION_UNSUPPORTED: 'PULSE_CANONICAL_NATIVE_EXPRESSION_UNSUPPORTED',
+  BINDING_UNSUPPORTED: 'PULSE_CANONICAL_NATIVE_BINDING_UNSUPPORTED',
+  LOCAL_UNRESOLVED: 'PULSE_CANONICAL_NATIVE_LOCAL_UNRESOLVED',
+  EFFECT_INVALID: 'PULSE_CANONICAL_NATIVE_EFFECT_INVALID',
+  EFFECT_MISMATCH: 'PULSE_CANONICAL_NATIVE_EFFECT_MISMATCH',
+  CONTINUATION_MISMATCH: 'PULSE_CANONICAL_NATIVE_CONTINUATION_MISMATCH',
+  EVENT_HANDLER_INELIGIBLE: 'PULSE_CANONICAL_NATIVE_EVENT_HANDLER_INELIGIBLE',
+  LOG_INVALID: 'PULSE_CANONICAL_NATIVE_LOG_INVALID',
+  PLAN_INVALID: 'PULSE_CANONICAL_NATIVE_PLAN_INVALID'
+});
+
+const CANONICAL_NATIVE_PLAN_POLICY = Object.freeze({
+  version: CANONICAL_NATIVE_PLAN_VERSION,
+  ownershipVersion: CANONICAL_NATIVE_PLAN_OWNERSHIP_VERSION,
+  providerNeutral: true,
+  providerSelected: false,
+  providerSdkUserland: false,
+  javascriptRuntime: false,
+  promiseSemantics: false,
+  asyncify: false,
+  controlFlow: 'structured straight-line statements plus if/else branches',
+  suspension: 'explicit effect and effect-group statements with stable continuation IDs',
+  values: 'versioned JSON expression tree with stable local identities',
+  logging: 'compile-time threshold pruning plus synchronous provider-adapter emission',
+  schemas: 'canonical compiled schema registry and explicit schema references',
+  crypto: 'explicit preselected realization plan; guest source remains package-owned and fallback-free',
+  packages: 'trusted package-owned canonical effects and pure intrinsic records only'
+});
+
+module.exports = Object.freeze({
+  CANONICAL_NATIVE_PLAN_VERSION,
+  CANONICAL_NATIVE_PLAN_HASH_ALGORITHM,
+  CANONICAL_NATIVE_PLAN_OWNERSHIP_VERSION,
+  CANONICAL_NATIVE_STATEMENT_KINDS,
+  CANONICAL_NATIVE_EXPRESSION_KINDS,
+  CANONICAL_NATIVE_CONTEXT_READS,
+  CANONICAL_NATIVE_INTRINSICS,
+  CANONICAL_NATIVE_DECODER_KINDS,
+  CANONICAL_NATIVE_RESULT_MODES,
+  CANONICAL_NATIVE_VALUE_KINDS,
+  CANONICAL_NATIVE_PLAN_DIAGNOSTIC_CODES,
+  CANONICAL_NATIVE_PLAN_POLICY
+});

package/src/handler/canonical-native-runtime.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const CANONICAL_NATIVE_WASM_VERSION = 'pulse.canonical-native-wasm.v2';
+const CANONICAL_NATIVE_ABI_VERSION = 2;
+const CANONICAL_NATIVE_AS_GENERATOR_VERSION = 'pulse.canonical-native-as-generator.v3';
+const CANONICAL_NATIVE_COMPILER_VERSION = 'pulse.canonical-native-wasm-compiler.v3';
+const CANONICAL_NATIVE_HOST_VERSION = 'pulse.canonical-native-host.v3';
+
+const CANONICAL_NATIVE_RUN_STATUS = Object.freeze({
+  COMPLETE: 0,
+  SUSPENDED: 1,
+  FAILED: -1,
+  INVALID_RESUME: -2
+});
+
+const CANONICAL_NATIVE_RESULT_STATUS = Object.freeze({
+  REJECTED: 0,
+  ACCEPTED: 1
+});
+
+const CANONICAL_NATIVE_ERROR_CODES = Object.freeze({
+  NONE: 0,
+  INVALID_START: 1,
+  INCOMPLETE_RESUME: 2,
+  INVALID_EFFECT_RESULT: 3,
+  FALLTHROUGH_WITHOUT_RESULT: 4,
+  HOST_FAILURE: 5,
+  INVALID_PROGRAM_COUNTER: 6
+});
+
+const CANONICAL_NATIVE_BINARY_OPERATORS = Object.freeze([
+  '===', '!==', '==', '!=', '<', '<=', '>', '>=', '+', '-', '*', '/', '%', '**',
+  '&&', '||', '??', '&', '|', '^', '<<', '>>', '>>>', 'in'
+]);
+
+const CANONICAL_NATIVE_UNARY_OPERATORS = Object.freeze([
+  '!', '+', '-', '~', 'typeof', 'void'
+]);
+
+const CANONICAL_NATIVE_ASSIGNMENT_OPERATORS = Object.freeze([
+  '=', '+=', '-=', '*=', '/=', '%=', '**=', '&&=', '||=', '??=', '&=', '|=', '^=', '<<=', '>>=', '>>>='
+]);
+
+const CANONICAL_NATIVE_IMPORT_MODULE = 'pulse_host';
+const CANONICAL_NATIVE_ALLOWED_ENV_IMPORTS = Object.freeze(['abort', 'seed']);
+const CANONICAL_NATIVE_IMPORTS = Object.freeze([
+  ['value_undefined', [], ['i32']],
+  ['value_null', [], ['i32']],
+  ['value_boolean', ['i32'], ['i32']],
+  ['value_number', ['f64'], ['i32']],
+  ['value_string', ['i32', 'i32'], ['i32']],
+  ['value_array', [], ['i32']],
+  ['value_array_push', ['i32', 'i32'], []],
+  ['value_array_spread', ['i32', 'i32'], []],
+  ['value_object', [], ['i32']],
+  ['value_object_set', ['i32', 'i32', 'i32'], []],
+  ['value_object_spread', ['i32', 'i32'], []],
+  ['value_property', ['i32', 'i32'], ['i32']],
+  ['value_property_set', ['i32', 'i32', 'i32'], ['i32']],
+  ['value_element', ['i32', 'i32'], ['i32']],
+  ['value_element_set', ['i32', 'i32', 'i32'], ['i32']],
+  ['value_binary', ['i32', 'i32', 'i32'], ['i32']],
+  ['value_unary', ['i32', 'i32'], ['i32']],
+  ['value_truthy', ['i32'], ['i32']],
+  ['value_nullish', ['i32'], ['i32']],
+  ['log', ['i32', 'i32'], []],
+  ['request_method', [], ['i32']],
+  ['request_url', [], ['i32']],
+  ['request_path', [], ['i32']],
+  ['request_headers', [], ['i32']],
+  ['request_header', ['i32'], ['i32']],
+  ['request_text', [], ['i32']],
+  ['request_json', ['i32'], ['i32']],
+  ['router_match', ['i32', 'i32'], ['i32']],
+  ['router_param', ['i32', 'i32', 'i32'], ['i32']],
+  ['response_json', ['i32', 'i32'], ['i32']],
+  ['response_text', ['i32', 'i32'], ['i32']],
+  ['response_custom', ['i32'], ['i32']],
+  ['grip_is_websocket', [], ['i32']],
+  ['grip_subscribe', ['i32', 'i32'], ['i32']],
+  ['grip_handoff', ['i32'], ['i32']],
+  ['kv_namespace', ['i32'], ['i32']],
+  ['fetch_json', ['i32', 'i32'], ['i32']],
+  ['fetch_text', ['i32'], ['i32']],
+  ['fetch_header', ['i32', 'i32'], ['i32']],
+  ['effect_begin', ['i32', 'i32'], []]
+]);
+
+const CANONICAL_NATIVE_EXPORTS = Object.freeze([
+  ['memory', 'memory'],
+  ['pulse_abi_version', [], ['i32']],
+  ['pulse_plan_hash_ptr', [], ['i32']],
+  ['pulse_plan_hash_length', [], ['i32']],
+  ['pulse_start', [], ['i32']],
+  ['pulse_resume', [], ['i32']],
+  ['pulse_set_effect_result', ['i32', 'i32'], ['i32']],
+  ['pulse_result_handle', [], ['i32']],
+  ['pulse_program_counter', [], ['i32']],
+  ['pulse_continuation_state', [], ['i32']],
+  ['pulse_last_error_code', [], ['i32']],
+  ['pulse_pending_count', [], ['i32']]
+]);
+
+const CANONICAL_NATIVE_SCHEMA_EXPORTS = Object.freeze([
+  ['__new', ['i32', 'i32'], ['i32']],
+  ['__pin', ['i32'], ['i32']],
+  ['__unpin', ['i32'], []],
+  ['pulse_schema_string_id', [], ['i32']],
+  ['pulse_schema_decode', ['i32', 'i32'], ['i32']],
+  ['pulse_schema_encode', ['i32', 'i32'], ['i32']]
+]);
+
+const CANONICAL_NATIVE_IMPORT_NAMES = Object.freeze(CANONICAL_NATIVE_IMPORTS.map(([name]) => name));
+const CANONICAL_NATIVE_EXPORT_NAMES = Object.freeze(CANONICAL_NATIVE_EXPORTS.map(([name]) => name));
+const CANONICAL_NATIVE_SCHEMA_EXPORT_NAMES = Object.freeze(CANONICAL_NATIVE_SCHEMA_EXPORTS.map(([name]) => name));
+
+const CANONICAL_NATIVE_DIAGNOSTIC_CODES = Object.freeze({
+  PLAN_REQUIRED: 'PULSE_CANONICAL_NATIVE_WASM_PLAN_REQUIRED',
+  PLAN_INVALID: 'PULSE_CANONICAL_NATIVE_WASM_PLAN_INVALID',
+  STATEMENT_UNSUPPORTED: 'PULSE_CANONICAL_NATIVE_WASM_STATEMENT_UNSUPPORTED',
+  EXPRESSION_UNSUPPORTED: 'PULSE_CANONICAL_NATIVE_WASM_EXPRESSION_UNSUPPORTED',
+  LOCAL_UNRESOLVED: 'PULSE_CANONICAL_NATIVE_WASM_LOCAL_UNRESOLVED',
+  EFFECT_UNRESOLVED: 'PULSE_CANONICAL_NATIVE_WASM_EFFECT_UNRESOLVED',
+  ASSEMBLYSCRIPT_MISSING: 'PULSE_CANONICAL_NATIVE_WASM_ASC_MISSING',
+  ASSEMBLYSCRIPT_FAILED: 'PULSE_CANONICAL_NATIVE_WASM_ASC_FAILED',
+  WASM_INVALID: 'PULSE_CANONICAL_NATIVE_WASM_INVALID',
+  ABI_INVALID: 'PULSE_CANONICAL_NATIVE_WASM_ABI_INVALID'
+});
+
+const CANONICAL_NATIVE_POLICY = Object.freeze({
+  providerNeutral: true,
+  providerSelected: false,
+  javascriptRuntime: false,
+  asyncify: false,
+  promiseSemantics: false,
+  valueOwnership: 'host-owned opaque i32 handles; generated Wasm owns control flow and local identities',
+  controlFlow: 'generated AssemblyScript state machine with stable basic blocks',
+  suspension: 'effect_begin records descriptors before one explicit suspension boundary; results are injected before pulse_resume',
+  groupedEffects: 'all group members begin before one suspension boundary and all results must be ready before resume',
+  incompleteResume: 'rejected without advancing the program counter or consuming available results',
+  authority: 'request data and consequential effects remain host-owned; guest control flow remains authoritative',
+  schemaJson: 'normalized registry IR generates json-as 1.5.0 guest codecs; host preflight enforces shared policy and structured errors',
+  schemaBodyOwnership: 'request and fetched-response bytes are snapshotted once; application JSON values are encoded before suspension'
+});
+
+module.exports = Object.freeze({
+  CANONICAL_NATIVE_WASM_VERSION,
+  CANONICAL_NATIVE_ABI_VERSION,
+  CANONICAL_NATIVE_AS_GENERATOR_VERSION,
+  CANONICAL_NATIVE_COMPILER_VERSION,
+  CANONICAL_NATIVE_HOST_VERSION,
+  CANONICAL_NATIVE_RUN_STATUS,
+  CANONICAL_NATIVE_RESULT_STATUS,
+  CANONICAL_NATIVE_ERROR_CODES,
+  CANONICAL_NATIVE_BINARY_OPERATORS,
+  CANONICAL_NATIVE_UNARY_OPERATORS,
+  CANONICAL_NATIVE_ASSIGNMENT_OPERATORS,
+  CANONICAL_NATIVE_IMPORT_MODULE,
+  CANONICAL_NATIVE_ALLOWED_ENV_IMPORTS,
+  CANONICAL_NATIVE_IMPORTS,
+  CANONICAL_NATIVE_IMPORT_NAMES,
+  CANONICAL_NATIVE_EXPORTS,
+  CANONICAL_NATIVE_EXPORT_NAMES,
+  CANONICAL_NATIVE_SCHEMA_EXPORTS,
+  CANONICAL_NATIVE_SCHEMA_EXPORT_NAMES,
+  CANONICAL_NATIVE_DIAGNOSTIC_CODES,
+  CANONICAL_NATIVE_POLICY
+});

package/src/handler/canonical-runtime.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const CANONICAL_PROGRAM_VERSION = 'pulse.canonical-program.v2';
+const CANONICAL_RUNTIME_PROTOCOL_VERSION = 'pulse.canonical-runtime-protocol.v2';
+const CANONICAL_EFFECT_MARKER_KINDS = Object.freeze(['effect', 'group']);
+const CANONICAL_PACKAGE_EFFECT_VERSION = 'pulse.canonical-package-effect.v1';
+
+module.exports = Object.freeze({
+  CANONICAL_PROGRAM_VERSION,
+  CANONICAL_RUNTIME_PROTOCOL_VERSION,
+  CANONICAL_EFFECT_MARKER_KINDS,
+  CANONICAL_PACKAGE_EFFECT_VERSION
+});

package/src/handler/context.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const ROUTE_HANDLER_CONTEXT_LOWERING_VERSION = 'pulsewasm.route-handler-context-lowering.v1';
+const ROUTE_HANDLER_CONTEXT_LOWERING_PHASE = '31';
+const ROUTE_HANDLER_CONTEXT_LOWERING_ARTIFACT = 'route-handler-context-lowering-plan.json';
+const ROUTE_HANDLER_CONTEXT_CONTRACT_ID = 'pulse.route-handler-context';
+
+const ROUTE_HANDLER_CONTEXT_PLAN_SCOPE = Object.freeze({
+  syncContextLowering: true,
+  runtimeBehaviorChanged: true,
+  providerBehaviorImplemented: false,
+  effectExecutionImplemented: false,
+  asyncAwait: false,
+  promises: false,
+  asyncify: false,
+  closureCapture: false
+});
+
+const ROUTE_HANDLER_CONTEXT_SYNC_SURFACE = Object.freeze([
+  'ctx.param',
+  'ctx.paramI32',
+  'ctx.request.method',
+  'ctx.request.path',
+  'ctx.state.get',
+  'ctx.state.set',
+  'ctx.request.header.first',
+  'ctx.request.header.count',
+  'ctx.request.header.at',
+  'ctx.response.header.set',
+  'ctx.response.header.append',
+  'ctx.response.header.delete',
+  'ctx.result.text',
+  'ctx.result.jsonText',
+  'ctx.result.empty',
+  'ctx.error',
+  'next',
+  'next(error)'
+]);
+
+const ROUTE_HANDLER_CONTEXT_RESERVED_SURFACE = Object.freeze([
+  'ctx.fetch',
+  'ctx.resolve',
+  'ctx.resolved',
+  'ctx.bodyText',
+  'ctx.request.body',
+  'ctx.request.json',
+  'ctx.request.arrayBuffer',
+  'global fetch',
+  'Promise',
+  'async/await'
+]);
+
+const ROUTE_HANDLER_CONTEXT_EXPRESSION_SUBSET = Object.freeze({
+  literals: Object.freeze(['string', 'number', 'boolean']),
+  identifiers: 'locals declared in the same handler body',
+  binaryOperators: Object.freeze(['+', '-', '*', '/', '%', '===', '!==', '==', '!=', '<', '<=', '>', '>=', '&&', '||']),
+  unaryOperators: Object.freeze(['!']),
+  branches: 'if/else is lowerable when branches remain within the same synchronous context surface',
+  rejected: Object.freeze([
+    'loops',
+    'switch',
+    'try/catch/throw',
+    'classes/new',
+    'destructuring',
+    'spread/rest',
+    'computed property access',
+    'dynamic ctx member access',
+    'inline closure capture',
+    'nested functions',
+    'recursion',
+    'Promise',
+    'async/await',
+    'ctx.resolve runtime execution'
+  ])
+});
+
+const ROUTE_HANDLER_CONTEXT_DIAGNOSTICS = Object.freeze({
+  handlerSourceMissing: 'PULSEWASM_CONTEXT_HANDLER_SOURCE_MISSING',
+  parameterUnsupported: 'PULSEWASM_CONTEXT_PARAMETER_UNSUPPORTED',
+  captureUnsupported: 'PULSEWASM_CONTEXT_CAPTURE_UNSUPPORTED',
+  destructuringUnsupported: 'PULSEWASM_CONTEXT_DESTRUCTURING_UNSUPPORTED',
+  loopUnsupported: 'PULSEWASM_CONTEXT_LOOP_UNSUPPORTED',
+  asyncUnsupported: 'PULSEWASM_CONTEXT_ASYNC_UNSUPPORTED',
+  promiseUnsupported: 'PULSEWASM_CONTEXT_PROMISE_UNSUPPORTED',
+  throwUnsupported: 'PULSEWASM_CONTEXT_THROW_UNSUPPORTED',
+  classUnsupported: 'PULSEWASM_CONTEXT_CLASS_UNSUPPORTED',
+  computedPropertyUnsupported: 'PULSEWASM_CONTEXT_COMPUTED_PROPERTY_UNSUPPORTED',
+  unsupportedStatement: 'PULSEWASM_CONTEXT_UNSUPPORTED_STATEMENT',
+  unsupportedExpression: 'PULSEWASM_CONTEXT_UNSUPPORTED_EXPRESSION',
+  unsupportedCall: 'PULSEWASM_CONTEXT_UNSUPPORTED_CALL',
+  unsupportedContextSurface: 'PULSEWASM_CONTEXT_UNSUPPORTED_SURFACE',
+  effectBoundaryReserved: 'PULSEWASM_CONTEXT_EFFECT_BOUNDARY_RESERVED',
+  effectUnsupported: 'PULSEWASM_CONTEXT_EFFECT_UNSUPPORTED',
+  resultTerminalConflict: 'PULSEWASM_CONTEXT_TERMINAL_CONFLICT',
+  ifBranchUnsupported: 'PULSEWASM_CONTEXT_IF_BRANCH_UNSUPPORTED'
+});
+
+function defaultRouteHandlerContextLoweringPolicy() {
+  return {
+    ...ROUTE_HANDLER_CONTEXT_PLAN_SCOPE,
+    contractId: ROUTE_HANDLER_CONTEXT_CONTRACT_ID,
+    artifact: ROUTE_HANDLER_CONTEXT_LOWERING_ARTIFACT,
+    syncSurface: [...ROUTE_HANDLER_CONTEXT_SYNC_SURFACE],
+    reservedSurface: [...ROUTE_HANDLER_CONTEXT_RESERVED_SURFACE],
+    expressionSubset: JSON.parse(JSON.stringify(ROUTE_HANDLER_CONTEXT_EXPRESSION_SUBSET)),
+    lifecycle: {
+      handlerRunsSynchronously: true,
+      effectBoundaryReserved: true,
+      providerExecution: false,
+      wasmSuspension: false,
+      continuationReentry: 'ctx.resolve plan only; not implemented by Pass 31'
+    }
+  };
+}
+
+module.exports = {
+  ROUTE_HANDLER_CONTEXT_LOWERING_VERSION,
+  ROUTE_HANDLER_CONTEXT_PLAN_VERSION: ROUTE_HANDLER_CONTEXT_LOWERING_VERSION,
+  ROUTE_HANDLER_CONTEXT_LOWERING_PHASE,
+  ROUTE_HANDLER_CONTEXT_PLAN_PHASE: ROUTE_HANDLER_CONTEXT_LOWERING_PHASE,
+  ROUTE_HANDLER_CONTEXT_LOWERING_ARTIFACT,
+  ROUTE_HANDLER_CONTEXT_PLAN_ARTIFACT: ROUTE_HANDLER_CONTEXT_LOWERING_ARTIFACT,
+  ROUTE_HANDLER_CONTEXT_CONTRACT_ID,
+  ROUTE_HANDLER_CONTEXT_PLAN_SCOPE,
+  ROUTE_HANDLER_CONTEXT_SYNC_SURFACE,
+  ROUTE_HANDLER_CONTEXT_RESERVED_SURFACE,
+  ROUTE_HANDLER_CONTEXT_EXPRESSION_SUBSET,
+  ROUTE_HANDLER_CONTEXT_DIAGNOSTICS,
+  defaultRouteHandlerContextLoweringPolicy,
+  defaultRouteHandlerContextPolicy: defaultRouteHandlerContextLoweringPolicy
+};

package/src/handler/ctx-contract.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { HANDLER_SURFACE_DEFINITIONS, HANDLER_SURFACE_CONTRACT_VERSION } = require('./surface-contract.js');
+
+const CTX_CONTRACT_VERSION = 'pulse.ctx-contract.v4';
+const CTX_CONTRACT_ID = 'pulse.ctx';
+const CTX_SURFACE_IDS = Object.freeze([
+  'ctx.param','ctx.req.method','ctx.req.url','ctx.req.path','ctx.req.header','ctx.req.headers',
+  'ctx.state.get','ctx.state.set','ctx.json','ctx.text','ctx.response','ctx.req.text','ctx.req.json.schema',
+  'ctx.req.json.generic','ctx.fetch.projected','ctx.fetch.opaque-return','ctx.config.get','ctx.secret.get',
+  'ctx.kv.get','ctx.kv.put','ctx.kv.getVersioned','ctx.kv.insertIfAbsent','ctx.kv.compareAndSwap','ctx.emit','package.operation'
+]);
+const surfaceById = new Map(HANDLER_SURFACE_DEFINITIONS.map((entry) => [entry.id, entry]));
+const CTX_SURFACES = Object.freeze(CTX_SURFACE_IDS.map((id) => {
+  const surface = surfaceById.get(id);
+  if (!surface) throw new TypeError(`Missing handler-surface definition for ctx contract entry ${id}.`);
+  return Object.freeze({
+    id: surface.id,
+    class: surface.class,
+    canonicalOperation: surface.canonicalOperation,
+    awaitPolicy: surface.awaitPolicy,
+    publicForms: surface.publicForms,
+    nativeEligible: surface.targetSupport.native,
+    javascriptSupported: surface.targetSupport.javascript,
+    schemaPolicy: surface.schemaPolicy || null,
+    redaction: surface.redaction || null
+  });
+}));
+function defaultCtxContract() {
+  return Object.freeze({
+    version: CTX_CONTRACT_VERSION,
+    contractId: CTX_CONTRACT_ID,
+    handlerSurfaceVersion: HANDLER_SURFACE_CONTRACT_VERSION,
+    surfaces: CTX_SURFACES,
+    planes: Object.freeze({
+      sharedAuthoring: Object.freeze(['state', 'log', 'fetch', 'parallel', 'config', 'secret', 'kv', 'emit']),
+      httpAuthoring: Object.freeze(['req', 'json', 'text', 'response']),
+      routeAuthoring: Object.freeze(['param']),
+      eventAuthoring: Object.freeze(['event.type', 'event.payload']),
+      eventExecutionImplemented: true,
+      emitPublished: true,
+      emitJavascriptExecutionImplemented: true,
+      emitNativeExecutionImplemented: false
+    }),
+    policies: Object.freeze({
+      handlersAsyncShaped: true,
+      syncAwaitIsWarning: true,
+      effectAwaitRequiredWhenConsumed: true,
+      terminalNextAwaitForbidden: true,
+      stateRepresentation: 'execution-local-string-map',
+      stateMissingValue: 'undefined',
+      stateClearedPerRequest: true,
+      stateClearedPerExecution: true,
+      nativePromiseRuntime: false,
+      nativeAsyncify: false,
+      packageCapabilitiesManifestClassified: true
+    })
+  });
+}
+function validateCtxContract(contract = defaultCtxContract()) {
+  if (contract.version !== CTX_CONTRACT_VERSION) throw new TypeError(`Unsupported ctx contract version ${contract.version}.`);
+  const ids = new Set();
+  for (const surface of contract.surfaces) {
+    if (ids.has(surface.id)) throw new TypeError(`Duplicate ctx surface ${surface.id}.`);
+    ids.add(surface.id);
+  }
+  if (ids.size !== CTX_SURFACE_IDS.length) throw new TypeError('ctx contract surface count does not match its sealed ID list.');
+  if (contract.policies.nativePromiseRuntime !== false || contract.policies.nativeAsyncify !== false) throw new TypeError('Native ctx lowering must remain Promise-free and Asyncify-free.');
+  return contract;
+}
+module.exports = Object.freeze({ CTX_CONTRACT_VERSION, CTX_CONTRACT_ID, CTX_SURFACE_IDS, CTX_SURFACES, defaultCtxContract, validateCtxContract });