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

package/src/definitions/handler-roles.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const HANDLER_ROLE_VERSION = 'pulsewasm.handler-role-definitions.v1';
+
+const HANDLER_ROLE_DEFINITIONS = Object.freeze([
+  Object.freeze({ role: 'route', params: 2, display: '(ctx, next) => PulseResult | void', asyncAllowed: false, generatorAllowed: false, promiseReturnAllowed: false }),
+  Object.freeze({ role: 'middleware', params: 2, display: '(ctx, next) => PulseResult | void', asyncAllowed: false, generatorAllowed: false, promiseReturnAllowed: false }),
+  Object.freeze({ role: 'lifecycle', params: 2, display: '(ctx, next) => void', asyncAllowed: false, generatorAllowed: false, promiseReturnAllowed: false }),
+  Object.freeze({ role: 'error', params: 3, display: '(err, ctx, next) => PulseResult | void', asyncAllowed: false, generatorAllowed: false, promiseReturnAllowed: false }),
+  Object.freeze({ role: 'channel', params: 1, display: '(ctx) => string | string[]', asyncAllowed: false, generatorAllowed: false, promiseReturnAllowed: false })
+]);
+
+function buildHandlerRoleRegistry(definitions = HANDLER_ROLE_DEFINITIONS) {
+  const list = Array.from(definitions);
+  const byRole = new Map();
+  for (const definition of list) {
+    if (!definition || !definition.role) throw new Error('Handler role definition is missing a role.');
+    if (byRole.has(definition.role)) throw new Error(`Duplicate handler role definition: ${definition.role}`);
+    byRole.set(definition.role, definition);
+  }
+  return Object.freeze({
+    version: HANDLER_ROLE_VERSION,
+    definitions: Object.freeze(list),
+    byRole,
+    get(role) {
+      return byRole.get(role);
+    },
+    has(role) {
+      return byRole.has(role);
+    },
+    roleNames() {
+      return Array.from(byRole.keys());
+    },
+    asSignatureMap() {
+      const out = {};
+      for (const [role, definition] of byRole.entries()) {
+        out[role] = { params: definition.params, display: definition.display };
+      }
+      return out;
+    }
+  });
+}
+
+const DEFAULT_HANDLER_ROLE_REGISTRY = buildHandlerRoleRegistry();
+const ROLE_SIGNATURES = DEFAULT_HANDLER_ROLE_REGISTRY.asSignatureMap();
+
+function roleForOperation(op) {
+  if (!op) return undefined;
+  if (op.route) return 'route';
+  if (op.kind === 'use') return 'middleware';
+  if (op.kind === 'get' || op.kind === 'post') return 'route';
+  if (op.kind === 'lifecycle') return 'lifecycle';
+  if (op.kind === 'error') return 'error';
+  if (op.kind === 'channel') return 'channel';
+  if (op.role) return op.role;
+  return undefined;
+}
+
+module.exports = {
+  HANDLER_ROLE_VERSION,
+  HANDLER_ROLE_DEFINITIONS,
+  DEFAULT_HANDLER_ROLE_REGISTRY,
+  ROLE_SIGNATURES,
+  buildHandlerRoleRegistry,
+  roleForOperation
+};

package/src/definitions/path-grammar.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const {
+  PATH_GRAMMAR_VERSION,
+  PATH_POLICY
+} = require('../path.js');
+
+module.exports = {
+  PATH_GRAMMAR_VERSION,
+  PATH_POLICY
+};

