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

package/src/route-plan.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const ROUTE_PLAN_VERSION = 'pulsewasm.route-plan.v4';
+const ROUTE_STABLE_INPUT_VERSION = 'pulsewasm.route-stable-input.v2';
+
+const ROUTE_STABLE_ID_POLICY = Object.freeze({
+  algorithm: 'sha256',
+  prefix: 'route',
+  input: 'method + normalized path + params + handler IDs + inherited middleware/error/lifecycle handler IDs + channel identity',
+  version: ROUTE_STABLE_INPUT_VERSION
+});
+
+const ROUTE_RUNTIME_ID_POLICY = Object.freeze({
+  field: 'runtimeId',
+  dense: true,
+  startsAt: 0,
+  assignment: 'deterministic flattened route order'
+});
+
+const ROUTE_ID_COMPATIBILITY_POLICY = Object.freeze({
+  id: 'alias of runtimeId for Phase 1 compatibility'
+});
+
+const ROUTE_ID_POLICY = Object.freeze({
+  stable: ROUTE_STABLE_ID_POLICY,
+  runtime: ROUTE_RUNTIME_ID_POLICY,
+  compatibility: ROUTE_ID_COMPATIBILITY_POLICY
+});
+
+const ROUTE_PLAN_POLICY = Object.freeze({
+  version: ROUTE_PLAN_VERSION,
+  idPolicy: ROUTE_ID_POLICY
+});
+
+module.exports = {
+  ROUTE_PLAN_VERSION,
+  ROUTE_STABLE_INPUT_VERSION,
+  ROUTE_STABLE_ID_POLICY,
+  ROUTE_RUNTIME_ID_POLICY,
+  ROUTE_ID_COMPATIBILITY_POLICY,
+  ROUTE_ID_POLICY,
+  ROUTE_PLAN_POLICY
+};

package/src/schema-json/compile.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const SCHEMA_JSON_COMPILE_VERSION = 'pulsewasm.schema-json-compile.v1';
+const SCHEMA_JSON_COMPILE_SMOKE_VERSION = 'pulsewasm.schema-json-compile-smoke.v1';
+const SCHEMA_JSON_COMPILE_PHASE = '13';
+const PHASE = SCHEMA_JSON_COMPILE_PHASE;
+
+const MARKER_TYPES = new Map([
+  ['string', 'string'],
+  ['bool', 'bool'],
+  ['boolean', 'bool'],
+  ['i32', 'i32'],
+  ['u32', 'u32'],
+  ['Int32', 'i32'],
+  ['Uint32', 'u32'],
+  ['f64', 'f64'],
+  ['number', 'f64']
+]);
+const JSON_MARKER_MODULES = new Set([
+  '@pulse-compute/pulse/schema',
+  '@pulsewasm/json-types',
+  'pulsewasm/json-types'
+]);
+
+function plainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function jsonConfig(config) {
+  const runtime = plainObject(config && config.runtime);
+  const payload = plainObject(runtime.payload);
+  return plainObject(payload.json || (config && config.json));
+}
+
+function normalizeFieldType(type) {
+  const raw = String(type || '');
+  return MARKER_TYPES.get(raw) || raw;
+}
+
+function isJsonMarkerModule(moduleName) {
+  return JSON_MARKER_MODULES.has(String(moduleName || ''));
+}
+
+function compileNeeded(config) {
+  const json = jsonConfig(config);
+  const schemas = Array.isArray(json.schemas) ? json.schemas : [];
+  const target = json.target || 'generic';
+  const effectiveTarget = target === 'auto' && schemas.length > 0 ? 'schema' : target;
+  if (effectiveTarget !== 'schema') return false;
+  return schemas.some((schema) => Object.keys(plainObject(schema.fields)).length === 0 && typeof schema.source === 'string' && schema.source && typeof schema.type === 'string' && schema.type);
+}
+
+module.exports = {
+  SCHEMA_JSON_COMPILE_VERSION,
+  SCHEMA_JSON_COMPILE_SMOKE_VERSION,
+  SCHEMA_JSON_COMPILE_PHASE,
+  PHASE,
+  MARKER_TYPES,
+  JSON_MARKER_MODULES,
+  normalizeFieldType,
+  isJsonMarkerModule,
+  compileNeeded
+};

package/src/schema-json/contracts.js

