@pulse-compute/wasm-contracts 1.0.0-beta.3 → 1.0.0-beta.5

package/README.md

@@ -7,9 +7,9 @@
 > **Supported entry points:** `@pulse-compute/wasm-contracts/provider/toolchain`<br>
 > **Stability:** The provider toolchain contract is versioned and supported for the Beta; other protocol and proof interfaces remain internal.<br>
 > **npm:** [`@pulse-compute/wasm-contracts`](https://www.npmjs.com/package/@pulse-compute/wasm-contracts)<br>
-> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.3/packages/implementation-packages/)
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.5/packages/implementation-packages/)
 >
-> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.3` package policy.
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.5` package policy.
 <!-- pulse-package-status:end -->
 
 This package owns stable data contracts shared by the compiler, runtime, and providers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-compute/wasm-contracts",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "license": "Apache-2.0",
   "engines": {
     "node": "^22.14.0 || ^24.0.0"
@@ -126,7 +126,7 @@
     "url": "git+https://github.com/pulse-compute/pulse.git",
     "directory": "wasm/packages/contracts"
   },
-  "homepage": "https://pulsecompute.io/v1.0.0-beta.3/packages/implementation-packages/",
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.5/packages/implementation-packages/",
   "bugs": {
     "url": "https://github.com/pulse-compute/pulse/issues"
   }

package/src/diagnostics.js

@@ -2,7 +2,7 @@
 
 const path = require('node:path');
 
