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

package/src/entities/contracts.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const { sha256Hex, stableStringify } = require('../stable-id.js');
+const { PACKAGE_INTRINSIC_VERSION } = require('../package/package-contract.js');
+const runtime = require('./runtime.js');
+
+const ENTITIES_PACKAGE_VERSION = 'pulse.entities-package.v1';
+const ENTITIES_CONTRACT_VERSION = 'pulse.entities-contract.v1';
+const ENTITIES_PLAN_VERSION = 'pulse.entities-lowering-plan.v1';
+const ENTITIES_CATALOG_VERSION = 'pulse.entities-catalog.v1';
+const ENTITIES_DIAGNOSTIC_VERSION = 'pulse.entities-diagnostics.v1';
+const ENTITIES_HANDLER_REFERENCE_VERSION = 'pulse.entities-handler-reference.v1';
+const ENTITIES_REGISTRY_VERSION = 'pulse.entities-registry.v1';
+const ENTITIES_CONTRACT_ID = 'pulse.entities';
+const ENTITIES_PACKAGE_NAME = '@pulse-compute/entities';
+const ENTITIES_LOWERER_ID = 'pulse.entities.compiler-builder.v1';
+const ENTITIES_LOWERER_EXPORT = 'createEntitiesPackageCompilerBuilder';
+const ENTITIES_LOWERER_MANIFEST = './pulsewasm.manifest.cjs';
+const ENTITIES_LOWERABLE_SUBPATH = '@pulse-compute/entities';
+const ENTITIES_PACKAGE_INTRINSIC_VERSION = PACKAGE_INTRINSIC_VERSION;
+const ENTITIES_PUBLIC_SYMBOLS = Object.freeze(['EntityRouter', 'jsonRpc']);
+const ENTITIES_PACKAGE_INTRINSICS = Object.freeze({
+  handle: Object.freeze({
+    name: 'pulse.entities.handle.v1',
+    compilerName: '__pulse_entities_handle',
+    valueKind: 'response',
+    argumentIndexes: Object.freeze([0])
+  })
+});
+const ROUTER_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+function normalizeHandlerReference(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.HANDLER_UNRESOLVED, 'Entity handler reference must be an object.');
+  }
+  const unknown = Object.keys(input).filter((key) => !['version', 'file', 'exportName', 'localName'].includes(key)).sort();
+  if (unknown.length > 0) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.HANDLER_UNRESOLVED, `Entity handler reference contains unsupported fields: ${unknown.join(', ')}.`);
+  const version = input.version === undefined ? ENTITIES_HANDLER_REFERENCE_VERSION : String(input.version);
+  const file = typeof input.file === 'string' ? input.file.replace(/\\/g, '/') : '';
+  const exportName = typeof input.exportName === 'string' ? input.exportName : '';
+  const localName = input.localName === undefined ? exportName : String(input.localName);
+  if (version !== ENTITIES_HANDLER_REFERENCE_VERSION || !file || file.startsWith('/') || file.split('/').includes('..') || !exportName || !localName) {
+    throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.HANDLER_UNRESOLVED, 'Entity handler reference must use a portable file and named export.', { version, file, exportName, localName });
+  }
+  return Object.freeze({ version, file, exportName, localName });
+}
+
+function normalizeEntityRegistry(entriesInput, limitsInput = runtime.ENTITIES_DEFAULT_LIMITS) {
+  const limits = limitsInput === runtime.ENTITIES_DEFAULT_LIMITS ? limitsInput : runtime.normalizeEntityLimits(limitsInput);
+  if (!Array.isArray(entriesInput)) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Entity registry entries must be an array.');
+  if (entriesInput.length > limits.maxEntities) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.LIMIT_EXCEEDED, 'Entity registry exceeds its entity limit.', { count: entriesInput.length, maxEntities: limits.maxEntities });
+  const seen = new Set();
+  const entries = entriesInput.map((entry) => {
+    const normalized = runtime.normalizeEntityRegistration(entry, limits);
+    if (seen.has(normalized.discriminator)) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DISCRIMINATOR_DUPLICATE, `Entity discriminator ${JSON.stringify(normalized.discriminator)} is already registered.`, { discriminator: normalized.discriminator });
+    seen.add(normalized.discriminator);
+    return normalized;
+  }).sort((left, right) => runtime.compareText(left.discriminator, right.discriminator));
+  const metadataBytes = entries.reduce((sum, entry) => sum + (entry.declaration.metadata ? runtime.utf8ByteLength(stableStringify(entry.declaration.metadata)) : 0), 0);
+  if (metadataBytes > limits.maxMetadataBytesPerRouter) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.LIMIT_EXCEEDED, 'Entity router metadata exceeds its aggregate byte limit.', { metadataBytes, maxBytes: limits.maxMetadataBytesPerRouter });
+  const semantic = entries.map((entry) => ({ discriminator: entry.discriminator, input: entry.declaration.input, output: entry.declaration.output, metadata: entry.declaration.metadata, handler: entry.handler.name }));
+  return Object.freeze({ version: ENTITIES_REGISTRY_VERSION, entries: Object.freeze(entries), registryHash: sha256Hex(stableStringify(semantic)), limits });
+}
+
+function normalizeEntityPlan(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || input.version !== ENTITIES_PLAN_VERSION || input.contractId !== ENTITIES_CONTRACT_ID || !Array.isArray(input.routers)) {
+    throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Entity plan requires ${ENTITIES_PLAN_VERSION} and ${ENTITIES_CONTRACT_ID}.`);
+  }
+  const unknownPlan = Object.keys(input).filter((key) => !['version', 'contractId', 'routers'].includes(key)).sort();
+  if (unknownPlan.length > 0) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Entity plan contains unsupported fields: ${unknownPlan.join(', ')}.`);
+  const routerIds = new Set();
+  const routers = input.routers.map((router, routerIndex) => {
+    if (!router || typeof router !== 'object' || Array.isArray(router)) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `routers[${routerIndex}] must be an object.`);
+    const unknownRouter = Object.keys(router).filter((key) => !['id', 'adapter', 'binding', 'entities'].includes(key)).sort();
+    if (unknownRouter.length > 0) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `routers[${routerIndex}] contains unsupported fields: ${unknownRouter.join(', ')}.`);
+    const id = String(router.id || '');
+    if (!ROUTER_ID_PATTERN.test(id) || routerIds.has(id)) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Entity router ID is invalid or duplicated: ${id}.`, { id });
+    routerIds.add(id);
+    if (!router.binding || router.binding.kind !== 'request') throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.BINDING_UNSUPPORTED, 'Entity plan binding must be request.');
+    const adapter = runtime.normalizeAdapter(router.adapter);
+    if (!Array.isArray(router.entities)) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `routers[${routerIndex}].entities must be an array.`);
+    if (router.entities.length > runtime.ENTITIES_DEFAULT_LIMITS.maxEntities) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.LIMIT_EXCEEDED, `Entity plan router ${id} exceeds its entity limit.`);
+    const discriminators = new Set();
+    const entities = router.entities.map((entity, entityIndex) => {
+      if (!entity || typeof entity !== 'object' || Array.isArray(entity)) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `routers[${routerIndex}].entities[${entityIndex}] must be an object.`);
+      const unknown = Object.keys(entity).filter((key) => !['discriminator', 'inputSchema', 'outputSchema', 'handler', 'metadata'].includes(key)).sort();
+      if (unknown.length > 0) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Entity contains unsupported fields: ${unknown.join(', ')}.`);
+      const discriminator = runtime.normalizeDiscriminator(entity.discriminator);
+      if (discriminators.has(discriminator)) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.DISCRIMINATOR_DUPLICATE, `Duplicate entity ${discriminator}.`, { discriminator });
+      discriminators.add(discriminator);
+      return Object.freeze({ discriminator, inputSchema: runtime.normalizeSchemaId(entity.inputSchema, 'inputSchema'), outputSchema: runtime.normalizeSchemaId(entity.outputSchema, 'outputSchema'), handler: normalizeHandlerReference(entity.handler), ...(entity.metadata === undefined ? {} : { metadata: runtime.normalizeStaticMetadata(entity.metadata) }) });
+    }).sort((left, right) => runtime.compareText(left.discriminator, right.discriminator));
+    const metadataBytes = entities.reduce((sum, entity) => sum + (entity.metadata ? runtime.utf8ByteLength(stableStringify(entity.metadata)) : 0), 0);
+    if (metadataBytes > runtime.ENTITIES_DEFAULT_LIMITS.maxMetadataBytesPerRouter) throw runtime.entitiesContractError(runtime.ENTITIES_DIAGNOSTIC_CODES.LIMIT_EXCEEDED, `Entity plan router ${id} exceeds its metadata limit.`);
+    return Object.freeze({ id, adapter, binding: Object.freeze({ kind: 'request' }), entities: Object.freeze(entities) });
+  }).sort((left, right) => runtime.compareText(left.id, right.id));
+  const normalized = Object.freeze({ version: ENTITIES_PLAN_VERSION, contractId: ENTITIES_CONTRACT_ID, routers: Object.freeze(routers) });
+  return Object.freeze({ ...normalized, planHash: sha256Hex(stableStringify(normalized)) });
+}
+
+module.exports = Object.freeze({
+  ...runtime,
+  ENTITIES_PACKAGE_VERSION,
+  ENTITIES_CONTRACT_VERSION,
+  ENTITIES_PLAN_VERSION,
+  ENTITIES_CATALOG_VERSION,
+  ENTITIES_DIAGNOSTIC_VERSION,
+  ENTITIES_HANDLER_REFERENCE_VERSION,
+  ENTITIES_REGISTRY_VERSION,
+  ENTITIES_CONTRACT_ID,
+  ENTITIES_PACKAGE_NAME,
+  ENTITIES_LOWERER_ID,
+  ENTITIES_LOWERER_EXPORT,
+  ENTITIES_LOWERER_MANIFEST,
+  ENTITIES_LOWERABLE_SUBPATH,
+  ENTITIES_PACKAGE_INTRINSIC_VERSION,
+  ENTITIES_PUBLIC_SYMBOLS,
+  ENTITIES_PACKAGE_INTRINSICS,
+  normalizeHandlerReference,
+  normalizeEntityRegistry,
+  normalizeEntityPlan
+});

