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

package/src/host/wasm-host-abi.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const ABI_VERSION = 'pulsewasm.wasm-host-abi.v4';
+const ABI_PHASE = '12D';
+
+const METHOD_CODES = Object.freeze({
+  UNKNOWN: 0,
+  GET: 1,
+  POST: 2,
+  PUT: 3,
+  PATCH: 4,
+  DELETE: 5,
+  OPTIONS: 6,
+  HEAD: 7
+});
+
+const RESULT_KINDS = Object.freeze({
+  RESULT_NONE: 0,
+  RESULT_TEXT: 1,
+  RESULT_JSON: 2,
+  RESULT_BINARY: 3,
+  RESULT_EMPTY: 4,
+  RESULT_STREAM: 5
+});
+
+const NEXT_OUTCOMES = Object.freeze({
+  NEXT_NONE: 0,
+  NEXT_NORMAL: 1,
+  NEXT_ERROR: 2
+});
+
+function fn(name, params, returns = 'void', notes = []) {
+  return { name, params, returns, notes };
+}
+
+function buildWasmHostAbiExportGroups() {
+  const memory = [
+    fn('memory', [], 'memory', ['Exported linear memory.']),
+    fn('pulse_alloc', [{ name: 'byteLength', type: 'i32' }], 'i32', ['Allocates host-visible memory.']),
+    fn('pulse_free', [{ name: 'ptr', type: 'i32' }, { name: 'byteLength', type: 'i32' }], 'void', ['Releases memory previously allocated through pulse_alloc when supported.'])
+  ];
+
+  const lifecycle = [
+    fn('pulse_init', [], 'void', ['Initializes runtime globals.']),
+    fn('pulse_reset', [], 'void', ['Clears transient dispatch/result/error state.'])
+  ];
+
+  const dispatch = [
+    fn('pulse_execute_request', [{ name: 'methodCode', type: 'i32' }, { name: 'pathPtr', type: 'i32' }, { name: 'pathLen', type: 'i32' }], 'i32', ['Executes request routing with a UTF-8 full path.']),
+    fn('pulse_execute_connect', [{ name: 'methodCode', type: 'i32' }, { name: 'pathPtr', type: 'i32' }, { name: 'pathLen', type: 'i32' }], 'i32', ['Executes explicit connect lifecycle handlers for the matched scope.']),
+    fn('pulse_execute_disconnect', [{ name: 'methodCode', type: 'i32' }, { name: 'pathPtr', type: 'i32' }, { name: 'pathLen', type: 'i32' }], 'i32', ['Executes explicit disconnect lifecycle handlers for the matched scope.'])
+  ];
+
+  const result = [
+    fn('pulse_result_status', [], 'i32'),
+    fn('pulse_result_kind', [], 'i32'),
+    fn('pulse_result_body_ref', [], 'i32'),
+    fn('pulse_result_body_ptr', [], 'i32'),
+    fn('pulse_result_body_len', [], 'i32'),
+    fn('pulse_result_headers_ref', [], 'i32'),
+    fn('pulse_result_error_ref', [], 'i32'),
+    fn('pulse_result_stream_ref', [], 'i32'),
+    fn('pulse_result_response_ref', [], 'i32')
+  ];
+
+  const headers = [
+    fn('pulse_request_header_first', [{ name: 'ctxRef', type: 'i32' }, { name: 'namePtr', type: 'i32' }, { name: 'nameLen', type: 'i32' }], 'i32', ['Returns first matching request header StringRef, or 0.']),
+    fn('pulse_request_header_count', [{ name: 'ctxRef', type: 'i32' }, { name: 'namePtr', type: 'i32' }, { name: 'nameLen', type: 'i32' }], 'i32'),
+    fn('pulse_request_header_at', [{ name: 'ctxRef', type: 'i32' }, { name: 'namePtr', type: 'i32' }, { name: 'nameLen', type: 'i32' }, { name: 'index', type: 'i32' }], 'i32', ['Returns matching request header StringRef by repeated-header index, or 0.']),
+    fn('pulse_response_header_set', [{ name: 'ctxRef', type: 'i32' }, { name: 'namePtr', type: 'i32' }, { name: 'nameLen', type: 'i32' }, { name: 'valuePtr', type: 'i32' }, { name: 'valueLen', type: 'i32' }], 'void'),
+    fn('pulse_response_header_append', [{ name: 'ctxRef', type: 'i32' }, { name: 'namePtr', type: 'i32' }, { name: 'nameLen', type: 'i32' }, { name: 'valuePtr', type: 'i32' }, { name: 'valueLen', type: 'i32' }], 'void'),
+    fn('pulse_response_header_delete', [{ name: 'ctxRef', type: 'i32' }, { name: 'namePtr', type: 'i32' }, { name: 'nameLen', type: 'i32' }], 'void'),
+    fn('pulse_result_header_count', [], 'i32'),
+    fn('pulse_result_header_name_ptr', [{ name: 'index', type: 'i32' }], 'i32'),
+    fn('pulse_result_header_name_len', [{ name: 'index', type: 'i32' }], 'i32'),
+    fn('pulse_result_header_value_ptr', [{ name: 'index', type: 'i32' }], 'i32'),
+    fn('pulse_result_header_value_len', [{ name: 'index', type: 'i32' }], 'i32'),
+    fn('pulse_result_header_mode', [{ name: 'index', type: 'i32' }], 'i32', ['1 = set/override, 2 = append.']),
+    fn('pulse_result_header_delete_count', [], 'i32'),
+    fn('pulse_result_header_delete_name_ptr', [{ name: 'index', type: 'i32' }], 'i32'),
+    fn('pulse_result_header_delete_name_len', [{ name: 'index', type: 'i32' }], 'i32')
+  ];
+
+  const jsonBody = [
+    fn('pulse_request_body_text', [{ name: 'ctxRef', type: 'i32' }], 'i32', ['Returns request body text StringRef; body access is explicit and lazy.']),
+    fn('pulse_request_body_len', [{ name: 'ctxRef', type: 'i32' }], 'i32'),
+    fn('pulse_request_json_parse', [{ name: 'ctxRef', type: 'i32' }], 'i32', ['Returns JsonParseResultRef; parsing errors are explicit, not thrown.']),
+    fn('pulse_json_result_ok', [{ name: 'resultRef', type: 'i32' }], 'i32'),
+    fn('pulse_json_result_value', [{ name: 'resultRef', type: 'i32' }], 'i32'),
+    fn('pulse_json_result_error', [{ name: 'resultRef', type: 'i32' }], 'i32'),
+    fn('pulse_json_kind', [{ name: 'valueRef', type: 'i32' }], 'i32'),
+    fn('pulse_json_object_has', [{ name: 'valueRef', type: 'i32' }, { name: 'keyPtr', type: 'i32' }, { name: 'keyLen', type: 'i32' }], 'i32'),
+    fn('pulse_json_object_get', [{ name: 'valueRef', type: 'i32' }, { name: 'keyPtr', type: 'i32' }, { name: 'keyLen', type: 'i32' }], 'i32'),
+    fn('pulse_json_array_len', [{ name: 'valueRef', type: 'i32' }], 'i32'),
+    fn('pulse_json_array_get', [{ name: 'valueRef', type: 'i32' }, { name: 'index', type: 'i32' }], 'i32'),
+    fn('pulse_json_as_string', [{ name: 'valueRef', type: 'i32' }], 'i32'),
+    fn('pulse_json_as_f64', [{ name: 'valueRef', type: 'i32' }], 'f64'),
+    fn('pulse_json_as_bool', [{ name: 'valueRef', type: 'i32' }], 'i32'),
+    fn('pulse_result_json_text', [{ name: 'ctxRef', type: 'i32' }, { name: 'statusCode', type: 'i32' }, { name: 'jsonPtr', type: 'i32' }, { name: 'jsonLen', type: 'i32' }], 'void', ['Sets RESULT_JSON and Content-Type: application/json.'])
+  ];
+
+  const stringRefs = [
+    fn('pulse_string_ptr', [{ name: 'stringRef', type: 'i32' }], 'i32'),
+    fn('pulse_string_len', [{ name: 'stringRef', type: 'i32' }], 'i32'),
+    fn('pulse_string_is_null', [{ name: 'stringRef', type: 'i32' }], 'i32')
+  ];
+
+  const ctxOps = [
+    fn('pulse_ctx_param', [{ name: 'ctxRef', type: 'i32' }, { name: 'namePtr', type: 'i32' }, { name: 'nameLen', type: 'i32' }], 'i32', ['Returns a StringRef, or 0 when missing.']),
+    fn('pulse_ctx_state_get', [{ name: 'ctxRef', type: 'i32' }, { name: 'keyPtr', type: 'i32' }, { name: 'keyLen', type: 'i32' }], 'i32', ['Returns a StringRef, or 0 when missing.']),
+    fn('pulse_ctx_state_set', [{ name: 'ctxRef', type: 'i32' }, { name: 'keyPtr', type: 'i32' }, { name: 'keyLen', type: 'i32' }, { name: 'valuePtr', type: 'i32' }, { name: 'valueLen', type: 'i32' }], 'void'),
+    fn('pulse_result_text', [{ name: 'ctxRef', type: 'i32' }, { name: 'statusCode', type: 'i32' }, { name: 'bodyPtr', type: 'i32' }, { name: 'bodyLen', type: 'i32' }], 'void'),
+    fn('pulse_result_empty', [{ name: 'ctxRef', type: 'i32' }, { name: 'statusCode', type: 'i32' }], 'void'),
+    fn('pulse_result_stream', [{ name: 'ctxRef', type: 'i32' }, { name: 'statusCode', type: 'i32' }, { name: 'streamRef', type: 'i32' }], 'void', ['Sets RESULT_STREAM from an opaque host-owned stream ref.']),
+    fn('pulse_result_from_response', [{ name: 'ctxRef', type: 'i32' }, { name: 'responseRef', type: 'i32' }], 'void', ['Sets RESULT_STREAM from an opaque host-owned response ref; host preserves/merges status, headers, and stream.']),
+    fn('pulse_next', [{ name: 'ctxRef', type: 'i32' }], 'void'),
+    fn('pulse_next_error', [{ name: 'ctxRef', type: 'i32' }, { name: 'errorRef', type: 'i32' }], 'void')
+  ];
+
+  const errors = [
+    fn('pulse_error', [{ name: 'codePtr', type: 'i32' }, { name: 'codeLen', type: 'i32' }, { name: 'messagePtr', type: 'i32' }, { name: 'messageLen', type: 'i32' }, { name: 'statusCode', type: 'i32' }], 'i32'),
+    fn('pulse_error_with_cause', [{ name: 'codePtr', type: 'i32' }, { name: 'codeLen', type: 'i32' }, { name: 'messagePtr', type: 'i32' }, { name: 'messageLen', type: 'i32' }, { name: 'statusCode', type: 'i32' }, { name: 'causeRef', type: 'i32' }], 'i32'),
+    fn('pulse_error_code_ref', [{ name: 'errorRef', type: 'i32' }], 'i32'),
+    fn('pulse_error_message_ref', [{ name: 'errorRef', type: 'i32' }], 'i32'),
+    fn('pulse_error_status_code', [{ name: 'errorRef', type: 'i32' }], 'i32'),
+    fn('pulse_error_cause_ref', [{ name: 'errorRef', type: 'i32' }], 'i32')
+  ];
+
+  const channel = [
+    fn('pulse_channel_count', [{ name: 'channelsRef', type: 'i32' }], 'i32'),
+    fn('pulse_channel_ref_at', [{ name: 'channelsRef', type: 'i32' }, { name: 'index', type: 'i32' }], 'i32')
+  ];
+
+  return { memory, lifecycle, dispatch, result, headers, jsonBody, stringRefs, ctxOps, errors, channel };
+}
+
+function flattenWasmHostAbiExports(groups) {
+  return Object.entries(groups).flatMap(([group, functions]) => functions.map((item) => ({ group, ...item })));
+}
+
+function listWasmHostAbiExports() {
+  return flattenWasmHostAbiExports(buildWasmHostAbiExportGroups());
+}
+
+module.exports = {
+  ABI_VERSION,
+  ABI_PHASE,
+  METHOD_CODES,
+  RESULT_KINDS,
+  NEXT_OUTCOMES,
+  buildWasmHostAbiExportGroups,
+  flattenWasmHostAbiExports,
+  listWasmHostAbiExports
+};