-const PACKAGE_VERSION = 'pulsewasm-route-extractor@1.0.0-beta.3';
+const PACKAGE_VERSION = 'pulsewasm-route-extractor@1.0.0-beta.5';
 const DIAGNOSTICS_VERSION = 'pulsewasm.diagnostics.v1';
 
 function stableFileName(fileName, cwd) {

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

@@ -3,12 +3,16 @@
 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_PURE_LOOP_LIMITS = Object.freeze({ maxIterations: 1024, maxNestedIterations: 65536 });
 
 const CANONICAL_NATIVE_STATEMENT_KINDS = Object.freeze([
   'local',
   'effect',
   'effect-group',
   'if',
+  'pure-loop',
+  'break',
+  'continue',
   'return',
   'expression'
 ]);
@@ -46,6 +50,8 @@ const CANONICAL_NATIVE_INTRINSICS = Object.freeze([
   'request.text',
   'request.json',
   'response.json',
+  'schema.encode.text',
+  'schema.decode.text',
   'response.text',
   'response.custom',
   'kv.namespace',
@@ -118,7 +124,7 @@ const CANONICAL_NATIVE_PLAN_POLICY = Object.freeze({
   javascriptRuntime: false,
   promiseSemantics: false,
   asyncify: false,
-  controlFlow: 'structured straight-line statements plus if/else branches',
+  controlFlow: 'structured statements, if/else, and literal-capped pure for loops; no effect iteration',
   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',
@@ -129,6 +135,7 @@ const CANONICAL_NATIVE_PLAN_POLICY = Object.freeze({
 
 module.exports = Object.freeze({
   CANONICAL_NATIVE_PLAN_VERSION,
+  CANONICAL_PURE_LOOP_LIMITS,
   CANONICAL_NATIVE_PLAN_HASH_ALGORITHM,
   CANONICAL_NATIVE_PLAN_OWNERSHIP_VERSION,
   CANONICAL_NATIVE_STATEMENT_KINDS,

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

@@ -63,6 +63,7 @@ const CANONICAL_NATIVE_IMPORTS = Object.freeze([
   ['value_unary', ['i32', 'i32'], ['i32']],
   ['value_truthy', ['i32'], ['i32']],
   ['value_nullish', ['i32'], ['i32']],
+  ['value_string_trim', ['i32'], ['i32']],
   ['log', ['i32', 'i32'], []],
   ['request_method', [], ['i32']],
   ['request_url', [], ['i32']],
@@ -73,7 +74,11 @@ const CANONICAL_NATIVE_IMPORTS = Object.freeze([
   ['request_json', ['i32'], ['i32']],
   ['router_match', ['i32', 'i32'], ['i32']],
   ['router_param', ['i32', 'i32', 'i32'], ['i32']],
+  // 0: no failure; positive: application error handle; negative: terminal failure.
+  ['router_error_take', [], ['i32']],
   ['response_json', ['i32', 'i32'], ['i32']],
+  ['schema_encode', ['i32', 'i32'], ['i32']],
+  ['schema_decode', ['i32', 'i32'], ['i32']],
   ['response_text', ['i32', 'i32'], ['i32']],
   ['response_custom', ['i32'], ['i32']],
   ['grip_is_websocket', [], ['i32']],

package/src/handler/ctx-contract.js

@@ -6,8 +6,8 @@ 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.state.get','ctx.state.set','ctx.encodeJson','ctx.decodeJson','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.time.now','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]));
@@ -33,7 +33,7 @@ function defaultCtxContract() {
     handlerSurfaceVersion: HANDLER_SURFACE_CONTRACT_VERSION,
     surfaces: CTX_SURFACES,
     planes: Object.freeze({
-      sharedAuthoring: Object.freeze(['state', 'log', 'fetch', 'parallel', 'config', 'secret', 'kv', 'emit']),
+      sharedAuthoring: Object.freeze(['state', 'log', 'time', 'fetch', 'parallel', 'config', 'secret', 'kv', 'emit', 'encodeJson', 'decodeJson']),
       httpAuthoring: Object.freeze(['req', 'json', 'text', 'response']),
       routeAuthoring: Object.freeze(['param']),
       eventAuthoring: Object.freeze(['event.type', 'event.payload']),

package/src/handler/runtime-api.js

@@ -12,6 +12,7 @@ const ERROR_KINDS = Object.freeze({
   fetchTimeout: 'FetchTimeoutError',
   bodyTooLarge: 'BodyTooLargeError',
   bodyDecode: 'BodyDecodeError',
+  requestBodyInvalidUtf8: 'RequestBodyInvalidUtf8Error',
   bodyUnavailable: 'BodyUnavailableError',
   opaqueBodyInspection: 'OpaqueBodyInspectionError',
   responseEncode: 'ResponseEncodeError',
@@ -113,7 +114,7 @@ function readInputBody(input) {
     : Object.prototype.hasOwnProperty.call(source, 'text')
       ? source.text
       : source.jsonText;
-  return { available: true, text: Buffer.isBuffer(value) ? value.toString('utf8') : String(value ?? '') };
+  return { available: true, value };
 }
 
 function createStructuredBodyValue(input = {}, options = {}) {
@@ -124,7 +125,8 @@ function createStructuredBodyValue(input = {}, options = {}) {
   const contentClass = classifyContentType(contentType);
   const forceStructured = options.forceStructured === true;
   const body = readInputBody(input);
-  const bytes = utf8ByteLength(body.text);
+  const raw = body.value instanceof Uint8Array ? body.value : undefined;
+  const bytes = raw ? raw.byteLength : utf8ByteLength(body.value);
   const counters = { bodyCopies: 0, textTransforms: 0, jsonTransforms: 0, errors: 0 };
   let textMemo;
   let jsonMemo;
@@ -156,12 +158,20 @@ function createStructuredBodyValue(input = {}, options = {}) {
       textMemo = rejected;
       return textMemo;
     }
+    let value;
+    try {
+      value = raw ? new TextDecoder('utf-8', { fatal: options.strictUtf8 === true, ignoreBOM: true }).decode(raw) : String(body.value ?? '');
+    } catch (_) {
+      counters.errors += 1;
+      textMemo = runtimeValueError(ERROR_KINDS.requestBodyInvalidUtf8, 'Pulse request text must be well-formed UTF-8.');
+      return textMemo;
+    }
     counters.bodyCopies += 1;
     counters.textTransforms += 1;
     textMemo = deepFreeze({
       ok: true,
       kind: 'structured-text',
-      value: String(body.text),
+      value,
       bytes,
       contentType: String(contentType || ''),
       contentClass,

package/src/handler/surface-contract.js

@@ -212,6 +212,30 @@ const HANDLER_SURFACE_DEFINITIONS = Object.freeze([
     nativeBehavior: 'construct-canonical-result',
     status: 'existing-alias-normalization'
   }),
+  surface({
+    id: 'ctx.decodeJson',
+    class: 'sync',
+    canonicalOperation: 'schema.decode.text',
+    publicForms: ["ctx.decodeJson<T>(text, 'schema.id')"],
+    awaitPolicy: 'optional-redundant-warning',
+    validPositions: ['expression', 'return', 'condition'],
+    targetSupport: { javascript: true, native: true },
+    nativeBehavior: 'decode-bounded-schema-text',
+    schemaPolicy: 'literal-schema-required',
+    status: 'supported'
+  }),
+  surface({
+    id: 'ctx.encodeJson',
+    class: 'sync',
+    canonicalOperation: 'schema.encode.text',
+    publicForms: ["ctx.encodeJson(value, 'schema.id')"],
+    awaitPolicy: 'optional-redundant-warning',
+    validPositions: ['expression', 'statement', 'return'],
+    targetSupport: { javascript: true, native: true },
+    nativeBehavior: 'schema-validated-bounded-json-text',
+    schemaPolicy: 'literal-schema-required',
+    status: 'supported'
+  }),
   surface({
     id: 'ctx.text',
     class: 'sync',
@@ -303,6 +327,17 @@ const HANDLER_SURFACE_DEFINITIONS = Object.freeze([
     nativeBehavior: 'emit-terminal-fetch-effect',
     status: 'supported'
   }),
+  surface({
+    id: 'ctx.time.now',
+    class: 'effect',
+    canonicalOperation: 'effect.time.now',
+    publicForms: ['ctx.time.now()'],
+    awaitPolicy: 'required-when-consumed',
+    validPositions: ['await-expression', 'parallel-member'],
+    targetSupport: { javascript: true, native: true },
+    nativeBehavior: 'emit-provider-wall-clock-effect-and-continuation',
+    status: 'supported'
+  }),
   surface({
     id: 'ctx.config.get',
     class: 'effect',

package/src/handler/types-contract.js

@@ -20,7 +20,7 @@ function defaultHandlerTypesContract() {
       set: 'void'
     }),
     executionContexts: Object.freeze({
-      shared: Object.freeze(['state', 'log', 'fetch', 'parallel', 'config', 'secret', 'kv', 'emit']),
+      shared: Object.freeze(['state', 'log', 'time', 'fetch', 'parallel', 'config', 'secret', 'kv', 'emit', 'encodeJson', 'decodeJson']),
       http: Object.freeze(['req', 'json', 'text', 'response']),
       route: Object.freeze(['param']),
       event: Object.freeze(['event.type', 'event.payload']),

package/src/provider/canonical-provider.js

@@ -9,6 +9,8 @@ const CANONICAL_PROVIDER_CAPABILITIES = Object.freeze([
   'response.text',
   'response.custom',
   'fetch',
+  'time.wall-clock',
+  'crypto.digestText',
   'config.get',
   'secret.get',
   'kv.get',

package/src/s3/contracts.js

@@ -3,7 +3,7 @@
 const S3_CONTRACT_ID = 'pulse.s3';
 const S3_PACKAGE = '@pulse-compute/s3';
 const S3_LOWERING_PLAN_VERSION = 'pulse.s3-lowering-plan.v1';
-const S3_LIMITS = Object.freeze({ keyBytes: 1024, textBytes: 32768, metadataBytes: 1024, headerBytes: 16384, envelopeBytes: 262144 });
+const S3_LIMITS = Object.freeze({ keyBytes: 1024, textBytes: 2097152, defaultTextBytes: 32768, metadataBytes: 1024, headerBytes: 16384, envelopeBytes: 12648448 });
 const S3_OPERATIONS = Object.freeze(Object.fromEntries(['head', 'getText', 'putText'].map((name) => [name, Object.freeze({
   kind: `s3.${name}`, capability: `s3.${name}`, result: name === 'head' ? 's3-head-result' : name === 'getText' ? 's3-get-text-result' : 's3-put-text-result'
 })])));

package/src/schema-json/registry.js

@@ -2,8 +2,8 @@
 
 const { sha256Hex, stableStringify } = require('../stable-id.js');
 
-const SCHEMA_REGISTRY_IR_VERSION = 'pulse.schema-registry-ir.v1';
-const SCHEMA_CODEC_INPUTS_VERSION = 'pulse.schema-codec-inputs.v1';
+const SCHEMA_REGISTRY_IR_VERSION = 'pulse.schema-registry-ir.v2';
+const SCHEMA_CODEC_INPUTS_VERSION = 'pulse.schema-codec-inputs.v2';
 const SCHEMA_AUTHORING_VERSION = 'pulse.schema-authoring.v1';
 const SCHEMA_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z][A-Za-z0-9_-]*)+$/;
 const RESPONSE_CASE_ID_PATTERN = SCHEMA_ID_PATTERN;
@@ -106,15 +106,15 @@ function normalizeSchemaNode(input, field = 'schema.root', stack = []) {
       throw schemaContractError('PULSE_SCHEMA_IR_FIELD_DUPLICATE', `${field} declares field ${name} more than once.`, { field, name });
     }
     names.add(name);
-    if (entry.required !== true) {
-      throw schemaContractError('PULSE_SCHEMA_OPTIONAL_FIELD_RESERVED', `${field}.${name} must be required in schema IR v1.`, {
+    if (typeof entry.required !== 'boolean') {
+      throw schemaContractError('PULSE_SCHEMA_IR_FIELD_REQUIRED', `${field}.${name}.required must be a boolean.`, {
         field,
         name
       });
     }
     return Object.freeze({
       name,
-      required: true,
+      required: entry.required,
       value: normalizeSchemaNode(entry.value, `${field}.fields[${index}].value`, [...stack, name]),
       source: entry.source ? normalizeSource(entry.source, `${field}.fields[${index}].source`) : undefined
     });
@@ -193,7 +193,9 @@ function normalizeSchemaRegistry(input) {
     responses,
     policies: deepFreeze({
       objectRoots: true,
-      requiredFieldsOnly: true,
+      requiredFieldsOnly: false,
+      optionalFields: 'omit-absent-own-properties',
+      presentUndefined: 'reject',
       unknownInputFields: 'drop',
       outputFields: 'declared-only',
       outputFieldOrder: 'declaration',
@@ -248,7 +250,7 @@ function collectNativeClasses(schema, node, symbols, classes, pathParts = []) {
     fields: Object.freeze(node.fields.map((field) => Object.freeze({
       name: field.name,
       type: assemblyScriptType(field.value, symbols, [...pathParts, field.name]),
-      required: true,
+      required: field.required,
       constraints: field.value.kind === 'string-enum'
         ? Object.freeze({ enum: field.value.values })
         : Object.freeze({})
@@ -256,18 +258,27 @@ function collectNativeClasses(schema, node, symbols, classes, pathParts = []) {
   }));
 }
 
+function schemaHasOptionalProperties(node) {
+  if (node.kind === 'nullable') return schemaHasOptionalProperties(node.value);
+  if (node.kind === 'array') return schemaHasOptionalProperties(node.element);
+  return node.kind === 'object' && node.fields.some(field => !field.required || schemaHasOptionalProperties(field.value));
+}
+
 function codecInputsForRegistry(registryInput) {
   const registry = normalizeSchemaRegistry(registryInput);
   const nativeSchemas = registry.schemas.map((schema) => {
     const schemaClasses = [];
     const symbols = new Map();
-    collectNativeClasses(schema, schema.root, symbols, schemaClasses);
+    const presence = schemaHasOptionalProperties(schema.root);
+    if (!presence) collectNativeClasses(schema, schema.root, symbols, schemaClasses);
+    const rootClass = presence ? 'JSON.Value' : symbols.get('');
     return Object.freeze({
       id: schema.id,
-      rootClass: symbols.get(''),
+      rootClass,
+      representation: presence ? 'schema-projected-json-value' : 'required-struct',
       classes: Object.freeze(schemaClasses),
-      parse: `JSON.parse<${symbols.get('')}>`,
-      stringify: `JSON.stringify<${symbols.get('')}>`
+      parse: `JSON.parse<${rootClass}>`,
+      stringify: `JSON.stringify<${rootClass}>`
     });
   });
   return deepFreeze({
@@ -333,7 +344,7 @@ function defaultSchemaRegistryContract() {
       stableStringIds: true,
       exactLiteralIdsAtBoundaries: true,
       oldSchemasJsonSupported: false,
-      optionalPropertiesSupported: false,
+      optionalPropertiesSupported: true,
       recursiveSchemasSupported: false,
       publicJsonAsImportsSupported: false,
       automaticFallback: false
@@ -354,6 +365,7 @@ module.exports = Object.freeze({
   normalizeSchemaNode,
   normalizeSchemaRegistry,
   codecInputsForRegistry,
+  schemaHasOptionalProperties,
   defaultSchemaBoundaryPolicy,
   defaultSchemaRegistryContract
 });

package/src/schema-json/semantic-trace.js

@@ -7,12 +7,14 @@ const JSON_SEMANTIC_TRACE_VERSION = 'pulse.json-semantic-trace.v1';
 const JSON_TRACE_EVENT_KINDS = Object.freeze([
   'json.decode.request',
   'json.decode.fetch',
+  'json.decode.text',
   'json.encode.response',
   'json.encode.fetch',
+  'json.encode.value',
   'json.decode.error',
   'json.encode.error'
 ]);
-const JSON_BOUNDARIES = Object.freeze(['request', 'fetch-response', 'application-response', 'fetch-request']);
+const JSON_BOUNDARIES = Object.freeze(['request', 'fetch-response', 'application-response', 'fetch-request', 'application-value', 'application-text']);
 const JSON_BODY_OWNERSHIP = Object.freeze([
   'request-snapshot',
   'fetched-response-snapshot',
@@ -22,10 +24,12 @@ const JSON_BODY_OWNERSHIP = Object.freeze([
 const JSON_EVENT_BOUNDARIES = Object.freeze({
   'json.decode.request': Object.freeze(['request']),
   'json.decode.fetch': Object.freeze(['fetch-response']),
+  'json.decode.text': Object.freeze(['application-text']),
   'json.encode.response': Object.freeze(['application-response']),
   'json.encode.fetch': Object.freeze(['fetch-request']),
-  'json.decode.error': Object.freeze(['request', 'fetch-response']),
-  'json.encode.error': Object.freeze(['application-response', 'fetch-request'])
+  'json.encode.value': Object.freeze(['application-value']),
+  'json.decode.error': Object.freeze(['request', 'fetch-response', 'application-text']),
+  'json.encode.error': Object.freeze(['application-response', 'fetch-request', 'application-value'])
 });
 
 function traceError(code, message, details = {}) {