package/src/entities/json-rpc.d.ts

@@ -0,0 +1,27 @@
+import runtime = require('./runtime.js');
+
+declare interface JsonRpcOptions {
+  readonly namedParamsOnly?: true;
+  readonly acceptEmptyObjectForNoInput?: boolean;
+}
+
+declare const jsonRpcContracts: {
+  readonly ENTITIES_JSON_RPC_ADAPTER_VERSION: 'pulse.entities-json-rpc-adapter.v1';
+  readonly ENTITIES_JSON_RPC_ADAPTER_ID: 'json-rpc';
+  readonly ENTITIES_JSON_RPC_PROTOCOL: '2.0';
+  readonly ENTITIES_JSON_RPC_OPTIONS: Readonly<{ namedParamsOnly: true; acceptEmptyObjectForNoInput: false }>;
+  readonly ENTITIES_JSON_RPC_ERROR_CODES: Readonly<Record<string, number>>;
+  readonly ENTITIES_JSON_RPC_FAILURE_MAP: Readonly<Record<string, Readonly<{ code: number; message: string }>>>;
+  normalizeJsonRpcOptions(input?: JsonRpcOptions): Readonly<{ namedParamsOnly: true; acceptEmptyObjectForNoInput: boolean }>;
+  createJsonRpcAdapter(input?: JsonRpcOptions, limits?: typeof runtime.ENTITIES_DEFAULT_LIMITS): Readonly<{
+    version: string;
+    id: 'json-rpc';
+    adapterVersion: string;
+    options: Readonly<{ namedParamsOnly: true; acceptEmptyObjectForNoInput: boolean }>;
+    limits: typeof runtime.ENTITIES_DEFAULT_LIMITS;
+  }>;
+  normalizeJsonRpcId(value: unknown, present?: boolean): Readonly<{ kind: string; value: unknown }>;
+  mapEntitiesFailureToJsonRpc(failure: unknown): Readonly<{ code: number; message: string }>;
+};
+
+export = jsonRpcContracts;