package/src/definitions/router-api.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const ROUTER_API_VERSION = 'pulsewasm.router-api-definitions.v1';
+
+function createHttpRouteDefinition(name, method) {
+  if (!name || !method) throw new Error('createHttpRouteDefinition requires name and method.');
+  return Object.freeze({
+    name,
+    kind: 'route',
+    opKind: name,
+    method: String(method).toUpperCase(),
+    allowedArities: [2],
+    signatures: Object.freeze([
+      Object.freeze({ arity: 2, pathArg: 0, handlerArg: 1 })
+    ]),
+    pathPolicy: 'required-static',
+    role: 'route'
+  });
+}
+
+const ROUTER_API_DEFINITIONS = Object.freeze([
+  Object.freeze({
+    name: 'use',
+    kind: 'middleware',
+    opKind: 'use',
+    allowedArities: Object.freeze([1, 2]),
+    signatures: Object.freeze([
+      Object.freeze({ arity: 1, handlerArg: 0 }),
+      Object.freeze({ arity: 2, pathArg: 0, handlerArg: 1 })
+    ]),
+    pathPolicy: 'optional-static',
+    role: 'middleware'
+  }),
+  createHttpRouteDefinition('get', 'GET'),
+  createHttpRouteDefinition('head', 'HEAD'),
+  createHttpRouteDefinition('post', 'POST'),
+  createHttpRouteDefinition('put', 'PUT'),
+  createHttpRouteDefinition('patch', 'PATCH'),
+  createHttpRouteDefinition('delete', 'DELETE'),
+  Object.freeze({
+    name: 'mount',
+    kind: 'mount',
+    opKind: 'mount',
+    allowedArities: Object.freeze([2]),
+    signatures: Object.freeze([
+      Object.freeze({ arity: 2, pathArg: 0, routerArg: 1 })
+    ]),
+    pathPolicy: 'mount-static'
+  }),
+  Object.freeze({
+    name: 'channel',
+    kind: 'channel',
+    opKind: 'channel',
+    allowedArities: Object.freeze([1]),
+    signatures: Object.freeze([
+      Object.freeze({ arity: 1, valueArg: 0 })
+    ]),
+    pathPolicy: 'none',
+    role: 'channel'
+  }),
+  Object.freeze({
+    name: 'on',
+    kind: 'lifecycle',
+    opKind: 'lifecycle',
+    allowedArities: Object.freeze([2]),
+    signatures: Object.freeze([
+      Object.freeze({ arity: 2, eventArg: 0, handlerArg: 1 })
+    ]),
+    allowedEvents: Object.freeze(['connect', 'disconnect']),
+    pathPolicy: 'none',
+    role: 'lifecycle'
+  }),
+  Object.freeze({
+    name: 'error',
+    kind: 'error',
+    opKind: 'error',
+    allowedArities: Object.freeze([1]),
+    signatures: Object.freeze([
+      Object.freeze({ arity: 1, handlerArg: 0 })
+    ]),
+    pathPolicy: 'none',
+    role: 'error'
+  }),
+  Object.freeze({
+    name: 'timeout',
+    kind: 'timeout',
+    opKind: 'timeout',
+    allowedArities: Object.freeze([1]),
+    signatures: Object.freeze([
+      Object.freeze({ arity: 1, valueArg: 0 })
+    ]),
+    pathPolicy: 'none'
+  })
+]);
+
+function buildRouterApiRegistry(definitions = ROUTER_API_DEFINITIONS) {
+  const list = Array.from(definitions);
+  const byName = new Map();
+  for (const definition of list) {
+    if (!definition || !definition.name) throw new Error('Router API definition is missing a name.');
+    if (byName.has(definition.name)) throw new Error(`Duplicate router API definition: ${definition.name}`);
+    byName.set(definition.name, definition);
+  }
+  return Object.freeze({
+    version: ROUTER_API_VERSION,
+    definitions: Object.freeze(list),
+    byName,
+    supportedMethods: new Set(byName.keys()),
+    routeMethods: new Set(list.filter((definition) => definition.kind === 'route').map((definition) => definition.name)),
+    get(name) {
+      return byName.get(name);
+    },
+    has(name) {
+      return byName.has(name);
+    },
+    supportedMethodNames() {
+      return Array.from(byName.keys());
+    }
+  });
+}
+
+const DEFAULT_ROUTER_API_REGISTRY = buildRouterApiRegistry();
+const SUPPORTED_METHODS = DEFAULT_ROUTER_API_REGISTRY.supportedMethods;
+const ROUTE_METHODS = DEFAULT_ROUTER_API_REGISTRY.routeMethods;
+
+function signatureForArity(definition, arity) {
+  return (definition.signatures || []).find((signature) => signature.arity === arity);
+}
+
+function arityDisplay(definition) {
+  const allowed = Array.from(definition.allowedArities || []);
+  if (allowed.length === 0) return '0';
+  if (allowed.length === 1) return String(allowed[0]);
+  const min = Math.min(...allowed);
+  const max = Math.max(...allowed);
+  return allowed.length === max - min + 1 ? `${min}-${max}` : allowed.join(' or ');
+}
+
+module.exports = {
+  ROUTER_API_VERSION,
+  ROUTER_API_DEFINITIONS,
+  DEFAULT_ROUTER_API_REGISTRY,
+  SUPPORTED_METHODS,
+  ROUTE_METHODS,
+  arityDisplay,
+  buildRouterApiRegistry,
+  createHttpRouteDefinition,
+  signatureForArity
+};