@@ -0,0 +1,10 @@
+'use strict';
+
+module.exports = {
+  v1: require('./v1.js'),
+  v2: require('./v2.js'),
+  compile: require('./compile.js'),
+  genericParser: require('./generic-parser.js'),
+  registry: require('./registry.js'),
+  semanticTrace: require('./semantic-trace.js')
+};

package/src/schema-json/generic-parser.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const SCHEMA_JSON_GENERIC_PARSER_VERSION = 'pulsewasm.schema-json-generic-parser.v1';
+const SCHEMA_JSON_GENERIC_PARSER_PLAN_VERSION = 'pulsewasm.schema-json-generic-parser-plan.v1';
+const SCHEMA_JSON_GENERIC_PARSER_ABI_VERSION = 'pulsewasm.schema-json-generic-parser-abi.v1';
+const SCHEMA_JSON_GENERIC_PARSER_SMOKE_VERSION = 'pulsewasm.schema-json-generic-parser-smoke.v1';
+const SCHEMA_JSON_GENERIC_PARSER_PHASE = '34';
+const PHASE = SCHEMA_JSON_GENERIC_PARSER_PHASE;
+
+const SCHEMA_JSON_GENERIC_PARSER_ARTIFACT = 'schema-json-generic-parser.json';
+const SCHEMA_JSON_GENERIC_PARSER_PLAN_ARTIFACT = 'schema-json-generic-parser-plan.json';
+const SCHEMA_JSON_GENERIC_PARSER_ABI_ARTIFACT = 'schema-json-generic-parser-abi.json';
+const SCHEMA_JSON_GENERIC_PARSER_SMOKE_ARTIFACT = 'schema-json-generic-parser-smoke.json';
+const SCHEMA_JSON_GENERIC_PARSER_NAME = 'as-json';
+const SCHEMA_JSON_GENERIC_PARSER_ID = SCHEMA_JSON_GENERIC_PARSER_NAME;
+const SCHEMA_JSON_GENERIC_PARSER_MODE = 'generic-as-json-parser';
+const SCHEMA_JSON_GENERIC_PARSER_FILE = 'generated/as/schema-json/generic/as-json-parser.as.ts';
+const SCHEMA_JSON_GENERIC_PARSER_MODULE_FILE = SCHEMA_JSON_GENERIC_PARSER_FILE;
+const SCHEMA_JSON_GENERIC_PARSER_SMOKE_RUNNER_FILE = 'generated/as-smoke/schema-json-generic-parser-smoke-runner.as.ts';
+const SCHEMA_JSON_GENERIC_PARSER_WASM_FILE = 'generated/schema-json-generic-parser/pulsewasm-schema-json-generic-parser.wasm';
+const SCHEMA_JSON_GENERIC_PARSER_WAT_FILE = 'generated/schema-json-generic-parser/pulsewasm-schema-json-generic-parser.wat';
+const SCHEMA_JSON_GENERIC_PARSER_WASM = SCHEMA_JSON_GENERIC_PARSER_WASM_FILE;
+const SCHEMA_JSON_GENERIC_PARSER_WAT = SCHEMA_JSON_GENERIC_PARSER_WAT_FILE;
+const SCHEMA_JSON_GENERIC_PARSER_DOC_FILE = 'generated/host/schema-json-generic-parser.md';
+
+const SCHEMA_JSON_TARGETS = Object.freeze(['generic', 'schema', 'auto', 'parser', 'none']);
+const SCHEMA_JSON_GENERIC_PARSER_TARGETS = Object.freeze(['auto', 'parser']);
+const SCHEMA_JSON_PARSER_MODES = Object.freeze([SCHEMA_JSON_GENERIC_PARSER_NAME]);
+const SCHEMA_JSON_GENERIC_VALUE_KINDS = Object.freeze({ null: 0, bool: 1, number: 2, string: 3, array: 4, object: 5, error: -1 });
+const SCHEMA_JSON_GENERIC_PARSER_ACCESSORS = Object.freeze(['parse', 'ok', 'value', 'error', 'errorCode', 'errorMessage', 'errorStatusCode', 'kind', 'isNull', 'asBool', 'asF64', 'asString', 'objectGet', 'objectHas', 'has', 'get', 'getString', 'getI32', 'getU32', 'getF64', 'getBool', 'arrayLen', 'arrayGet', 'length', 'at', 'text']);
+const SCHEMA_JSON_GENERIC_ACCESSOR_SURFACE = SCHEMA_JSON_GENERIC_PARSER_ACCESSORS;
+const SCHEMA_JSON_GENERIC_RESERVED_SURFACE = Object.freeze(['automatic typed schema inference from generic refs', 'arbitrary JavaScript object materialization', 'host JSON.parse fallback', 'binary request body parsing', 'streaming request body parsing', 'mutation APIs for parsed generic refs']);
+const SCHEMA_JSON_GENERIC_PARSER_POLICY = Object.freeze({ phase: SCHEMA_JSON_GENERIC_PARSER_PHASE, parser: SCHEMA_JSON_GENERIC_PARSER_NAME, explicitOptIn: true, schemaDeclarationsPreferred: true, schemaAutoTakesPrecedence: true, directJsObjects: false, hostJsonParse: false, assemblyScriptParser: true, fullJsonTree: true, valueAccess: 'opaque-ref-accessors', bodySource: 'seeded-body-text-only', supportedTargets: SCHEMA_JSON_GENERIC_PARSER_TARGETS, supportedValueKinds: Object.keys(SCHEMA_JSON_GENERIC_VALUE_KINDS).filter((kind) => kind !== 'error'), reservedSurface: SCHEMA_JSON_GENERIC_RESERVED_SURFACE });
+const SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS = Object.freeze({ parserRequired: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_REQUIRED', genericParserRequired: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_REQUIRED', unsupportedParser: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_UNSUPPORTED', genericParserUnsupported: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_UNSUPPORTED', genericParserInactive: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_INACTIVE', schemasTakePrecedence: 'PULSEWASM_SCHEMA_JSON_SCHEMAS_TAKE_PRECEDENCE', schemasIgnored: 'PULSEWASM_SCHEMA_JSON_GENERIC_SCHEMAS_IGNORED', schemaTargetRequiresSchemas: 'PULSEWASM_SCHEMA_JSON_SCHEMAS_REQUIRED', compileFailed: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_COMPILE_FAILED', genericParserCompileFailed: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_COMPILE_FAILED', smokeFailed: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_SMOKE_FAILED', genericParserSmokeFailed: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_SMOKE_FAILED', ascMissing: 'PULSEWASM_SCHEMA_JSON_GENERIC_PARSER_ASC_MISSING' });
+
+function plainObject(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
+function configArtifact(config) { return config && typeof config === 'object' && config.artifact ? config.artifact : config; }
+function jsonConfig(config) { const root = plainObject(configArtifact(config)); const runtime = plainObject(root.runtime); const payload = plainObject(runtime.payload); return plainObject(payload.json || root.json); }
+function schemas(config) { const json = jsonConfig(config); return Array.isArray(json.schemas) ? json.schemas : []; }
+function normalizeSchemaJsonTarget(value) { if (typeof value !== 'string' || !value) return 'generic'; if (value === 'fallback') return 'auto'; if (value === 'generic-parser') return 'parser'; return value; }
+function normalizeJsonTarget(config) { return normalizeSchemaJsonTarget(jsonConfig(config).target); }
+function normalizeParserMode(value) { if (typeof value === 'string' && value) return value; if (value && typeof value === 'object' && !Array.isArray(value)) return String(value.id || value.mode || value.kind || value.name || ''); return ''; }
+function normalizeSchemaJsonParser(value) { const normalized = String(normalizeParserMode(value) || '').toLowerCase(); if (!normalized) return undefined; if (normalized === 'assemblyscript-json' || normalized === 'full-as-json' || normalized === 'asjson' || normalized === 'generic-as-json') return SCHEMA_JSON_GENERIC_PARSER_ID; return normalized; }
+function normalizedParserId(config) { return normalizeSchemaJsonParser(jsonConfig(config).parser); }
+function normalizeJsonParserConfig(config = {}) {
+  const target = normalizeJsonTarget(config); const parser = normalizedParserId(config); const schemaList = schemas(config); const diagnostics = []; const warnings = []; let effectiveTarget = target; let genericParser = false; let schemaSidecar = false; let mode = 'inactive';
+  if (!SCHEMA_JSON_TARGETS.includes(target)) { diagnostics.push('PULSEWASM_SCHEMA_JSON_GENERIC_TARGET_UNSUPPORTED'); mode = 'error'; }
+  else if (target === 'schema') { effectiveTarget = 'schema'; schemaSidecar = true; mode = 'schema'; if (schemaList.length === 0) diagnostics.push(SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS.schemaTargetRequiresSchemas); }
+  else if (target === 'auto') { if (schemaList.length > 0) { effectiveTarget = 'schema'; schemaSidecar = true; mode = 'schema'; if (parser === SCHEMA_JSON_GENERIC_PARSER_ID) warnings.push(SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS.schemasTakePrecedence); } else if (parser === SCHEMA_JSON_GENERIC_PARSER_ID) { effectiveTarget = 'parser'; genericParser = true; mode = SCHEMA_JSON_GENERIC_PARSER_MODE; } else if (parser) { effectiveTarget = 'parser'; diagnostics.push(SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS.unsupportedParser); mode = 'error'; } else { effectiveTarget = 'parser'; diagnostics.push(SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS.parserRequired); mode = 'error'; } }
+  else if (target === 'parser') { effectiveTarget = 'parser'; const selectedParser = parser || SCHEMA_JSON_GENERIC_PARSER_ID; if (selectedParser === SCHEMA_JSON_GENERIC_PARSER_ID) { genericParser = true; mode = SCHEMA_JSON_GENERIC_PARSER_MODE; if (schemaList.length > 0) warnings.push(SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS.schemasIgnored); } else { diagnostics.push(SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS.unsupportedParser); mode = 'error'; } }
+  return { target, effectiveTarget, parser: target === 'parser' && !parser ? SCHEMA_JSON_GENERIC_PARSER_ID : parser, schemaCount: schemaList.length, schemasPresent: schemaList.length > 0, genericParser, schemaSidecar, mode, diagnostics, warnings, parserUnsupportedDiagnostic: diagnostics.includes(SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS.unsupportedParser), parserRequiredDiagnostic: diagnostics.includes(SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS.parserRequired), schemaSidecarRequested: schemaSidecar, genericParserRequested: genericParser };
+}
+function normalizeGenericParserConfig(config = {}) { const json = jsonConfig(config); const mode = normalizeJsonParserConfig(config); const schemaList = schemas(config); return { ...mode, schemas: schemaList, schemasSupplied: schemaList.length > 0, contentTypePolicy: typeof json.contentTypePolicy === 'string' && json.contentTypePolicy ? json.contentTypePolicy : 'accept-json-or-missing', defaultNamespace: typeof json.defaultNamespace === 'string' && json.defaultNamespace ? json.defaultNamespace : 'app', maxBytes: Number.isFinite(Number(json.maxBytes)) ? Number(json.maxBytes) : 1048576 }; }
+function normalizeSchemaJsonParserMode(config = {}) { return normalizeJsonParserConfig(config); }
+function normalizeSchemaJsonParserSelection(config = {}) { const mode = normalizeJsonParserConfig(config); return { target: mode.target, effectiveTarget: mode.effectiveTarget, effectiveParser: mode.parser, parserRequested: mode.genericParser, explicitParser: Boolean(mode.parser), schemasSupplied: mode.schemasPresent, schemaCount: mode.schemaCount, schemaSidecarsPreferred: mode.schemaSidecar, mode: mode.mode, diagnostics: mode.diagnostics, warnings: mode.warnings }; }
+function genericParserNeeded(config = {}) { const selection = normalizeJsonParserConfig(config); if (selection.genericParser) return true; if ((selection.target === 'auto' || selection.target === 'parser') && !selection.schemaSidecar && selection.diagnostics.length > 0) return true; return false; }
+function shouldUseGenericSchemaJsonParser(config = {}) { return genericParserNeeded(config); }
+function shouldUseSchemaJsonGenericParser(config = {}, options = {}) { return Boolean(options && options.forceGenericParser) || genericParserNeeded(config); }
+function shouldUseSchemaJsonSchemaMode(config = {}) { return normalizeJsonParserConfig(config).schemaSidecar; }
+function defaultSchemaJsonGenericParserPolicy() { return { ...SCHEMA_JSON_GENERIC_PARSER_POLICY, accessorSurface: SCHEMA_JSON_GENERIC_PARSER_ACCESSORS.slice(), diagnostics: { ...SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS } }; }
+
+module.exports = { SCHEMA_JSON_GENERIC_PARSER_VERSION, SCHEMA_JSON_GENERIC_PARSER_PLAN_VERSION, SCHEMA_JSON_GENERIC_PARSER_ABI_VERSION, SCHEMA_JSON_GENERIC_PARSER_SMOKE_VERSION, SCHEMA_JSON_GENERIC_PARSER_PHASE, PHASE, SCHEMA_JSON_GENERIC_PARSER_ARTIFACT, SCHEMA_JSON_GENERIC_PARSER_PLAN_ARTIFACT, SCHEMA_JSON_GENERIC_PARSER_ABI_ARTIFACT, SCHEMA_JSON_GENERIC_PARSER_SMOKE_ARTIFACT, SCHEMA_JSON_GENERIC_PARSER_NAME, SCHEMA_JSON_GENERIC_PARSER_ID, SCHEMA_JSON_GENERIC_PARSER_MODE, SCHEMA_JSON_GENERIC_PARSER_FILE, SCHEMA_JSON_GENERIC_PARSER_MODULE_FILE, SCHEMA_JSON_GENERIC_PARSER_SMOKE_RUNNER_FILE, SCHEMA_JSON_GENERIC_PARSER_WASM_FILE, SCHEMA_JSON_GENERIC_PARSER_WAT_FILE, SCHEMA_JSON_GENERIC_PARSER_WASM, SCHEMA_JSON_GENERIC_PARSER_WAT, SCHEMA_JSON_GENERIC_PARSER_DOC_FILE, SCHEMA_JSON_TARGETS, SCHEMA_JSON_GENERIC_PARSER_TARGETS, SCHEMA_JSON_PARSER_MODES, SCHEMA_JSON_GENERIC_VALUE_KINDS, SCHEMA_JSON_GENERIC_PARSER_ACCESSORS, SCHEMA_JSON_GENERIC_ACCESSOR_SURFACE, SCHEMA_JSON_GENERIC_RESERVED_SURFACE, SCHEMA_JSON_GENERIC_PARSER_POLICY, SCHEMA_JSON_GENERIC_PARSER_DIAGNOSTICS, configArtifact, jsonConfig, schemas, normalizeSchemaJsonTarget, normalizeJsonTarget, normalizeParserMode, normalizeSchemaJsonParser, normalizedParserId, normalizeJsonParserConfig, normalizeGenericParserConfig, normalizeSchemaJsonParserMode, normalizeSchemaJsonParserSelection, genericParserNeeded, shouldUseGenericSchemaJsonParser, shouldUseSchemaJsonGenericParser, shouldUseSchemaJsonSchemaMode, defaultSchemaJsonGenericParserPolicy };

package/src/schema-json/registry.js

@@ -0,0 +1,359 @@
+'use strict';
+
+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_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;
+const SCALAR_KINDS = Object.freeze(['string', 'boolean', 'i32', 'u32', 'f64']);
+const NODE_KINDS = Object.freeze([...SCALAR_KINDS, 'object', 'array', 'string-enum', 'nullable']);
+
+function schemaContractError(code, message, details = {}) {
+  const error = new TypeError(message);
+  error.code = code;
+  error.details = Object.freeze({ ...details });
+  return error;
+}
+
+function plainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+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 requiredString(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw schemaContractError('PULSE_SCHEMA_IR_STRING_REQUIRED', `${field} must be a non-empty string.`, { field, value });
+  }
+  return value.trim();
+}
+
+function normalizeSource(input, field) {
+  if (!plainObject(input)) {
+    throw schemaContractError('PULSE_SCHEMA_IR_SOURCE_REQUIRED', `${field} must identify a source location.`, { field });
+  }
+  const line = Number(input.line);
+  const column = Number(input.column);
+  if (!Number.isSafeInteger(line) || line < 1 || !Number.isSafeInteger(column) || column < 1) {
+    throw schemaContractError('PULSE_SCHEMA_IR_SOURCE_INVALID', `${field} requires positive line and column values.`, {
+      field,
+      line,
+      column
+    });
+  }
+  return Object.freeze({
+    file: requiredString(input.file, `${field}.file`).replace(/\\/g, '/'),
+    line,
+    column
+  });
+}
+
+function normalizeId(value, field, pattern, code) {
+  const id = requiredString(value, field);
+  if (!pattern.test(id)) {
+    throw schemaContractError(code, `${field} must be a stable dotted identifier.`, { field, id });
+  }
+  return id;
+}
+
+function normalizeSchemaNode(input, field = 'schema.root', stack = []) {
+  if (!plainObject(input)) {
+    throw schemaContractError('PULSE_SCHEMA_IR_NODE_REQUIRED', `${field} must be a normalized schema node.`, { field });
+  }
+  const kind = requiredString(input.kind, `${field}.kind`);
+  if (!NODE_KINDS.includes(kind)) {
+    throw schemaContractError('PULSE_SCHEMA_IR_NODE_KIND_UNSUPPORTED', `${field}.kind is unsupported: ${kind}.`, { field, kind });
+  }
+  if (SCALAR_KINDS.includes(kind)) return Object.freeze({ kind });
+  if (kind === 'array') {
+    return Object.freeze({ kind, element: normalizeSchemaNode(input.element, `${field}.element`, stack) });
+  }
+  if (kind === 'nullable') {
+    const value = normalizeSchemaNode(input.value, `${field}.value`, stack);
+    if (value.kind === 'nullable') {
+      throw schemaContractError('PULSE_SCHEMA_IR_REDUNDANT_NULLABLE', `${field} cannot contain another nullable node.`, { field });
+    }
+    return Object.freeze({ kind, value });
+  }
+  if (kind === 'string-enum') {
+    if (!Array.isArray(input.values) || input.values.length === 0) {
+      throw schemaContractError('PULSE_SCHEMA_IR_ENUM_VALUES_REQUIRED', `${field}.values must contain at least one string literal.`, { field });
+    }
+    const values = input.values.map((value, index) => requiredString(value, `${field}.values[${index}]`));
+    if (new Set(values).size !== values.length) {
+      throw schemaContractError('PULSE_SCHEMA_IR_ENUM_VALUE_DUPLICATE', `${field}.values must be unique.`, { field, values });
+    }
+    return Object.freeze({ kind, values: Object.freeze(values) });
+  }
+  if (!Array.isArray(input.fields)) {
+    throw schemaContractError('PULSE_SCHEMA_IR_OBJECT_FIELDS_REQUIRED', `${field}.fields must be an array.`, { field });
+  }
+  const names = new Set();
+  const fields = input.fields.map((entry, index) => {
+    if (!plainObject(entry)) {
+      throw schemaContractError('PULSE_SCHEMA_IR_FIELD_REQUIRED', `${field}.fields[${index}] must be an object.`, { field, index });
+    }
+    const name = requiredString(entry.name, `${field}.fields[${index}].name`);
+    if (names.has(name)) {
+      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.`, {
+        field,
+        name
+      });
+    }
+    return Object.freeze({
+      name,
+      required: true,
+      value: normalizeSchemaNode(entry.value, `${field}.fields[${index}].value`, [...stack, name]),
+      source: entry.source ? normalizeSource(entry.source, `${field}.fields[${index}].source`) : undefined
+    });
+  });
+  return Object.freeze({ kind, fields: Object.freeze(fields) });
+}
+
+function normalizeSchema(input, index) {
+  if (!plainObject(input)) {
+    throw schemaContractError('PULSE_SCHEMA_IR_SCHEMA_REQUIRED', `schemas[${index}] must be an object.`, { index });
+  }
+  const id = normalizeId(input.id, `schemas[${index}].id`, SCHEMA_ID_PATTERN, 'PULSE_SCHEMA_ID_INVALID');
+  const root = normalizeSchemaNode(input.root, `schemas[${index}].root`);
+  if (root.kind !== 'object') {
+    throw schemaContractError('PULSE_SCHEMA_ROOT_OBJECT_REQUIRED', `Schema ${id} must have an object root.`, { id, kind: root.kind });
+  }
+  return Object.freeze({
+    id,
+    typeName: requiredString(input.typeName, `schemas[${index}].typeName`),
+    root,
+    source: normalizeSource(input.source, `schemas[${index}].source`)
+  });
+}
+
+function normalizeResponseCase(input, index) {
+  if (!plainObject(input)) {
+    throw schemaContractError('PULSE_RESPONSE_CASE_REQUIRED', `responses[${index}] must be an object.`, { index });
+  }
+  const status = Number(input.status);
+  if (!Number.isSafeInteger(status) || status < 100 || status > 599) {
+    throw schemaContractError('PULSE_RESPONSE_STATUS_INVALID', `responses[${index}].status must be an integer from 100 through 599.`, {
+      index,
+      status
+    });
+  }
+  return Object.freeze({
+    id: normalizeId(input.id, `responses[${index}].id`, RESPONSE_CASE_ID_PATTERN, 'PULSE_RESPONSE_CASE_ID_INVALID'),
+    status,
+    schemaId: normalizeId(input.schemaId, `responses[${index}].schemaId`, SCHEMA_ID_PATTERN, 'PULSE_SCHEMA_ID_INVALID'),
+    source: normalizeSource(input.source, `responses[${index}].source`)
+  });
+}
+
+function assertUnique(entries, field, code) {
+  const seen = new Set();
+  for (const entry of entries) {
+    if (seen.has(entry.id)) {
+      throw schemaContractError(code, `${field} contains duplicate ID ${entry.id}.`, { field, id: entry.id });
+    }
+    seen.add(entry.id);
+  }
+}
+
+function normalizeSchemaRegistry(input) {
+  if (!plainObject(input)) {
+    throw schemaContractError('PULSE_SCHEMA_REGISTRY_REQUIRED', 'Schema registry IR must be an object.');
+  }
+  const schemas = Object.freeze((input.schemas || []).map(normalizeSchema));
+  const responses = Object.freeze((input.responses || []).map(normalizeResponseCase));
+  assertUnique(schemas, 'schemas', 'PULSE_SCHEMA_ID_DUPLICATE');
+  assertUnique(responses, 'responses', 'PULSE_RESPONSE_CASE_ID_DUPLICATE');
+  const schemaIds = new Set(schemas.map((entry) => entry.id));
+  for (const entry of responses) {
+    if (!schemaIds.has(entry.schemaId)) {
+      throw schemaContractError(
+        'PULSE_RESPONSE_SCHEMA_UNKNOWN',
+        `Response case ${entry.id} references unknown schema ${entry.schemaId}.`,
+        { responseCaseId: entry.id, schemaId: entry.schemaId }
+      );
+    }
+  }
+  const semantic = {
+    version: SCHEMA_REGISTRY_IR_VERSION,
+    source: normalizeSource(input.source, 'source'),
+    schemas,
+    responses,
+    policies: deepFreeze({
+      objectRoots: true,
+      requiredFieldsOnly: true,
+      unknownInputFields: 'drop',
+      outputFields: 'declared-only',
+      outputFieldOrder: 'declaration',
+      numericPolicy: 'finite-rfc-json',
+      parity: 'semantic',
+      dynamicIds: false,
+      schemaTrialFallback: false,
+      publicDecorators: false
+    })
+  };
+  return deepFreeze({
+    ...semantic,
+    registryHash: sha256Hex(stableStringify(semantic))
+  });
+}
+
+function assemblyScriptType(node, symbols, pathParts) {
+  switch (node.kind) {
+    case 'string': return 'string';
+    case 'boolean': return 'bool';
+    case 'i32': return 'i32';
+    case 'u32': return 'u32';
+    case 'f64': return 'f64';
+    case 'string-enum': return 'string';
+    case 'array': return `Array<${assemblyScriptType(node.element, symbols, [...pathParts, 'item'])}>`;
+    case 'nullable': return `${assemblyScriptType(node.value, symbols, [...pathParts, 'value'])} | null`;
+    case 'object': {
+      const key = pathParts.join('.');
+      return symbols.get(key);
+    }
+    default: throw schemaContractError('PULSE_SCHEMA_IR_NODE_KIND_UNSUPPORTED', `Unsupported schema node kind ${node.kind}.`);
+  }
+}
+
+function identifier(value) {
+  const normalized = String(value).normalize('NFKC').replace(/[^A-Za-z0-9_$]+/g, '_');
+  return /^[A-Za-z_$]/.test(normalized) ? normalized : `_${normalized}`;
+}
+
+function collectNativeClasses(schema, node, symbols, classes, pathParts = []) {
+  if (node.kind === 'nullable') return collectNativeClasses(schema, node.value, symbols, classes, [...pathParts, 'value']);
+  if (node.kind === 'array') return collectNativeClasses(schema, node.element, symbols, classes, [...pathParts, 'item']);
+  if (node.kind !== 'object') return;
+  const key = pathParts.join('.');
+  const symbol = `__Pulse_${identifier(schema.id)}${pathParts.length === 0 ? '' : `_${pathParts.map(identifier).join('_')}`}`;
+  symbols.set(key, symbol);
+  for (const field of node.fields) collectNativeClasses(schema, field.value, symbols, classes, [...pathParts, field.name]);
+  classes.push(Object.freeze({
+    symbol,
+    schemaId: schema.id,
+    path: pathParts.length === 0 ? '' : `/${pathParts.map((part) => String(part).replace(/~/g, '~0').replace(/\//g, '~1')).join('/')}`,
+    fields: Object.freeze(node.fields.map((field) => Object.freeze({
+      name: field.name,
+      type: assemblyScriptType(field.value, symbols, [...pathParts, field.name]),
+      required: true,
+      constraints: field.value.kind === 'string-enum'
+        ? Object.freeze({ enum: field.value.values })
+        : Object.freeze({})
+    })))
+  }));
+}
+
+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);
+    return Object.freeze({
+      id: schema.id,
+      rootClass: symbols.get(''),
+      classes: Object.freeze(schemaClasses),
+      parse: `JSON.parse<${symbols.get('')}>`,
+      stringify: `JSON.stringify<${symbols.get('')}>`
+    });
+  });
+  return deepFreeze({
+    version: SCHEMA_CODEC_INPUTS_VERSION,
+    registryVersion: registry.version,
+    registryHash: registry.registryHash,
+    javascript: {
+      backend: 'pulse-generated',
+      operation: 'direct-parse-or-serialize',
+      schemas: registry.schemas,
+      policies: registry.policies
+    },
+    native: {
+      backend: 'json-as',
+      package: 'json-as',
+      packageVersion: '1.5.0',
+      transform: 'json-as',
+      assemblyScriptVersion: '0.28.18',
+      generatedOnly: true,
+      publicDecorators: false,
+      schemas: Object.freeze(nativeSchemas)
+    },
+    responses: registry.responses
+  });
+}
+
+function defaultSchemaBoundaryPolicy() {
+  return deepFreeze({
+    strict: {
+      missingSchemaId: 'diagnostic',
+      knownSchemaId: 'schema-codec',
+      unknownSchemaId: 'diagnostic'
+    },
+    nonStrict: {
+      missingSchemaId: 'generic-json',
+      knownSchemaId: 'schema-codec',
+      unknownSchemaId: 'diagnostic'
+    },
+    suppliedIds: 'string-literal-only',
+    genericJsonFallbackForUnknownId: false,
+    schemaTrialFallback: false,
+    jsonBodyOwnership: 'pulse-semantic-encoding',
+    bodyOwnership: 'caller-exact-payload',
+    bodyAndJsonMutuallyExclusive: true
+  });
+}
+
+function defaultSchemaRegistryContract() {
+  return deepFreeze({
+    authoringVersion: SCHEMA_AUTHORING_VERSION,
+    registryVersion: SCHEMA_REGISTRY_IR_VERSION,
+    codecInputsVersion: SCHEMA_CODEC_INPUTS_VERSION,
+    schemaIdPattern: SCHEMA_ID_PATTERN.source,
+    responseCaseIdPattern: RESPONSE_CASE_ID_PATTERN.source,
+    scalarKinds: SCALAR_KINDS,
+    nodeKinds: NODE_KINDS,
+    helpers: ['defineSchemaRegistry', 'schema', 'response'],
+    markerTypes: ['Int32', 'Uint32'],
+    policies: {
+      canonicalEntrypoint: 'pulse.schema',
+      defaultExportRequired: true,
+      staticObjectLiteralsOnly: true,
+      stableStringIds: true,
+      exactLiteralIdsAtBoundaries: true,
+      oldSchemasJsonSupported: false,
+      optionalPropertiesSupported: false,
+      recursiveSchemasSupported: false,
+      publicJsonAsImportsSupported: false,
+      automaticFallback: false
+    },
+    boundaryPolicy: defaultSchemaBoundaryPolicy()
+  });
+}
+
+module.exports = Object.freeze({
+  SCHEMA_REGISTRY_IR_VERSION,
+  SCHEMA_CODEC_INPUTS_VERSION,
+  SCHEMA_AUTHORING_VERSION,
+  SCHEMA_ID_PATTERN,
+  RESPONSE_CASE_ID_PATTERN,
+  SCALAR_KINDS,
+  NODE_KINDS,
+  schemaContractError,
+  normalizeSchemaNode,
+  normalizeSchemaRegistry,
+  codecInputsForRegistry,
+  defaultSchemaBoundaryPolicy,
+  defaultSchemaRegistryContract
+});