package/src/entities/json-rpc.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const {
+  ENTITIES_DEFAULT_LIMITS,
+  ENTITIES_DIAGNOSTIC_CODES,
+  ENTITIES_FAILURE_VERSION,
+  ENTITIES_JSON_RPC_ADAPTER_VERSION,
+  ENTITIES_JSON_RPC_OPTIONS,
+  entitiesContractError,
+  normalizeJsonRpcAdapterOptions,
+  createJsonRpcAdapter: createRuntimeJsonRpcAdapter
+} = require('./runtime.js');
+
+const ENTITIES_JSON_RPC_ADAPTER_ID = 'json-rpc';
+const ENTITIES_JSON_RPC_PROTOCOL = '2.0';
+const ENTITIES_JSON_RPC_ERROR_CODES = Object.freeze({
+  parse: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internal: -32603
+});
+const ENTITIES_JSON_RPC_FAILURE_MAP = Object.freeze({
+  'invalid-envelope': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.invalidRequest, message: 'Invalid Request' }),
+  'unknown-entity': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.methodNotFound, message: 'Method not found' }),
+  'invalid-input': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.invalidParams, message: 'Invalid params' }),
+  'execution-failed': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.internal, message: 'Internal error' }),
+  'invalid-output': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.internal, message: 'Internal error' }),
+  'input-too-large': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.invalidRequest, message: 'Invalid Request' }),
+  'output-too-large': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.internal, message: 'Internal error' }),
+  'adapter-failed': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.internal, message: 'Internal error' }),
+  'runtime-not-realized': Object.freeze({ code: ENTITIES_JSON_RPC_ERROR_CODES.internal, message: 'Internal error' })
+});
+
+function normalizeJsonRpcOptions(input = {}) {
+  return normalizeJsonRpcAdapterOptions(input);
+}
+
+function createJsonRpcAdapter(options = {}, limitsInput = ENTITIES_DEFAULT_LIMITS) {
+  return createRuntimeJsonRpcAdapter(options, limitsInput);
+}
+
+function normalizeJsonRpcId(value, present = true) {
+  if (present !== true) return Object.freeze({ kind: 'absent', value: undefined });
+  if (value === null) return Object.freeze({ kind: 'null', value: null });
+  if (typeof value === 'string') return Object.freeze({ kind: 'string', value });
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return Object.freeze({ kind: 'number', value });
+  throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'JSON-RPC ID must be a string, safe integer, null, or absent.', { value });
+}
+
+function mapEntitiesFailureToJsonRpc(failure) {
+  if (!failure || failure.version !== ENTITIES_FAILURE_VERSION || !Object.prototype.hasOwnProperty.call(ENTITIES_JSON_RPC_FAILURE_MAP, failure.kind)) {
+    throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'JSON-RPC failure mapping requires a normalized Entities failure.');
+  }
+  return ENTITIES_JSON_RPC_FAILURE_MAP[failure.kind];
+}
+
+module.exports = Object.freeze({
+  ENTITIES_JSON_RPC_ADAPTER_VERSION,
+  ENTITIES_JSON_RPC_ADAPTER_ID,
+  ENTITIES_JSON_RPC_PROTOCOL,
+  ENTITIES_JSON_RPC_OPTIONS,
+  ENTITIES_JSON_RPC_ERROR_CODES,
+  ENTITIES_JSON_RPC_FAILURE_MAP,
+  normalizeJsonRpcOptions,
+  createJsonRpcAdapter,
+  normalizeJsonRpcId,
+  mapEntitiesFailureToJsonRpc
+});