package/src/diagnostics/codes.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const DIAGNOSTIC_CODE_VERSION = 'pulsewasm.diagnostic-codes.v1';
+
+const DIAGNOSTIC_CODES = Object.freeze({
+  UNSUPPORTED_ROUTER_METHOD: 'PULSEWASM_UNSUPPORTED_ROUTER_METHOD',
+  ARITY: 'PULSEWASM_ARITY',
+  DYNAMIC_PATH: 'PULSEWASM_DYNAMIC_PATH',
+  INVALID_PATH: 'PULSEWASM_INVALID_PATH',
+  UNSUPPORTED_HANDLER: 'PULSEWASM_UNSUPPORTED_HANDLER',
+  UNSUPPORTED_CHANNEL: 'PULSEWASM_UNSUPPORTED_CHANNEL',
+  UNSUPPORTED_LIFECYCLE: 'PULSEWASM_UNSUPPORTED_LIFECYCLE',
+  UNSUPPORTED_MOUNT_TARGET: 'PULSEWASM_UNSUPPORTED_MOUNT_TARGET',
+  COMPUTED_METHOD: 'PULSEWASM_COMPUTED_METHOD',
+  DYNAMIC_ROUTE_REGISTRATION: 'PULSEWASM_DYNAMIC_ROUTE_REGISTRATION',
+  ROUTER_REASSIGNMENT: 'PULSEWASM_ROUTER_REASSIGNMENT',
+  HANDLER_BINDING_UNKNOWN_HANDLER: 'PULSEWASM_HANDLER_BINDING_UNKNOWN_HANDLER',
+  HANDLER_BINDING_INLINE_UNSUPPORTED: 'PULSEWASM_HANDLER_BINDING_INLINE_UNSUPPORTED',
+  HANDLER_BINDING_NOT_EXPORTED: 'PULSEWASM_HANDLER_BINDING_NOT_EXPORTED',
+  HANDLER_BINDING_EXPORT_NAME_MISSING: 'PULSEWASM_HANDLER_BINDING_EXPORT_NAME_MISSING',
+  UNSUPPORTED_ROUTER_CONSTRUCTION: 'PULSEWASM_UNSUPPORTED_ROUTER_CONSTRUCTION',
+  GUEST_UNIT_INVALID: 'PULSE_GUEST_UNIT_INVALID',
+  GUEST_UNIT_HASH_MISMATCH: 'PULSE_GUEST_UNIT_HASH_MISMATCH',
+  GUEST_UNIT_OWNER_MISMATCH: 'PULSE_GUEST_UNIT_OWNER_MISMATCH',
+  GUEST_UNIT_ABI_MISMATCH: 'PULSE_GUEST_UNIT_ABI_MISMATCH',
+  GUEST_UNIT_IMPORT_MISMATCH: 'PULSE_GUEST_UNIT_IMPORT_MISMATCH',
+  GUEST_UNIT_EXPORT_MISMATCH: 'PULSE_GUEST_UNIT_EXPORT_MISMATCH',
+  GUEST_UNIT_MEMORY_MISMATCH: 'PULSE_GUEST_UNIT_MEMORY_MISMATCH',
+  GUEST_UNIT_START_MISMATCH: 'PULSE_GUEST_UNIT_START_MISMATCH',
+  GUEST_UNIT_FEATURE_MISMATCH: 'PULSE_GUEST_UNIT_FEATURE_MISMATCH',
+  GUEST_UNIT_MATERIALIZATION_FAILED: 'PULSE_GUEST_UNIT_MATERIALIZATION_FAILED',
+  GUEST_UNIT_CARDINALITY_UNSUPPORTED: 'PULSE_GUEST_UNIT_CARDINALITY_UNSUPPORTED',
+  GUEST_TARGET_POLICY_REQUIRED: 'PULSE_GUEST_TARGET_POLICY_REQUIRED',
+  GUEST_LINK_FAILED: 'PULSE_GUEST_LINK_FAILED',
+  GUEST_OPTIMIZATION_FAILED: 'PULSE_GUEST_OPTIMIZATION_FAILED',
+  GUEST_FINAL_AUDIT_FAILED: 'PULSE_GUEST_FINAL_AUDIT_FAILED'
+});
+
+module.exports = {
+  DIAGNOSTIC_CODE_VERSION,
+  DIAGNOSTIC_CODES
+};