package/src/index.js

@@ -0,0 +1,75 @@
+'use strict';
+
+module.exports = {
+  handlerSchemaDecodeResult: require('./handler/schema-decode-result.js'),
+  handlerSchemaResponseCodec: require('./handler/schema-response-codec.js'),
+  diagnostics: require('./diagnostics.js'),
+  diagnosticCodes: require('./diagnostics/codes.js'),
+  diagnosticReporter: require('./diagnostics/reporter.js'),
+  stableId: require('./stable-id.js'),
+  logging: require('./logging.js'),
+  configSchema: require('./definitions/config-schema.js'),
+  handlerRoles: require('./definitions/handler-roles.js'),
+  routerApi: require('./definitions/router-api.js'),
+  path: require('./path.js'),
+  pathGrammar: require('./definitions/path-grammar.js'),
+  routePlan: require('./route-plan.js'),
+  dispatchTable: require('./dispatch-table.js'),
+  executionPlan: require('./execution-plan.js'),
+  pathTable: require('./path-table.js'),
+  handlerTable: require('./handler-table.js'),
+  handlerEffects: require('./handler/effects.js'),
+  handlerContext: require('./handler/context.js'),
+  handlerIoLifecycle: require('./handler/io-lifecycle.js'),
+  requestJsonBody: require('./handler/request-json-body.js'),
+  schemaDecodeResult: require('./handler/schema-decode-result.js'),
+  schemaResponseCodec: require('./handler/schema-response-codec.js'),
+  backendJsonRequestBody: require('./handler/backend-json-request-body.js'),
+  referenceNodeLifecycleGolden: require('./handler/reference-node-lifecycle-golden.js'),
+  betaLifecycleGolden: require('./handler/beta-lifecycle-golden.js'),
+  lifecycleAuthoringAlignment: require('./handler/lifecycle-authoring-alignment.js'),
+  lifecycleReadinessAggregate: require('./handler/lifecycle-readiness-aggregate.js'),
+  doctorReadinessAggregator: require('./handler/doctor-readiness-aggregator.js'),
+  runtimeApi: require('./handler/runtime-api.js'),
+  canonicalRuntime: require('./handler/canonical-runtime.js'),
+  canonicalNativePlan: require('./handler/canonical-native-plan.js'),
+  canonicalNativeRuntime: require('./handler/canonical-native-runtime.js'),
+  canonicalProvider: require('./provider/canonical-provider.js'),
+  assetsContracts: require('./assets/contracts.js'),
+  gripContracts: require('./grip/contracts.js'),
+  jwtContracts: require('./jwt/contracts.js'),
+  entitiesContracts: require('./entities/contracts.js'),
+  entitiesRuntime: require('./entities/runtime.js'),
+  entitiesJsonRpc: require('./entities/json-rpc.js'),
+  entitiesCatalog: require('./entities/catalog.js'),
+  hostCapabilities: require('./host/capabilities.js'),
+  hostWasmAbi: require('./host/wasm-host-abi.js'),
+  requestResultHeaders: require('./host/request-result-headers.js'),
+  channelBroadcaster: require('./host/channel-broadcaster.js'),
+  jsonBody: require('./host/json-body.js'),
+  streamingPassthrough: require('./host/streaming-passthrough.js'),
+  backendCapabilities: require('./host/backend-capabilities.js'),
+  libraryContracts: require('./library/contracts.js'),
+  libraryManifest: require('./library/manifest.js'),
+  secondPackageOwnedLowering: require('./library/second-package-owned-lowering.js'),
+  librarySidecars: require('./library/sidecars.js'),
+  libraryApiSurface: require('./library/api-surface.js'),
+  schemaJsonContracts: require('./schema-json/contracts.js'),
+  schemaJsonV1: require('./schema-json/v1.js'),
+  schemaJsonV2: require('./schema-json/v2.js'),
+  schemaJsonCompile: require('./schema-json/compile.js'),
+  schemaJsonGenericParser: require('./schema-json/generic-parser.js'),
+  configSymbolicRefs: require('./config/symbolic-refs.js'),
+  configProviderResolution: require('./config/provider-resolution.js'),
+  runtimeProviderKv: require('./config/runtime-provider-kv.js'),
+  compilerSpine: require('./spine.js'),
+  handlerSurface: require('./handler/surface-contract.js'),
+  ctxContract: require('./handler/ctx-contract.js'),
+  handlerTypes: require('./handler/types-contract.js'),
+  projectConfigPlan: require('./project/config-plan.js'),
+  projectConfigRuntime: require('./project/config-runtime.js'),
+  reachableGraph: require('./project/reachable-graph.js'),
+  packageOwnership: require('./project/package-ownership.js'),
+  packageContract: require('./package/package-contract.js'),
+  targetSupportEvidence: require('./project/target-support-evidence.js')
+};