package/src/entities/runtime.d.ts

@@ -0,0 +1,67 @@
+declare interface EntitiesRuntimeLimits {
+  readonly maxEnvelopeBytes: number;
+  readonly maxPayloadBytes: number;
+  readonly maxMethodBytes: number;
+  readonly maxEntities: number;
+  readonly maxMetadataBytesPerEntity: number;
+  readonly maxMetadataBytesPerRouter: number;
+  readonly maxMetadataDepth: number;
+  readonly maxMetadataEntries: number;
+  readonly maxJsonDepth: number;
+  readonly maxOutputBytes: number;
+  readonly maxErrorMessageBytes: number;
+}
+
+declare const runtime: {
+  readonly ENTITIES_ADAPTER_VERSION: 'pulse.entities-adapter.v1';
+  readonly ENTITIES_FAILURE_VERSION: 'pulse.entities-failure.v1';
+  readonly ENTITIES_JSON_RPC_ADAPTER_VERSION: 'pulse.entities-json-rpc-adapter.v1';
+  readonly ENTITIES_JSON_RPC_OPTIONS: Readonly<{ namedParamsOnly: true; acceptEmptyObjectForNoInput: false }>;
+  readonly ENTITIES_DEFAULT_LIMITS: EntitiesRuntimeLimits;
+  readonly ENTITIES_LIMIT_KEYS: readonly string[];
+  readonly ENTITIES_FAILURE_KINDS: readonly string[];
+  readonly ENTITIES_FAILURE_CODES: Readonly<Record<string, string>>;
+  readonly ENTITIES_DIAGNOSTIC_CODES: Readonly<Record<string, string>>;
+  entitiesContractError(code: string, message: string, detail?: Readonly<Record<string, unknown>>): TypeError & {
+    readonly code: string;
+    readonly detail: Readonly<Record<string, unknown>>;
+  };
+  utf8ByteLength(value: unknown): number;
+  compareText(left: string, right: string): number;
+  normalizeEntityLimits(input?: Readonly<Partial<EntitiesRuntimeLimits>>): EntitiesRuntimeLimits;
+  normalizeDiscriminator(value: unknown, limits?: EntitiesRuntimeLimits): string;
+  normalizeSchemaId(value: unknown, field?: string): string | null;
+  normalizeStaticMetadata(value: unknown, limits?: EntitiesRuntimeLimits): Readonly<Record<string, unknown>> | undefined;
+  normalizeEntityDeclaration(input: unknown, limits?: EntitiesRuntimeLimits): Readonly<{
+    input: string | null;
+    output: string | null;
+    metadata?: Readonly<Record<string, unknown>>;
+  }>;
+  normalizeHandler<T extends Function>(handler: T): T;
+  normalizeJsonRpcAdapterOptions(input?: Readonly<{ namedParamsOnly?: true; acceptEmptyObjectForNoInput?: boolean }>): Readonly<{
+    namedParamsOnly: true;
+    acceptEmptyObjectForNoInput: boolean;
+  }>;
+  normalizeAdapter(input: unknown, limits?: EntitiesRuntimeLimits): Readonly<{
+    version: string;
+    id: 'json-rpc';
+    adapterVersion: string;
+    options: Readonly<Record<string, unknown>>;
+    limits: EntitiesRuntimeLimits;
+  }>;
+  createJsonRpcAdapter(input?: Readonly<{ namedParamsOnly?: true; acceptEmptyObjectForNoInput?: boolean }>, limits?: EntitiesRuntimeLimits): Readonly<{
+    version: string;
+    id: 'json-rpc';
+    adapterVersion: string;
+    options: Readonly<{ namedParamsOnly: true; acceptEmptyObjectForNoInput: boolean }>;
+    limits: EntitiesRuntimeLimits;
+  }>;
+  normalizeEntityRegistration(input: unknown, limits?: EntitiesRuntimeLimits): Readonly<{
+    discriminator: string;
+    declaration: Readonly<{ input: string | null; output: string | null; metadata?: Readonly<Record<string, unknown>> }>;
+    handler: Function;
+  }>;
+  normalizeEntityFailure(input: unknown, limits?: EntitiesRuntimeLimits): Readonly<Record<string, unknown>>;
+};
+
+export = runtime;