package/src/diagnostics/reporter.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const core = require('../diagnostics.js');
+
+function createDiagnosticReporter(defaults = {}) {
+  return {
+    report(sourceFile, node, code, message, hint, options = {}) {
+      return core.diagnostic(sourceFile, node, code, message, hint, { ...defaults, ...options });
+    },
+    push(diagnostics, sourceFile, node, code, message, hint, options = {}) {
+      const diag = this.report(sourceFile, node, code, message, hint, options);
+      diagnostics.push(diag);
+      return diag;
+    }
+  };
+}
+
+module.exports = {
+  createDiagnosticReporter
+};

package/src/diagnostics.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const path = require('node:path');
+
+const PACKAGE_VERSION = 'pulsewasm-route-extractor@1.0.0-beta.2';
+const DIAGNOSTICS_VERSION = 'pulsewasm.diagnostics.v1';
+
+function stableFileName(fileName, cwd) {
+  if (!fileName) return fileName;
+  if (fileName.startsWith('<') && fileName.endsWith('>')) return fileName;
+  const root = cwd || process.cwd();
+  const rel = path.relative(root, fileName);
+  return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : fileName;
+}
+
+function normalizeArtifact(value, cwd) {
+  if (Array.isArray(value)) return value.map((item) => normalizeArtifact(item, cwd));
+  if (!value || typeof value !== 'object') return value;
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    if ((key === 'file' || key === 'source') && typeof child === 'string') {
+      out[key] = stableFileName(child, cwd);
+    } else {
+      out[key] = normalizeArtifact(child, cwd);
+    }
+  }
+  return out;
+}
+
+class ExtractionError extends Error {
+  constructor(diagnostics, options = {}) {
+    const list = Array.isArray(diagnostics) ? diagnostics : [diagnostics];
+    const normalized = normalizeDiagnostics(list);
+    super(formatDiagnostics(normalized));
+    this.name = 'ExtractionError';
+    this.diagnostics = normalized;
+    this.status = options.status || 'error';
+    this.passes = options.passes || [];
+    this.summary = options.summary;
+    this.source = options.source;
+  }
+}
+
+function sourceLoc(sourceFile, node) {
+  const start = typeof node.getStart === 'function' ? node.getStart(sourceFile) : node.pos ?? 0;
+  const end = node.end ?? start;
+  const startLC = sourceFile.getLineAndCharacterOfPosition(start);
+  const endLC = sourceFile.getLineAndCharacterOfPosition(end);
+  return {
+    file: sourceFile.fileName,
+    start: { line: startLC.line + 1, column: startLC.character + 1, offset: start },
+    end: { line: endLC.line + 1, column: endLC.character + 1, offset: end }
+  };
+}
+
+function diagnostic(sourceFile, node, code, message, hint, options = {}) {
+  return normalizeDiagnostic({
+    code,
+    message,
+    hint,
+    severity: options.severity || 'error',
+    pass: options.pass || options.phase,
+    phase: options.phase,
+    loc: node ? sourceLoc(sourceFile, node) : { file: sourceFile.fileName }
+  });
+}
+
+function normalizeDiagnostic(diag, index) {
+  const loc = diag.loc || { file: '<unknown>' };
+  const out = {
+    code: diag.code || 'PULSEWASM_DIAGNOSTIC',
+    severity: diag.severity || 'error',
+    message: diag.message || '',
+    loc
+  };
+  const pass = diag.pass || diag.phase;
+  if (pass) out.pass = pass;
+  if (diag.hint) out.hint = diag.hint;
+  if (diag.details !== undefined) out.details = diag.details;
+  if (typeof index === 'number') out.index = index;
+  return out;
+}
+
+function normalizeDiagnostics(diagnostics) {
+  const list = Array.isArray(diagnostics) ? diagnostics : diagnostics ? [diagnostics] : [];
+  return list.map((diag, index) => normalizeDiagnostic(diag, index));
+}
+
+function countDiagnostics(diagnostics) {
+  const counts = { total: diagnostics.length, error: 0, warning: 0, info: 0 };
+  for (const diag of diagnostics) {
+    const severity = diag.severity || 'error';
+    if (counts[severity] === undefined) counts[severity] = 0;
+    counts[severity] += 1;
+  }
+  return counts;
+}
+
+function createDiagnosticsEnvelope(options = {}) {
+  const diagnostics = normalizeDiagnostics(options.diagnostics || []);
+  return normalizeArtifact({
+    version: DIAGNOSTICS_VERSION,
+    generatedBy: options.generatedBy || PACKAGE_VERSION,
+    status: options.status || (diagnostics.some((diag) => diag.severity === 'error') ? 'error' : 'ok'),
+    source: options.source,
+    entryRouter: options.entryRouter,
+    passes: options.passes || [],
+    summary: options.summary,
+    counts: countDiagnostics(diagnostics),
+    diagnostics
+  }, options.cwd || process.cwd());
+}
+
+function formatDiagnostics(diagnostics) {
+  return normalizeDiagnostics(diagnostics)
+    .map((diag) => {
+      const loc = diag.loc || {};
+      const start = loc.start ? `${loc.file}:${loc.start.line}:${loc.start.column}` : loc.file || '<unknown>';
+      const pass = diag.pass ? ` [${diag.pass}]` : '';
+      const hint = diag.hint ? `\n  hint: ${diag.hint}` : '';
+      return `${start}${pass} ${diag.code}: ${diag.message}${hint}`;
+    })
+    .join('\n');
+}
+
+module.exports = {
+  PACKAGE_VERSION,
+  DIAGNOSTICS_VERSION,
+  ExtractionError,
+  countDiagnostics,
+  createDiagnosticsEnvelope,
+  diagnostic,
+  formatDiagnostics,
+  normalizeArtifact,
+  normalizeDiagnostic,
+  normalizeDiagnostics,
+  sourceLoc,
+  stableFileName
+};