package/src/jwt/contracts.js

@@ -0,0 +1,427 @@
+'use strict';
+
+const {
+  CRYPTO_SEMANTIC_OWNER
+} = require('../crypto/contracts.js');
+const {
+  PACKAGE_CRYPTO_REQUIREMENT_VERSION
+} = require('../package/package-contract.js');
+
+const JWT_CONTRACT_VERSION = 'pulse.jwt-contract.v1';
+const JWT_CANONICAL_EFFECT_VERSION = 'pulse.canonical-package-effect.v1';
+const JWT_LOWERING_PLAN_VERSION = 'pulse.jwt-lowering-plan.v1';
+const JWT_LOWERING_PLAN_ARTIFACT = 'jwt-lowering-plan.json';
+const JWT_SIDECAR_ABI_VERSION = 'pulse.jwt-sidecar-abi.v1';
+const JWT_CRYPTO_COMPOSITION_VERSION = 'pulse.jwt-crypto-composition.v1';
+const JWT_CONTRACT_ID = 'pulse.jwt';
+const JWT_PACKAGE_NAME = '@pulse-compute/jwt';
+
+const JWT_ALGORITHMS = Object.freeze(['HS256', 'RS256', 'ES256', 'EdDSA']);
+const JWT_IMPLEMENTED_ALGORITHMS = Object.freeze(['HS256', 'ES256']);
+const JWT_KEY_TYPES = Object.freeze(['secret', 'jwk', 'jwks']);
+const JWT_IMPLEMENTED_KEY_TYPES = Object.freeze(['secret', 'jwk', 'jwks']);
+const JWT_NATIVE_REALIZATION_KINDS = Object.freeze(['crypto-composed']);
+const JWT_ALGORITHM_CAPABILITIES = Object.freeze({
+  HS256: 'jwt.verify.hs256',
+  RS256: 'jwt.verify.rs256',
+  ES256: 'jwt.verify.es256',
+  EdDSA: 'jwt.verify.eddsa'
+});
+const JWT_PACKAGE_INTRINSICS = Object.freeze({
+  bearer: Object.freeze({
+    name: 'jwt.bearer-request-header',
+    nativeIntrinsic: 'request.header',
+    compilerName: '__pulse_jwt_bearer_request_header',
+    valueKind: 'string-or-undefined',
+    argumentIndexes: Object.freeze([]),
+    staticArguments: Object.freeze(['authorization'])
+  })
+});
+const JWT_DIAGNOSTIC_CODES = Object.freeze({
+  ARGUMENT_SHAPE_UNSUPPORTED: 'PULSE_JWT_ARGUMENT_SHAPE_UNSUPPORTED',
+  CONTEXT_UNSUPPORTED: 'PULSE_JWT_CONTEXT_UNSUPPORTED',
+  TOKEN_SOURCE_UNSUPPORTED: 'PULSE_JWT_TOKEN_SOURCE_UNSUPPORTED',
+  BEARER_REQUEST_UNSUPPORTED: 'PULSE_JWT_BEARER_REQUEST_UNSUPPORTED',
+  BEARER_PLACEMENT_UNSUPPORTED: 'PULSE_JWT_BEARER_PLACEMENT_UNSUPPORTED',
+  PLACEMENT_UNSUPPORTED: 'PULSE_JWT_PLACEMENT_UNSUPPORTED',
+  RESULT_ACCESS_UNSUPPORTED: 'PULSE_JWT_RESULT_ACCESS_UNSUPPORTED',
+  OPTIONS_LITERAL_REQUIRED: 'PULSE_JWT_OPTIONS_LITERAL_REQUIRED',
+  OPTIONS_PROPERTY_UNSUPPORTED: 'PULSE_JWT_OPTIONS_PROPERTY_UNSUPPORTED',
+  ALGORITHMS_LITERAL_REQUIRED: 'PULSE_JWT_ALGORITHMS_LITERAL_REQUIRED',
+  ALGORITHMS_EMPTY: 'PULSE_JWT_ALGORITHMS_EMPTY',
+  ALGORITHM_UNSUPPORTED: 'PULSE_JWT_ALGORITHM_UNSUPPORTED',
+  KEY_LITERAL_REQUIRED: 'PULSE_JWT_KEY_LITERAL_REQUIRED',
+  KEY_TYPE_UNSUPPORTED: 'PULSE_JWT_KEY_TYPE_UNSUPPORTED',
+  KEY_ALGORITHM_MISMATCH: 'PULSE_JWT_KEY_ALGORITHM_MISMATCH',
+  JWK_INVALID: 'PULSE_JWT_JWK_INVALID',
+  PRIVATE_JWK_UNSUPPORTED: 'PULSE_JWT_PRIVATE_JWK_UNSUPPORTED',
+  JWKS_LIMIT_EXCEEDED: 'PULSE_JWT_JWKS_LIMIT_EXCEEDED',
+  JWKS_AMBIGUOUS: 'PULSE_JWT_JWKS_AMBIGUOUS',
+  POLICY_LITERAL_REQUIRED: 'PULSE_JWT_POLICY_LITERAL_REQUIRED',
+  POLICY_LIMIT_EXCEEDED: 'PULSE_JWT_POLICY_LIMIT_EXCEEDED',
+  SCHEMA_LITERAL_REQUIRED: 'PULSE_JWT_SCHEMA_LITERAL_REQUIRED',
+  SCHEMA_UNKNOWN: 'PULSE_JWT_SCHEMA_UNKNOWN',
+  SCHEMA_UNREALIZED: 'PULSE_JWT_SCHEMA_UNREALIZED',
+  TARGET_ALGORITHM_UNSUPPORTED: 'PULSE_JWT_TARGET_ALGORITHM_UNSUPPORTED',
+  TARGET_KEY_UNSUPPORTED: 'PULSE_JWT_TARGET_KEY_UNSUPPORTED',
+  TARGET_CLOCK_UNAVAILABLE: 'PULSE_JWT_TARGET_CLOCK_UNAVAILABLE',
+  REALIZATION_UNSUPPORTED: 'PULSE_JWT_REALIZATION_UNSUPPORTED',
+  REALIZATION_AMBIGUOUS: 'PULSE_JWT_REALIZATION_AMBIGUOUS',
+  FACADE_USE_UNSUPPORTED: 'PULSE_JWT_FACADE_USE_UNSUPPORTED'
+});
+const JWT_RESOURCE_LIMITS = Object.freeze({
+  tokenBytes: 16 * 1024,
+  protectedHeaderBytes: 4 * 1024,
+  claimsBytes: 16 * 1024,
+  jwksEntries: 16,
+  requiredClaimNames: 32,
+  algorithms: 4,
+  clockToleranceSeconds: 300,
+  jsonDepth: 32
+});
+
+const JWT_ES256_KEY_NORMALIZATION_CONTRACT = Object.freeze({
+  version: 'pulse.jwt.es256-key-normalization.v1',
+  status: 'executable-g3',
+  algorithm: 'ES256',
+  inlineJwk: Object.freeze({
+    requiredMembers: Object.freeze(['kty', 'crv', 'x', 'y']),
+    optionalMembers: Object.freeze(['alg', 'use', 'key_ops', 'kid']),
+    exactValues: Object.freeze({
+      kty: 'EC',
+      crv: 'P-256',
+      alg: 'absent-or-ES256',
+      use: 'absent-or-sig',
+      key_ops: 'absent-or-exactly-verify'
+    }),
+    coordinateEncoding: 'canonical-unpadded-base64url',
+    coordinateBytes: 32,
+    privateMembersRejected: true,
+    unknownMembersRejected: true,
+    certificateMembersRejected: true
+  }),
+  jwks: Object.freeze({
+    kind: 'bounded-static-inline',
+    entriesMaximum: JWT_RESOURCE_LIMITS.jwksEntries,
+    remoteDiscovery: false,
+    fetch: false,
+    cache: false,
+    refresh: false,
+    duplicateKid: 'reject-entire-set',
+    selection: 'kid-exact-or-single-eligible-key',
+    selectedKeyFailure: 'terminal-no-retry'
+  }),
+  cryptoAdapter: Object.freeze({
+    publicKeyType: 'p256-public-key-bytes',
+    publicKeyEncoding: 'x-y-big-endian',
+    publicKeyBytes: 64,
+    signatureEncoding: 'jose-r-s-big-endian',
+    signatureBytes: 64,
+    derAccepted: false,
+    highS: 'accepted-if-otherwise-valid'
+  }),
+  exactSigningInput: true,
+  claimsBeforeAuthenticity: false,
+  automaticFallback: false
+});
+
+const JWT_VERIFY_OPERATION = Object.freeze({
+  version: JWT_CANONICAL_EFFECT_VERSION,
+  contractId: JWT_CONTRACT_ID,
+  package: JWT_PACKAGE_NAME,
+  import: JWT_PACKAGE_NAME,
+  kind: 'jwt.verify',
+  providerKind: 'jwt',
+  operation: 'verify',
+  capability: 'jwt.verify',
+  result: 'jwt-verification',
+  placement: 'variable',
+  clock: 'provider-wall-clock'
+});
+
+const JWT_EXECUTION_REQUIREMENTS = Object.freeze({
+  containment: 'request-owned-effect',
+  cancellation: 'request-lifecycle-signal',
+  secretResolution: 'provider-owned-named-secret-authority',
+  clock: 'one-trusted-provider-wall-clock-capture',
+  schemaValidation: 'project-codecs-decode-in-memory',
+  resultProjection: 'detached-immutable-jwt-verification',
+  redaction: Object.freeze([
+    'token',
+    'signature',
+    'key-material',
+    'complete-claims',
+    'secret-value'
+  ])
+});
+
+const JWT_NATIVE_LOWERING_CONTRACT = Object.freeze({
+  planVersion: JWT_LOWERING_PLAN_VERSION,
+  sidecarAbiVersion: JWT_SIDECAR_ABI_VERSION,
+  cryptoCompositionVersion: JWT_CRYPTO_COMPOSITION_VERSION,
+  operation: 'jwt.verify',
+  tokenSource: 'bearer-request-header',
+  result: 'jwt-verification',
+  targetCapabilities: Object.freeze([
+    'jwt.verify',
+    'jwt.verify.hs256',
+    'secret.get',
+    'time.wall-clock'
+  ]),
+  realizationKinds: JWT_NATIVE_REALIZATION_KINDS,
+  realizationBinding: 'crypto-owned-before-artifact-generation',
+  implementationStatus: 'crypto-composed-hs256-es256',
+  implementedCapabilities: Object.freeze([
+    'jwt.verify',
+    'jwt.verify.hs256',
+    'jwt.verify.es256',
+    'secret.get',
+    'time.wall-clock'
+  ]),
+  implementedAlgorithms: JWT_IMPLEMENTED_ALGORITHMS,
+  implementedKeyTypes: JWT_IMPLEMENTED_KEY_TYPES,
+  realization: 'guest-source:pulse-hmac-as',
+  implementation: 'pulse-hmac-as.v1',
+  realizations: Object.freeze({
+    HS256: Object.freeze({
+      realization: 'guest-source:pulse-hmac-as',
+      implementation: 'pulse-hmac-as.v1',
+      guestUnitRequired: false
+    }),
+    ES256: Object.freeze({
+      realization: 'guest-linked:pulse-es256-rustcrypto-p256',
+      implementation: 'rustcrypto.p256-0.13.2.ecdsa-0.16.9.sha2-0.10.9.v1',
+      guestUnitRequired: true
+    })
+  }),
+  cryptoSemanticOwner: CRYPTO_SEMANTIC_OWNER,
+  portableVerifierImplemented: false,
+  hostVerifyImplemented: false,
+  guestUnitRequiredForHs256: false,
+  guestUnitRequiredForEs256: true,
+  automaticFallback: false
+});
+
+const JWT_TARGET_REALIZATIONS = Object.freeze({
+  node: Object.freeze({
+    javascript: Object.freeze({
+      status: 'eligible',
+      algorithm: 'HS256',
+      realization: 'runtime-builtin',
+      implementation: 'webcrypto.subtle.hmac-sha-256.v1',
+      algorithms: JWT_IMPLEMENTED_ALGORITHMS,
+      keyTypes: JWT_IMPLEMENTED_KEY_TYPES,
+      clock: 'node-provider-wall-clock',
+      automaticFallback: false
+    }),
+    native: Object.freeze({
+      status: 'eligible',
+      algorithm: 'HS256',
+      realization: 'guest-source:pulse-hmac-as',
+      implementation: 'pulse-hmac-as.v1',
+      algorithms: JWT_IMPLEMENTED_ALGORITHMS,
+      keyTypes: JWT_IMPLEMENTED_KEY_TYPES,
+      clock: 'node-provider-wall-clock',
+      guestUnitRequired: false,
+      automaticFallback: false
+    })
+  }),
+  fastly: Object.freeze({
+    javascript: Object.freeze({
+      status: 'eligible',
+      algorithm: 'HS256',
+      realization: 'runtime-builtin',
+      implementation: 'webcrypto.subtle.hmac-sha-256.v1',
+      algorithms: JWT_IMPLEMENTED_ALGORITHMS,
+      keyTypes: JWT_IMPLEMENTED_KEY_TYPES,
+      clock: 'fastly-provider-wall-clock',
+      automaticFallback: false
+    }),
+    native: Object.freeze({
+      status: 'eligible',
+      algorithms: JWT_IMPLEMENTED_ALGORITHMS,
+      keyTypes: JWT_IMPLEMENTED_KEY_TYPES,
+      realizations: JWT_NATIVE_LOWERING_CONTRACT.realizations,
+      guestUnitRequiredForEs256: true,
+      automaticFallback: false
+    })
+  })
+});
+
+class PulseJwtContractError extends Error {
+  constructor(message, detail) {
+    super(message);
+    this.name = 'PulseJwtContractError';
+    this.code = 'PULSE_JWT_OPERATION_FAILED';
+    this.detail = Object.freeze({ category: 'canonical-operation', ...detail });
+  }
+}
+
+function ordinaryObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function dataProperty(value, name) {
+  const descriptor = Object.getOwnPropertyDescriptor(value, name);
+  return descriptor && descriptor.enumerable
+    && Object.prototype.hasOwnProperty.call(descriptor, 'value')
+    ? descriptor.value
+    : undefined;
+}
+
+function assertOperationIdentity(effect) {
+  if (!ordinaryObject(effect)
+    || effect.contractId !== JWT_VERIFY_OPERATION.contractId
+    || effect.package !== JWT_VERIFY_OPERATION.package
+    || effect.kind !== JWT_VERIFY_OPERATION.kind
+    || effect.providerKind !== JWT_VERIFY_OPERATION.providerKind
+    || effect.operation !== JWT_VERIFY_OPERATION.operation
+    || effect.capability !== JWT_VERIFY_OPERATION.capability
+    || effect.result !== JWT_VERIFY_OPERATION.result) {
+    throw new PulseJwtContractError(
+      'Pulse JWT provider received an invalid canonical verification operation.',
+      { field: 'identity' }
+    );
+  }
+}
+
+function normalizeJwtVerifyEffect(effect) {
+  assertOperationIdentity(effect);
+  const payload = dataProperty(effect, 'payload');
+  if (!ordinaryObject(payload)) {
+    throw new PulseJwtContractError(
+      'Pulse JWT verification requires an ordinary operation payload.',
+      { field: 'payload' }
+    );
+  }
+  const payloadKeys = Reflect.ownKeys(payload);
+  if (payloadKeys.length !== 2 || !payloadKeys.includes('token') || !payloadKeys.includes('options')) {
+    throw new PulseJwtContractError(
+      'Pulse JWT verification received an invalid operation payload.',
+      { field: 'payload' }
+    );
+  }
+  const token = dataProperty(payload, 'token');
+  const options = dataProperty(payload, 'options');
+  if (typeof token !== 'string' || !ordinaryObject(options)) {
+    throw new PulseJwtContractError(
+      'Pulse JWT verification received an invalid token or options payload.',
+      { field: typeof token !== 'string' ? 'token' : 'options' }
+    );
+  }
+  return Object.freeze({ token, options });
+}
+
+function jwtVerifyProviderRequirements(options = {}) {
+  const requirements = ['jwt.verify', 'time.wall-clock'];
+  const algorithms = Array.isArray(options.algorithms) ? options.algorithms : [];
+  for (const algorithm of algorithms) {
+    const suffix = String(algorithm).toLowerCase();
+    if (JWT_ALGORITHMS.includes(String(algorithm)) && !requirements.includes(`jwt.verify.${suffix}`)) {
+      requirements.push(`jwt.verify.${suffix}`);
+    }
+  }
+  const key = ordinaryObject(options.key) ? options.key : {};
+  if (key.type === 'secret') requirements.push('secret.get');
+  if (typeof options.claimsSchema === 'string') requirements.push('schema.decode');
+  return Object.freeze(requirements);
+}
+
+function jwtAlgorithmCapability(algorithm) {
+  return JWT_ALGORITHM_CAPABILITIES[String(algorithm)];
+}
+
+function jwtVerifyNativeRequirements(options = {}) {
+  const requirements = ['jwt.verify', 'time.wall-clock'];
+  const algorithms = Array.isArray(options.algorithms) ? options.algorithms : [];
+  for (const algorithm of algorithms) {
+    const capability = jwtAlgorithmCapability(algorithm);
+    if (capability && !requirements.includes(capability)) requirements.push(capability);
+  }
+  const key = ordinaryObject(options.key) ? options.key : {};
+  if (key.type === 'secret') requirements.push('secret.get');
+  if (typeof options.claimsSchema === 'string') requirements.push('schema.decode');
+  return Object.freeze(requirements);
+}
+
+function jwtCryptoRequirements(algorithms = []) {
+  if (!Array.isArray(algorithms)) {
+    throw new PulseJwtContractError(
+      'JWT crypto demand requires a static algorithm array.',
+      { field: 'algorithms' }
+    );
+  }
+  const normalized = [...new Set(algorithms.map(String))].sort();
+  if (normalized.some((algorithm) => !JWT_ALGORITHMS.includes(algorithm))) {
+    throw new PulseJwtContractError(
+      'JWT crypto demand contains an unsupported JWT algorithm.',
+      { field: 'algorithms' }
+    );
+  }
+  if (normalized.length === 0) return Object.freeze([]);
+  return Object.freeze([
+    Object.freeze({
+      version: PACKAGE_CRYPTO_REQUIREMENT_VERSION,
+      requestedBy: JWT_PACKAGE_NAME,
+      semanticOwner: CRYPTO_SEMANTIC_OWNER,
+      reachable: true,
+      algorithms: Object.freeze(normalized)
+    })
+  ]);
+}
+
+function jwtVerifyRedactedProjection(options = {}) {
+  const key = ordinaryObject(options.key) ? options.key : {};
+  const keyCount = key.type === 'jwks' && Array.isArray(key.keys)
+    ? key.keys.length
+    : (key.type === 'jwk' || key.type === 'secret' ? 1 : 0);
+  return Object.freeze({
+    version: JWT_CONTRACT_VERSION,
+    contractId: JWT_CONTRACT_ID,
+    operation: 'verify',
+    algorithms: Object.freeze(Array.isArray(options.algorithms)
+      ? options.algorithms.filter((entry) => JWT_ALGORITHMS.includes(String(entry))).map(String)
+      : []),
+    keyType: JWT_KEY_TYPES.includes(String(key.type)) ? String(key.type) : 'unknown',
+    keyCount,
+    hasIssuer: options.issuer !== undefined,
+    hasAudience: options.audience !== undefined,
+    hasSubject: options.subject !== undefined,
+    hasClaimsSchema: typeof options.claimsSchema === 'string',
+    providerRequirements: jwtVerifyProviderRequirements(options)
+  });
+}
+
+module.exports = Object.freeze({
+  JWT_CONTRACT_VERSION,
+  JWT_CANONICAL_EFFECT_VERSION,
+  JWT_LOWERING_PLAN_VERSION,
+  JWT_LOWERING_PLAN_ARTIFACT,
+  JWT_SIDECAR_ABI_VERSION,
+  JWT_CRYPTO_COMPOSITION_VERSION,
+  JWT_CONTRACT_ID,
+  JWT_PACKAGE_NAME,
+  JWT_ALGORITHMS,
+  JWT_IMPLEMENTED_ALGORITHMS,
+  JWT_KEY_TYPES,
+  JWT_IMPLEMENTED_KEY_TYPES,
+  JWT_NATIVE_REALIZATION_KINDS,
+  JWT_ALGORITHM_CAPABILITIES,
+  JWT_PACKAGE_INTRINSICS,
+  JWT_DIAGNOSTIC_CODES,
+  JWT_RESOURCE_LIMITS,
+  JWT_ES256_KEY_NORMALIZATION_CONTRACT,
+  JWT_VERIFY_OPERATION,
+  JWT_EXECUTION_REQUIREMENTS,
+  JWT_NATIVE_LOWERING_CONTRACT,
+  JWT_TARGET_REALIZATIONS,
+  PulseJwtContractError,
+  normalizeJwtVerifyEffect,
+  jwtVerifyProviderRequirements,
+  jwtAlgorithmCapability,
+  jwtVerifyNativeRequirements,
+  jwtCryptoRequirements,
+  jwtVerifyRedactedProjection
+});