package/src/entities/runtime.js

@@ -0,0 +1,288 @@
+'use strict';
+
+const ENTITIES_ADAPTER_VERSION = 'pulse.entities-adapter.v1';
+const ENTITIES_FAILURE_VERSION = 'pulse.entities-failure.v1';
+const ENTITIES_JSON_RPC_ADAPTER_VERSION = 'pulse.entities-json-rpc-adapter.v1';
+const ENTITIES_JSON_RPC_OPTIONS = Object.freeze({
+  namedParamsOnly: true,
+  acceptEmptyObjectForNoInput: false
+});
+const ENTITIES_DEFAULT_LIMITS = Object.freeze({
+  maxEnvelopeBytes: 65_536,
+  maxPayloadBytes: 32_768,
+  maxMethodBytes: 256,
+  maxEntities: 256,
+  maxMetadataBytesPerEntity: 4_096,
+  maxMetadataBytesPerRouter: 65_536,
+  maxMetadataDepth: 8,
+  maxMetadataEntries: 128,
+  maxJsonDepth: 32,
+  maxOutputBytes: 65_536,
+  maxErrorMessageBytes: 256
+});
+const ENTITIES_LIMIT_KEYS = Object.freeze(Object.keys(ENTITIES_DEFAULT_LIMITS));
+const ENTITIES_FAILURE_KINDS = Object.freeze([
+  'invalid-envelope',
+  'unknown-entity',
+  'invalid-input',
+  'execution-failed',
+  'invalid-output',
+  'input-too-large',
+  'output-too-large',
+  'adapter-failed',
+  'runtime-not-realized'
+]);
+const ENTITIES_FAILURE_CODES = Object.freeze({
+  'invalid-envelope': 'PULSE_ENTITIES_INVALID_ENVELOPE',
+  'unknown-entity': 'PULSE_ENTITIES_UNKNOWN_ENTITY',
+  'invalid-input': 'PULSE_ENTITIES_INPUT_INVALID',
+  'execution-failed': 'PULSE_ENTITIES_EXECUTION_FAILED',
+  'invalid-output': 'PULSE_ENTITIES_OUTPUT_INVALID',
+  'input-too-large': 'PULSE_ENTITIES_INPUT_TOO_LARGE',
+  'output-too-large': 'PULSE_ENTITIES_OUTPUT_TOO_LARGE',
+  'adapter-failed': 'PULSE_ENTITIES_ADAPTER_FAILED',
+  'runtime-not-realized': 'PULSE_ENTITIES_RUNTIME_NOT_REALIZED'
+});
+const ENTITIES_DIAGNOSTIC_CODES = Object.freeze({
+  ADAPTER_STATIC_REQUIRED: 'PULSE_ENTITIES_ADAPTER_STATIC_REQUIRED',
+  ADAPTER_UNSUPPORTED: 'PULSE_ENTITIES_ADAPTER_UNSUPPORTED',
+  ADAPTER_OPTIONS_INVALID: 'PULSE_ENTITIES_ADAPTER_OPTIONS_INVALID',
+  DISCRIMINATOR_STATIC_REQUIRED: 'PULSE_ENTITIES_DISCRIMINATOR_STATIC_REQUIRED',
+  DISCRIMINATOR_INVALID: 'PULSE_ENTITIES_DISCRIMINATOR_INVALID',
+  DISCRIMINATOR_DUPLICATE: 'PULSE_ENTITIES_DISCRIMINATOR_DUPLICATE',
+  SCHEMA_MISSING: 'PULSE_ENTITIES_SCHEMA_MISSING',
+  SCHEMA_ID_INVALID: 'PULSE_ENTITIES_SCHEMA_ID_INVALID',
+  DECLARATION_INVALID: 'PULSE_ENTITIES_DECLARATION_INVALID',
+  HANDLER_UNRESOLVED: 'PULSE_ENTITIES_HANDLER_UNRESOLVED',
+  HANDLER_INVALID: 'PULSE_ENTITIES_HANDLER_INVALID',
+  METADATA_INVALID: 'PULSE_ENTITIES_METADATA_INVALID',
+  LIMIT_INVALID: 'PULSE_ENTITIES_LIMIT_INVALID',
+  LIMIT_EXCEEDED: 'PULSE_ENTITIES_LIMIT_EXCEEDED',
+  REGISTRATION_UNSUPPORTED: 'PULSE_ENTITIES_REGISTRATION_UNSUPPORTED',
+  BINDING_UNSUPPORTED: 'PULSE_ENTITIES_BINDING_UNSUPPORTED',
+  BODY_CONSUMER_CONFLICT: 'PULSE_ENTITIES_BODY_CONSUMER_CONFLICT',
+  TARGET_INELIGIBLE: 'PULSE_ENTITIES_TARGET_INELIGIBLE'
+});
+const SCHEMA_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z][A-Za-z0-9_-]*)+$/;
+
+function entitiesContractError(code, message, detail = {}) {
+  const error = new TypeError(message);
+  error.name = 'EntitiesContractError';
+  error.code = code;
+  error.detail = Object.freeze({ ...detail });
+  return error;
+}
+
+function plainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function assertDataObject(value, field, code = ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID) {
+  if (!plainObject(value)) throw entitiesContractError(code, `${field} must be a plain object.`, { field });
+  if (Object.getOwnPropertySymbols(value).length > 0) throw entitiesContractError(code, `${field} must not contain symbol keys.`, { field });
+  for (const key of Object.keys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+      throw entitiesContractError(code, `${field}.${key} must be an own data property.`, { field, key });
+    }
+  }
+  return value;
+}
+
+function assertKnownKeys(value, allowed, field, code = ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key)).sort();
+  if (unknown.length > 0) throw entitiesContractError(code, `${field} contains unsupported fields: ${unknown.join(', ')}.`, { field, unknown });
+}
+
+function utf8ByteLength(value) {
+  const text = String(value);
+  let bytes = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const point = text.codePointAt(index);
+    if (point <= 0x7f) bytes += 1;
+    else if (point <= 0x7ff) bytes += 2;
+    else if (point <= 0xffff) bytes += 3;
+    else {
+      bytes += 4;
+      index += 1;
+    }
+  }
+  return bytes;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function normalizeEntityLimits(input = {}) {
+  assertDataObject(input, 'limits', ENTITIES_DIAGNOSTIC_CODES.LIMIT_INVALID);
+  assertKnownKeys(input, ENTITIES_LIMIT_KEYS, 'limits', ENTITIES_DIAGNOSTIC_CODES.LIMIT_INVALID);
+  const output = {};
+  for (const name of ENTITIES_LIMIT_KEYS) {
+    const value = input[name] === undefined ? ENTITIES_DEFAULT_LIMITS[name] : Number(input[name]);
+    if (!Number.isSafeInteger(value) || value <= 0) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.LIMIT_INVALID, `limits.${name} must be a positive safe integer.`, { name, value });
+    output[name] = value;
+  }
+  if (output.maxPayloadBytes > output.maxEnvelopeBytes) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.LIMIT_INVALID, 'maxPayloadBytes cannot exceed maxEnvelopeBytes.');
+  if (output.maxMetadataBytesPerEntity > output.maxMetadataBytesPerRouter) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.LIMIT_INVALID, 'Per-entity metadata bytes cannot exceed the router metadata limit.');
+  return Object.freeze(output);
+}
+
+function normalizeDiscriminator(value, limitsInput = ENTITIES_DEFAULT_LIMITS) {
+  const limits = limitsInput === ENTITIES_DEFAULT_LIMITS ? limitsInput : normalizeEntityLimits(limitsInput);
+  if (typeof value !== 'string' || value.trim() === '') throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DISCRIMINATOR_INVALID, 'Entity discriminator must be a non-empty string.', { value });
+  const bytes = utf8ByteLength(value);
+  if (bytes > limits.maxMethodBytes) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DISCRIMINATOR_INVALID, 'Entity discriminator exceeds its UTF-8 byte limit.', { bytes, maxBytes: limits.maxMethodBytes });
+  return value;
+}
+
+function normalizeSchemaId(value, field = 'schemaId') {
+  if (value === null) return null;
+  if (typeof value !== 'string' || !SCHEMA_ID_PATTERN.test(value)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.SCHEMA_ID_INVALID, `${field} must be a dotted schema ID or null.`, { field, value });
+  return value;
+}
+
+function normalizeStaticMetadata(input, limitsInput = ENTITIES_DEFAULT_LIMITS) {
+  if (input === undefined) return undefined;
+  const limits = limitsInput === ENTITIES_DEFAULT_LIMITS ? limitsInput : normalizeEntityLimits(limitsInput);
+  let entries = 0;
+  const ancestors = new Set();
+  function visit(value, field, depth) {
+    if (depth > limits.maxMetadataDepth) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.METADATA_INVALID, 'Entity metadata exceeds its nesting limit.', { field, depth, maxDepth: limits.maxMetadataDepth });
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.METADATA_INVALID, `${field} must be finite.`, { field });
+      return value;
+    }
+    if (typeof value !== 'object') throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.METADATA_INVALID, `${field} must be static JSON.`, { field, kind: typeof value });
+    if (ancestors.has(value)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.METADATA_INVALID, 'Entity metadata must not contain cycles.', { field });
+    ancestors.add(value);
+    let output;
+    if (Array.isArray(value)) {
+      entries += value.length;
+      output = value.map((entry, index) => visit(entry, `${field}[${index}]`, depth + 1));
+    } else {
+      assertDataObject(value, field, ENTITIES_DIAGNOSTIC_CODES.METADATA_INVALID);
+      const keys = Object.keys(value).sort();
+      entries += keys.length;
+      output = Object.fromEntries(keys.map((key) => [key, visit(value[key], `${field}.${key}`, depth + 1)]));
+    }
+    ancestors.delete(value);
+    if (entries > limits.maxMetadataEntries) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.METADATA_INVALID, 'Entity metadata exceeds its entry limit.', { entries, maxEntries: limits.maxMetadataEntries });
+    return output;
+  }
+  if (!plainObject(input)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.METADATA_INVALID, 'Entity metadata root must be a plain object.');
+  const normalized = deepFreeze(visit(input, 'metadata', 0));
+  const bytes = utf8ByteLength(JSON.stringify(normalized));
+  if (bytes > limits.maxMetadataBytesPerEntity) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.METADATA_INVALID, 'Entity metadata exceeds its byte limit.', { bytes, maxBytes: limits.maxMetadataBytesPerEntity });
+  return normalized;
+}
+
+function normalizeEntityDeclaration(input, limitsInput = ENTITIES_DEFAULT_LIMITS) {
+  const limits = limitsInput === ENTITIES_DEFAULT_LIMITS ? limitsInput : normalizeEntityLimits(limitsInput);
+  assertDataObject(input, 'declaration');
+  assertKnownKeys(input, ['input', 'output', 'metadata'], 'declaration');
+  if (!Object.prototype.hasOwnProperty.call(input, 'input') || !Object.prototype.hasOwnProperty.call(input, 'output')) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Entity declaration requires explicit input and output fields.');
+  return Object.freeze({
+    input: normalizeSchemaId(input.input, 'declaration.input'),
+    output: normalizeSchemaId(input.output, 'declaration.output'),
+    ...(input.metadata === undefined ? {} : { metadata: normalizeStaticMetadata(input.metadata, limits) })
+  });
+}
+
+function normalizeHandler(handler) {
+  if (typeof handler !== 'function' || typeof handler.name !== 'string' || handler.name.trim() === '') throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.HANDLER_INVALID, 'Entity handler must be a named function reference.');
+  return handler;
+}
+
+function normalizeJsonRpcAdapterOptions(input = {}) {
+  assertDataObject(input, 'adapter.options', ENTITIES_DIAGNOSTIC_CODES.ADAPTER_OPTIONS_INVALID);
+  assertKnownKeys(input, Object.keys(ENTITIES_JSON_RPC_OPTIONS), 'adapter.options', ENTITIES_DIAGNOSTIC_CODES.ADAPTER_OPTIONS_INVALID);
+  const namedParamsOnly = input.namedParamsOnly === undefined ? true : input.namedParamsOnly;
+  const acceptEmptyObjectForNoInput = input.acceptEmptyObjectForNoInput === undefined ? false : input.acceptEmptyObjectForNoInput;
+  if (namedParamsOnly !== true) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.ADAPTER_OPTIONS_INVALID, 'jsonRpc namedParamsOnly must remain true in the first contract.');
+  if (typeof acceptEmptyObjectForNoInput !== 'boolean') throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.ADAPTER_OPTIONS_INVALID, 'jsonRpc acceptEmptyObjectForNoInput must be boolean.');
+  return Object.freeze({ namedParamsOnly: true, acceptEmptyObjectForNoInput });
+}
+
+function normalizeAdapter(input, limitsInput = ENTITIES_DEFAULT_LIMITS) {
+  const limits = limitsInput === ENTITIES_DEFAULT_LIMITS ? limitsInput : normalizeEntityLimits(limitsInput);
+  assertDataObject(input, 'adapter', ENTITIES_DIAGNOSTIC_CODES.ADAPTER_STATIC_REQUIRED);
+  assertKnownKeys(input, ['version', 'id', 'adapterVersion', 'options', 'limits'], 'adapter', ENTITIES_DIAGNOSTIC_CODES.ADAPTER_OPTIONS_INVALID);
+  if (input.version !== ENTITIES_ADAPTER_VERSION || input.id !== 'json-rpc' || input.adapterVersion !== ENTITIES_JSON_RPC_ADAPTER_VERSION) {
+    throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.ADAPTER_UNSUPPORTED, 'Only the first-party json-rpc adapter is supported.', { version: input.version, id: input.id, adapterVersion: input.adapterVersion });
+  }
+  return deepFreeze({
+    version: ENTITIES_ADAPTER_VERSION,
+    id: 'json-rpc',
+    adapterVersion: ENTITIES_JSON_RPC_ADAPTER_VERSION,
+    options: normalizeJsonRpcAdapterOptions(input.options),
+    limits: input.limits === undefined ? limits : normalizeEntityLimits(input.limits)
+  });
+}
+
+function createJsonRpcAdapter(options = {}, limitsInput = ENTITIES_DEFAULT_LIMITS) {
+  return Object.freeze({
+    version: ENTITIES_ADAPTER_VERSION,
+    id: 'json-rpc',
+    adapterVersion: ENTITIES_JSON_RPC_ADAPTER_VERSION,
+    options: normalizeJsonRpcAdapterOptions(options),
+    limits: limitsInput === ENTITIES_DEFAULT_LIMITS ? ENTITIES_DEFAULT_LIMITS : normalizeEntityLimits(limitsInput)
+  });
+}
+
+function normalizeEntityRegistration(input, limitsInput = ENTITIES_DEFAULT_LIMITS) {
+  const limits = limitsInput === ENTITIES_DEFAULT_LIMITS ? limitsInput : normalizeEntityLimits(limitsInput);
+  assertDataObject(input, 'registration');
+  assertKnownKeys(input, ['discriminator', 'declaration', 'handler'], 'registration');
+  return Object.freeze({
+    discriminator: normalizeDiscriminator(input.discriminator, limits),
+    declaration: normalizeEntityDeclaration(input.declaration, limits),
+    handler: normalizeHandler(input.handler)
+  });
+}
+
+function normalizeEntityFailure(input, limitsInput = ENTITIES_DEFAULT_LIMITS) {
+  const limits = limitsInput === ENTITIES_DEFAULT_LIMITS ? limitsInput : normalizeEntityLimits(limitsInput);
+  assertDataObject(input, 'failure');
+  assertKnownKeys(input, ['version', 'kind', 'message'], 'failure');
+  const kind = String(input.kind || '');
+  if (!ENTITIES_FAILURE_KINDS.includes(kind)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Unsupported Entities failure kind ${kind}.`, { kind });
+  const message = String(input.message || 'Entity operation failed.');
+  if (utf8ByteLength(message) > limits.maxErrorMessageBytes) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.LIMIT_EXCEEDED, 'Entities failure message exceeds its byte limit.');
+  return Object.freeze({ version: ENTITIES_FAILURE_VERSION, kind, code: ENTITIES_FAILURE_CODES[kind], message });
+}
+
+module.exports = Object.freeze({
+  ENTITIES_ADAPTER_VERSION,
+  ENTITIES_FAILURE_VERSION,
+  ENTITIES_JSON_RPC_ADAPTER_VERSION,
+  ENTITIES_JSON_RPC_OPTIONS,
+  ENTITIES_DEFAULT_LIMITS,
+  ENTITIES_LIMIT_KEYS,
+  ENTITIES_FAILURE_KINDS,
+  ENTITIES_FAILURE_CODES,
+  ENTITIES_DIAGNOSTIC_CODES,
+  entitiesContractError,
+  utf8ByteLength,
+  compareText,
+  normalizeEntityLimits,
+  normalizeDiscriminator,
+  normalizeSchemaId,
+  normalizeStaticMetadata,
+  normalizeEntityDeclaration,
+  normalizeHandler,
+  normalizeJsonRpcAdapterOptions,
+  normalizeAdapter,
+  createJsonRpcAdapter,
+  normalizeEntityRegistration,
+  normalizeEntityFailure
+});