package/src/dispatch-table.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const DISPATCH_TABLE_VERSION = 'pulsewasm.dispatch-table.v1';
+const DISPATCH_POLICY = Object.freeze({
+  dispatchVersion: DISPATCH_TABLE_VERSION,
+  routeIdField: 'runtimeId',
+  routeIdShape: 'dense integer IDs assigned by flattened route order',
+  handlerSlotField: 'slot',
+  handlerSlotShape: 'dense integer slots assigned by deterministic handler table order',
+  routeLookup: 'method bucket -> compiled path pattern -> runtimeId',
+  executionModel: Object.freeze({
+    normal: 'ordered middleware slots followed by terminal route handler slot',
+    errors: 'ordered route error handler slots carried separately for runtime error unwinding',
+    lifecycle: 'connect/disconnect slots carried separately for websocket lifecycle dispatch',
+    channel: 'static channel literal or handler slot reference'
+  }),
+  codegen: 'metadata-only; Phase 6 does not emit AssemblyScript or Wasm code'
+});
+
+module.exports = {
+  DISPATCH_TABLE_VERSION,
+  DISPATCH_POLICY
+};

package/src/entities/catalog.d.ts

@@ -0,0 +1,7 @@
+declare const catalog: {
+  readonly ENTITIES_CATALOG_TARGETS: readonly ['fastly-javascript', 'fastly-native', 'node-javascript', 'node-native'];
+  normalizeEligibility(input?: Readonly<Record<string, boolean>>): Readonly<Record<string, boolean>>;
+  normalizeEntityCatalog(input: unknown): Readonly<Record<string, unknown>>;
+};
+
+export = catalog;

package/src/entities/catalog.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const { sha256Hex, stableStringify } = require('../stable-id.js');
+const {
+  ENTITIES_CATALOG_VERSION,
+  ENTITIES_CONTRACT_ID,
+  ENTITIES_DEFAULT_LIMITS,
+  ENTITIES_DIAGNOSTIC_CODES,
+  entitiesContractError,
+  normalizeDiscriminator,
+  normalizeSchemaId,
+  normalizeStaticMetadata,
+  utf8ByteLength
+} = require('./contracts.js');
+
+const ENTITIES_CATALOG_TARGETS = Object.freeze([
+  'fastly-javascript',
+  'fastly-native',
+  'node-javascript',
+  'node-native'
+]);
+
+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 compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function normalizeEligibility(input = {}) {
+  if (!plainObject(input)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Catalog eligibility must be an object.');
+  const unknown = Object.keys(input).filter((key) => !ENTITIES_CATALOG_TARGETS.includes(key)).sort();
+  if (unknown.length > 0) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Catalog eligibility contains unknown targets: ${unknown.join(', ')}.`);
+  return Object.freeze(Object.fromEntries(ENTITIES_CATALOG_TARGETS.map((target) => {
+    const value = input[target];
+    if (value !== undefined && typeof value !== 'boolean') throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Eligibility for ${target} must be boolean.`);
+    return [target, value === true];
+  })));
+}
+
+function normalizeEntityCatalog(input) {
+  if (!plainObject(input) || input.version !== ENTITIES_CATALOG_VERSION || input.contractId !== ENTITIES_CONTRACT_ID || !Array.isArray(input.routers)) {
+    throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Entity catalog requires ${ENTITIES_CATALOG_VERSION}.`);
+  }
+  const routerIds = new Set();
+  const routers = input.routers.map((router) => {
+    if (!plainObject(router)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Catalog router must be an object.');
+    const id = String(router.id || '');
+    if (!id || routerIds.has(id) || router.adapter !== 'json-rpc' || router.binding !== 'request' || !Array.isArray(router.entities)) {
+      throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, `Catalog router ${id || '<missing>'} is invalid.`);
+    }
+    routerIds.add(id);
+    if (router.entities.length > ENTITIES_DEFAULT_LIMITS.maxEntities) {
+      throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.LIMIT_EXCEEDED, `Catalog router ${id} exceeds its entity limit.`);
+    }
+    const names = new Set();
+    const entities = router.entities.map((entity) => {
+      if (!plainObject(entity)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Catalog entity must be an object.');
+      const name = normalizeDiscriminator(entity.name);
+      if (names.has(name)) throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.DISCRIMINATOR_DUPLICATE, `Catalog repeats entity ${name}.`);
+      names.add(name);
+      return Object.freeze({
+        name,
+        inputSchema: normalizeSchemaId(entity.inputSchema, 'catalog.inputSchema'),
+        outputSchema: normalizeSchemaId(entity.outputSchema, 'catalog.outputSchema'),
+        ...(entity.metadata === undefined ? {} : { metadata: normalizeStaticMetadata(entity.metadata) }),
+        eligibility: normalizeEligibility(entity.eligibility)
+      });
+    }).sort((left, right) => compareText(left.name, right.name));
+    const metadataBytes = entities.reduce((sum, entity) => sum + (entity.metadata ? utf8ByteLength(stableStringify(entity.metadata)) : 0), 0);
+    if (metadataBytes > ENTITIES_DEFAULT_LIMITS.maxMetadataBytesPerRouter) {
+      throw entitiesContractError(ENTITIES_DIAGNOSTIC_CODES.LIMIT_EXCEEDED, `Catalog router ${id} exceeds its metadata limit.`);
+    }
+    return Object.freeze({ id, adapter: 'json-rpc', binding: 'request', entities: Object.freeze(entities) });
+  }).sort((left, right) => compareText(left.id, right.id));
+  const normalized = Object.freeze({ version: ENTITIES_CATALOG_VERSION, contractId: ENTITIES_CONTRACT_ID, routers: Object.freeze(routers) });
+  return Object.freeze({ ...normalized, catalogHash: sha256Hex(stableStringify(normalized)) });
+}
+
+module.exports = Object.freeze({
+  ENTITIES_CATALOG_TARGETS,
+  normalizeEligibility,
+  normalizeEntityCatalog
+});

package/src/entities/contracts.d.ts

@@ -0,0 +1,95 @@
+declare interface EntitiesLimits {
+  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 interface NormalizedEntityDeclaration {
+  readonly input: string | null;
+  readonly output: string | null;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+declare interface NormalizedEntityAdapter {
+  readonly version: string;
+  readonly id: 'json-rpc';
+  readonly adapterVersion: string;
+  readonly options: Readonly<Record<string, unknown>>;
+  readonly limits: EntitiesLimits;
+}
+
+declare interface EntitiesContractError extends TypeError {
+  readonly code: string;
+  readonly detail: Readonly<Record<string, unknown>>;
+}
+
+declare const contracts: {
+  readonly ENTITIES_PACKAGE_VERSION: 'pulse.entities-package.v1';
+  readonly ENTITIES_CONTRACT_VERSION: 'pulse.entities-contract.v1';
+  readonly ENTITIES_ADAPTER_VERSION: 'pulse.entities-adapter.v1';
+  readonly ENTITIES_PLAN_VERSION: 'pulse.entities-lowering-plan.v1';
+  readonly ENTITIES_CATALOG_VERSION: 'pulse.entities-catalog.v1';
+  readonly ENTITIES_FAILURE_VERSION: 'pulse.entities-failure.v1';
+  readonly ENTITIES_DIAGNOSTIC_VERSION: 'pulse.entities-diagnostics.v1';
+  readonly ENTITIES_HANDLER_REFERENCE_VERSION: 'pulse.entities-handler-reference.v1';
+  readonly ENTITIES_REGISTRY_VERSION: 'pulse.entities-registry.v1';
+  readonly ENTITIES_JSON_RPC_ADAPTER_VERSION: 'pulse.entities-json-rpc-adapter.v1';
+  readonly ENTITIES_CONTRACT_ID: 'pulse.entities';
+  readonly ENTITIES_PACKAGE_NAME: '@pulse-compute/entities';
+  readonly ENTITIES_LOWERER_ID: 'pulse.entities.compiler-builder.v1';
+  readonly ENTITIES_LOWERER_EXPORT: 'createEntitiesPackageCompilerBuilder';
+  readonly ENTITIES_LOWERER_MANIFEST: './pulsewasm.manifest.cjs';
+  readonly ENTITIES_LOWERABLE_SUBPATH: '@pulse-compute/entities';
+  readonly ENTITIES_PACKAGE_INTRINSIC_VERSION: 'pulse.package-intrinsic.v1';
+  readonly ENTITIES_PUBLIC_SYMBOLS: readonly ['EntityRouter', 'jsonRpc'];
+  readonly ENTITIES_PACKAGE_INTRINSICS: Readonly<{
+    handle: Readonly<{
+      name: 'pulse.entities.handle.v1';
+      compilerName: '__pulse_entities_handle';
+      valueKind: 'response';
+      argumentIndexes: readonly [0];
+    }>;
+  }>;
+  readonly ENTITIES_JSON_RPC_OPTIONS: Readonly<{ namedParamsOnly: true; acceptEmptyObjectForNoInput: false }>;
+  readonly ENTITIES_DEFAULT_LIMITS: EntitiesLimits;
+  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>>): EntitiesContractError;
+  normalizeEntityLimits(input?: Readonly<Partial<EntitiesLimits>>): EntitiesLimits;
+  normalizeDiscriminator(value: unknown, limits?: EntitiesLimits): string;
+  normalizeSchemaId(value: unknown, field?: string): string | null;
+  normalizeStaticMetadata(value: unknown, limits?: EntitiesLimits): Readonly<Record<string, unknown>> | undefined;
+  normalizeEntityDeclaration(input: unknown, limits?: EntitiesLimits): NormalizedEntityDeclaration;
+  normalizeHandler<T extends Function>(handler: T): T;
+  normalizeHandlerReference(input: unknown): Readonly<Record<string, string>>;
+  normalizeJsonRpcAdapterOptions(input?: Readonly<{ namedParamsOnly?: true; acceptEmptyObjectForNoInput?: boolean }>): Readonly<{
+    namedParamsOnly: true;
+    acceptEmptyObjectForNoInput: boolean;
+  }>;
+  normalizeAdapter(input: unknown, limits?: EntitiesLimits): NormalizedEntityAdapter;
+  normalizeEntityRegistration(input: unknown, limits?: EntitiesLimits): Readonly<{
+    discriminator: string;
+    declaration: NormalizedEntityDeclaration;
+    handler: Function;
+  }>;
+  normalizeEntityRegistry(input: readonly unknown[], limits?: EntitiesLimits): Readonly<{
+    version: string;
+    entries: readonly unknown[];
+    registryHash: string;
+    limits: EntitiesLimits;
+  }>;
+  normalizeEntityFailure(input: unknown, limits?: EntitiesLimits): Readonly<Record<string, unknown>>;
+  normalizeEntityPlan(input: unknown): Readonly<Record<string, unknown>>;
+};
+
+export = contracts;