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

package/src/compiler/schema-json-compile.js

@@ -0,0 +1,575 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const ts = require('typescript');
+const { PACKAGE_VERSION, diagnostic, normalizeArtifact, normalizeDiagnostic, stableFileName } = loadContractsDiagnostics();
+const {
+  SCHEMA_JSON_COMPILE_VERSION,
+  SCHEMA_JSON_COMPILE_SMOKE_VERSION,
+  PHASE,
+  MARKER_TYPES,
+  JSON_MARKER_MODULES,
+  normalizeFieldType,
+  compileNeeded
+} = loadContractsSchemaJsonCompile();
+
+
+function loadContractsDiagnostics() {
+  try {
+    return require('@pulse-compute/wasm-contracts/diagnostics');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/diagnostics.js');
+    }
+    throw error;
+  }
+}
+
+function loadContractsSchemaJsonCompile() {
+  try {
+    return require('@pulse-compute/wasm-contracts/schema-json/compile');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../contracts/src/schema-json/compile.js');
+    }
+    throw error;
+  }
+}
+
+function stableSlash(value) { return String(value || '').replace(/\\/g, '/'); }
+function plainObject(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
+function resolveSchemaSource(cwd, configFile, sourceRef) {
+  if (!sourceRef || typeof sourceRef !== 'string') return undefined;
+  const candidates = [];
+  candidates.push(path.resolve(cwd, sourceRef));
+  if (configFile) candidates.push(path.resolve(path.dirname(configFile), sourceRef));
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+  }
+  return candidates[0];
+}
+function jsonConfig(config) {
+  const runtime = plainObject(config.runtime);
+  const payload = plainObject(runtime.payload);
+  return plainObject(payload.json || config.json);
+}
+function configArtifact(options = {}) { return options.resolvedConfig?.artifact || options.resolvedConfig || {}; }
+function explicitFields(schema) {
+  const out = [];
+  const rawFields = plainObject(schema.fields);
+  for (const [name, type] of Object.entries(rawFields)) out.push({ name, type: normalizeFieldType(type) });
+  return out;
+}
+function makeDiag(code, message, hint, file, details) {
+  return normalizeDiagnostic({
+    code,
+    severity: 'error',
+    message,
+    hint,
+    phase: 'schema-json-compile',
+    pass: 'schema-json-compile',
+    loc: { file: file || '<config>' },
+    details
+  });
+}
+function makeWarn(code, message, hint, file, details) {
+  return normalizeDiagnostic({
+    code,
+    severity: 'warning',
+    message,
+    hint,
+    phase: 'schema-json-compile',
+    pass: 'schema-json-compile',
+    loc: { file: file || '<config>' },
+    details
+  });
+}
+function buildMarkdown(artifact) {
+  const lines = [];
+  lines.push('# PulseWasm Phase 13 — Schema JSON Compile Stream');
+  lines.push('');
+  lines.push(`Generated by: \`${artifact.generatedBy}\``);
+  lines.push('');
+  lines.push('## Purpose');
+  lines.push('');
+  lines.push('- lower flat required TypeScript payload types into explicit schema JSON declarations');
+  lines.push('- reuse the existing schema sidecar backend rather than introduce a new parser runtime');
+  lines.push('- keep v1 semantics narrow: string, bool, i32, u32, f64 only');
+  lines.push('');
+  lines.push('## Schemas');
+  lines.push('');
+  if (!artifact.schemas.length) lines.push('- none');
+  for (const schema of artifact.schemas) {
+    lines.push(`- \`${schema.id}\` mode \`${schema.mode}\` (${schema.fields.length} fields)`);
+  }
+  lines.push('');
+  lines.push('## Summary');
+  lines.push('');
+  for (const [key, value] of Object.entries(artifact.summary || {})) lines.push(`- ${key}: \`${value}\``);
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+class TypeGraph {
+  constructor(cwd, diagnostics) {
+    this.cwd = cwd;
+    this.diagnostics = diagnostics;
+    this.files = new Map();
+  }
+
+  loadFile(filePath) {
+    const absolute = path.resolve(filePath);
+    if (this.files.has(absolute)) return this.files.get(absolute);
+    if (!fs.existsSync(absolute)) {
+      this.diagnostics.push(makeDiag(
+        'PULSEWASM_SCHEMA_JSON_COMPILE_SOURCE_NOT_FOUND',
+        `Type source file ${JSON.stringify(stableFileName(absolute, this.cwd))} was not found.`,
+        'Check the schema source path and any relative type-only import paths.',
+        stableFileName(absolute, this.cwd)
+      ));
+      return undefined;
+    }
+    const text = fs.readFileSync(absolute, 'utf8');
+    const sourceFile = ts.createSourceFile(absolute, text, ts.ScriptTarget.Latest, true, absolute.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const record = {
+      file: absolute,
+      text,
+      sourceFile,
+      declarations: new Map(),
+      exportedDeclarations: new Map(),
+      imports: new Map()
+    };
+    this.files.set(absolute, record);
+
+    for (const parseDiag of sourceFile.parseDiagnostics || []) {
+      const start = typeof parseDiag.start === 'number' ? parseDiag.start : 0;
+      const lc = sourceFile.getLineAndCharacterOfPosition(start);
+      this.diagnostics.push(normalizeDiagnostic({
+        code: 'PULSEWASM_SCHEMA_JSON_COMPILE_PARSE_ERROR',
+        severity: 'error',
+        message: String(ts.flattenDiagnosticMessageText(parseDiag.messageText, '\n')),
+        phase: 'schema-json-compile',
+        pass: 'schema-json-compile',
+        loc: { file: stableFileName(absolute, this.cwd), start: { line: lc.line + 1, column: lc.character + 1, offset: start } }
+      }));
+    }
+
+    for (const statement of sourceFile.statements) {
+      if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) {
+        const name = statement.name?.text;
+        if (!name) continue;
+        record.declarations.set(name, statement);
+        if (this.isExported(statement)) record.exportedDeclarations.set(name, statement);
+      }
+      if (ts.isImportDeclaration(statement)) {
+        this.indexImport(record, statement);
+      }
+    }
+    return record;
+  }
+
+  isExported(node) {
+    return Boolean(node.modifiers && node.modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword));
+  }
+
+  indexImport(record, statement) {
+    const clause = statement.importClause;
+    if (!clause) return;
+    const moduleName = statement.moduleSpecifier?.text || '';
+    const typeOnly = clause.isTypeOnly || (!clause.name && clause.namedBindings && ts.isNamedImports(clause.namedBindings) && clause.namedBindings.elements.every((element) => Boolean(element.isTypeOnly)));
+    if (!typeOnly) {
+      this.diagnostics.push(diagnostic(record.sourceFile, statement, 'PULSEWASM_SCHEMA_JSON_COMPILE_VALUE_IMPORT_UNSUPPORTED', 'Schema compile stream supports type-only imports only.', 'Use `import type` for payload helper types.', { phase: 'schema-json-compile' }));
+      return;
+    }
+    if (clause.name) {
+      this.diagnostics.push(diagnostic(record.sourceFile, clause.name, 'PULSEWASM_SCHEMA_JSON_COMPILE_VALUE_IMPORT_UNSUPPORTED', 'Default imports are not part of the schema compile stream subset.', 'Use named type-only imports or inline the type alias.', { phase: 'schema-json-compile' }));
+      return;
+    }
+    if (!clause.namedBindings || !ts.isNamedImports(clause.namedBindings)) return;
+
+    let resolvedFile;
+    const markerModule = JSON_MARKER_MODULES.has(moduleName);
+    if (!markerModule) {
+      resolvedFile = this.resolveRelativeModule(record.file, moduleName);
+      if (!resolvedFile) {
+        this.diagnostics.push(diagnostic(record.sourceFile, statement.moduleSpecifier, 'PULSEWASM_SCHEMA_JSON_COMPILE_SOURCE_NOT_FOUND', `Could not resolve type-only import ${JSON.stringify(moduleName)}.`, 'Use a relative path that resolves to a .ts, .tsx, or .d.ts file.', { phase: 'schema-json-compile' }));
+        return;
+      }
+      this.loadFile(resolvedFile);
+    }
+
+    for (const element of clause.namedBindings.elements) {
+      const imported = element.propertyName ? element.propertyName.text : element.name.text;
+      const local = element.name.text;
+      if (markerModule) {
+        record.imports.set(local, { kind: 'marker', marker: normalizeFieldType(imported), imported, local });
+      } else {
+        record.imports.set(local, { kind: 'type', file: resolvedFile, name: imported, imported, local });
+      }
+    }
+  }
+
+  resolveRelativeModule(fromFile, moduleName) {
+    if (!moduleName || (!moduleName.startsWith('./') && !moduleName.startsWith('../') && moduleName !== '.' && moduleName !== '..')) return undefined;
+    const base = path.resolve(path.dirname(fromFile), moduleName);
+    const ext = path.extname(base);
+    const candidates = ext
+      ? [base]
+      : [`${base}.ts`, `${base}.tsx`, `${base}.d.ts`, path.join(base, 'index.ts'), path.join(base, 'index.tsx'), path.join(base, 'index.d.ts')];
+    return candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
+  }
+
+  findRootDeclaration(filePath, typeName) {
+    const record = this.loadFile(filePath);
+    if (!record) return undefined;
+    const decl = record.exportedDeclarations.get(typeName) || record.declarations.get(typeName);
+    if (!decl) return undefined;
+    if (!record.exportedDeclarations.get(typeName)) {
+      this.diagnostics.push(diagnostic(record.sourceFile, decl.name || decl, 'PULSEWASM_SCHEMA_JSON_COMPILE_EXPORT_REQUIRED', `Root type ${JSON.stringify(typeName)} must be exported from the type source.`, 'Export the payload root type so the compile stream has a stable public entry point.', { phase: 'schema-json-compile' }));
+    }
+    return { record, declaration: decl };
+  }
+
+  resolveNamedDeclaration(record, name) {
+    if (!record || !name) return undefined;
+    const local = record.declarations.get(name);
+    if (local) return { record, declaration: local };
+    const imported = record.imports.get(name);
+    if (!imported) return undefined;
+    if (imported.kind === 'type') {
+      const importedRecord = this.loadFile(imported.file);
+      const decl = importedRecord?.exportedDeclarations.get(imported.name) || importedRecord?.declarations.get(imported.name);
+      return decl ? { record: importedRecord, declaration: decl } : undefined;
+    }
+    return { record, marker: imported.marker };
+  }
+}
+
+function memberName(sourceFile, node) {
+  if (!node?.name) return undefined;
+  if (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) return node.name.text;
+  return node.name.getText(sourceFile);
+}
+
+function rootMembers(graph, record, declaration, seen) {
+  const key = `${record.file}#${declaration.name?.text || declaration.pos}`;
+  if (seen.has(key)) return { members: undefined, diagnostic: diagnostic(record.sourceFile, declaration.name || declaration, 'PULSEWASM_SCHEMA_JSON_GENERIC_TYPE_UNSUPPORTED', 'Recursive schema declarations are not supported in the Phase 13 compile stream.', 'Keep v1 schema compile roots flat and non-recursive.', { phase: 'schema-json-compile' }) };
+  seen.add(key);
+  if (ts.isInterfaceDeclaration(declaration)) return { members: declaration.members };
+  if (ts.isTypeAliasDeclaration(declaration)) {
+    const typeNode = declaration.type;
+    if (ts.isTypeLiteralNode(typeNode)) return { members: typeNode.members };
+    if (ts.isParenthesizedTypeNode(typeNode)) {
+      if (ts.isTypeLiteralNode(typeNode.type)) return { members: typeNode.type.members };
+      if (ts.isTypeReferenceNode(typeNode.type) && ts.isIdentifier(typeNode.type.typeName)) {
+        const resolved = graph.resolveNamedDeclaration(record, typeNode.type.typeName.text);
+        if (resolved?.declaration) return rootMembers(graph, resolved.record, resolved.declaration, seen);
+      }
+    }
+    if (ts.isTypeReferenceNode(typeNode) && ts.isIdentifier(typeNode.typeName)) {
+      const resolved = graph.resolveNamedDeclaration(record, typeNode.typeName.text);
+      if (resolved?.declaration) return rootMembers(graph, resolved.record, resolved.declaration, seen);
+    }
+  }
+  return {
+    members: undefined,
+    diagnostic: diagnostic(record.sourceFile, declaration.name || declaration, 'PULSEWASM_SCHEMA_JSON_COMPILE_ROOT_OBJECT_REQUIRED', 'Schema compile stream v1 requires an exported object root type.', 'Use an exported interface or object type alias with required flat fields only.', { phase: 'schema-json-compile' })
+  };
+}
+
+function classifyFieldType(graph, record, typeNode, state) {
+  if (!typeNode) return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', message: 'Schema fields require an explicit type annotation.', hint: 'Annotate every v1 field as string, boolean/bool, number/f64, i32, or u32.' };
+  if (ts.isParenthesizedTypeNode(typeNode)) return classifyFieldType(graph, record, typeNode.type, state);
+  if (typeNode.kind === ts.SyntaxKind.StringKeyword) return { ok: true, type: 'string' };
+  if (typeNode.kind === ts.SyntaxKind.BooleanKeyword) return { ok: true, type: 'bool' };
+  if (typeNode.kind === ts.SyntaxKind.NumberKeyword) return { ok: true, type: 'f64' };
+  if (ts.isArrayTypeNode(typeNode) || ts.isTupleTypeNode(typeNode)) {
+    return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_ARRAY_RESERVED', message: 'Array fields are reserved and are not part of schema JSON v1.', hint: 'Keep Phase 13 compile-stream schemas flat.' };
+  }
+  if (ts.isTypeLiteralNode(typeNode)) {
+    return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_NESTED_OBJECT_RESERVED', message: 'Nested object fields are reserved and are not part of schema JSON v1.', hint: 'Flatten the field set or keep using explicit declarations for richer shapes later.' };
+  }
+  if (ts.isUnionTypeNode(typeNode)) {
+    if (typeNode.types.some((part) => part.kind === ts.SyntaxKind.UndefinedKeyword)) {
+      return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_OPTIONAL_FIELD_RESERVED', message: 'Optional/undefined schema fields are reserved in schema JSON v1.', hint: 'Make every v1 compile-stream field required.' };
+    }
+    if (typeNode.types.some((part) => part.kind === ts.SyntaxKind.NullKeyword || (ts.isLiteralTypeNode(part) && part.literal.kind === ts.SyntaxKind.NullKeyword))) {
+      return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', message: 'Nullable schema fields are reserved in schema JSON v1.', hint: 'Remove `| null` from Phase 13 compile-stream schemas.' };
+    }
+    return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', message: 'Union schema fields are reserved in schema JSON v1.', hint: 'Use a concrete primitive field type.' };
+  }
+  if (ts.isLiteralTypeNode(typeNode)) {
+    return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', message: 'Literal-only schema fields are not part of schema JSON v1.', hint: 'Use string, boolean/bool, number/f64, i32, or u32.' };
+  }
+  if (ts.isTypeReferenceNode(typeNode)) {
+    if (typeNode.typeArguments && typeNode.typeArguments.length > 0) {
+      const typeName = ts.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : typeNode.typeName.getText(record.sourceFile);
+      if (typeName === 'Array') {
+        return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_ARRAY_RESERVED', message: 'Array fields are reserved in schema JSON v1.', hint: 'Keep Phase 13 compile-stream schemas flat.' };
+      }
+      return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_GENERIC_TYPE_UNSUPPORTED', message: `Generic type ${JSON.stringify(typeName)} is not supported by the Phase 13 compile stream.`, hint: 'Use a concrete primitive field type.' };
+    }
+    if (ts.isIdentifier(typeNode.typeName)) {
+      const refName = typeNode.typeName.text;
+      const direct = MARKER_TYPES.get(refName);
+      if (direct) return { ok: true, type: direct };
+      const resolved = graph.resolveNamedDeclaration(record, refName);
+      if (resolved?.marker) return { ok: true, type: normalizeFieldType(resolved.marker) };
+      if (resolved?.declaration) {
+        if (state.stack.has(`${resolved.record.file}#${refName}`)) {
+          return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_GENERIC_TYPE_UNSUPPORTED', message: `Recursive or cyclic reference ${JSON.stringify(refName)} is not supported by the Phase 13 compile stream.`, hint: 'Keep Phase 13 compile-stream schemas flat and acyclic.' };
+        }
+        state.stack.add(`${resolved.record.file}#${refName}`);
+        let result;
+        if (ts.isInterfaceDeclaration(resolved.declaration)) {
+          result = { ok: false, code: 'PULSEWASM_SCHEMA_JSON_NESTED_OBJECT_RESERVED', message: `Nested object reference ${JSON.stringify(refName)} is reserved in schema JSON v1.`, hint: 'Flatten the field set or keep using explicit schema declarations for richer shapes.' };
+        } else if (ts.isTypeAliasDeclaration(resolved.declaration)) {
+          result = classifyFieldType(graph, resolved.record, resolved.declaration.type, state);
+        } else {
+          result = { ok: false, code: 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', message: `Unsupported field type reference ${JSON.stringify(refName)}.`, hint: 'Use a concrete primitive field type.' };
+        }
+        state.stack.delete(`${resolved.record.file}#${refName}`);
+        return result;
+      }
+      return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', message: `Unknown field type reference ${JSON.stringify(refName)}.`, hint: 'Export or import the type alias, or use a supported primitive field type.' };
+    }
+  }
+  return { ok: false, code: 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', message: `Unsupported field type syntax ${JSON.stringify(typeNode.getText(record.sourceFile))}.`, hint: 'Use string, boolean/bool, number/f64, i32, or u32.' };
+}
+
+function compileSchemaSchema(graph, schema, options) {
+  const cwd = options.cwd || process.cwd();
+  const diagnostics = [];
+  const defaultNamespace = options.defaultNamespace || 'app';
+  const namespace = typeof schema.namespace === 'string' && schema.namespace ? schema.namespace : defaultNamespace;
+  const name = typeof schema.name === 'string' && schema.name ? schema.name : schema.type;
+  const typeName = typeof schema.type === 'string' && schema.type ? schema.type : name;
+  const id = `${namespace}.${name}`;
+  const sourceRef = typeof schema.source === 'string' ? schema.source : undefined;
+  const sourceFile = resolveSchemaSource(cwd, options.configFile, sourceRef);
+  const explicit = explicitFields(schema);
+  const fields = [];
+  let mode = 'explicit';
+  let compiled = [];
+
+  if (!sourceRef && explicit.length === 0) {
+    diagnostics.push(makeDiag('PULSEWASM_SCHEMA_JSON_COMPILE_SOURCE_REQUIRED', `Schema ${JSON.stringify(id)} requires either explicit fields or a type source + type name for the compile stream.`, 'Add fields: { ... } or provide source/type so Phase 13 can lower the schema from TypeScript.', options.configFile ? stableFileName(options.configFile, cwd) : '<config>', { schema: id }));
+  }
+
+  if (sourceRef && typeName) {
+    const root = graph.findRootDeclaration(sourceFile, typeName);
+    if (!root) {
+      diagnostics.push(makeDiag('PULSEWASM_SCHEMA_JSON_COMPILE_TYPE_NOT_FOUND', `Could not find exported type ${JSON.stringify(typeName)} in ${JSON.stringify(stableFileName(sourceFile, cwd))}.`, 'Export the payload root type from the source file and ensure the schema type name matches exactly.', sourceFile ? stableFileName(sourceFile, cwd) : '<config>', { schema: id, type: typeName }));
+    } else {
+      const rootShape = rootMembers(graph, root.record, root.declaration, new Set());
+      if (rootShape.diagnostic) diagnostics.push(rootShape.diagnostic);
+      for (const member of rootShape.members || []) {
+        if (!ts.isPropertySignature(member)) {
+          diagnostics.push(diagnostic(root.record.sourceFile, member, 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', 'Schema compile stream v1 supports only object property signatures.', 'Remove methods, call signatures, or index signatures from the root payload type.', { phase: 'schema-json-compile' }));
+          continue;
+        }
+        const fieldName = memberName(root.record.sourceFile, member);
+        if (!fieldName) {
+          diagnostics.push(diagnostic(root.record.sourceFile, member, 'PULSEWASM_SCHEMA_JSON_UNSUPPORTED_FIELD_TYPE', 'Schema compile stream could not resolve a static field name.', 'Use identifier or string-literal property names only.', { phase: 'schema-json-compile' }));
+          continue;
+        }
+        if (member.questionToken) {
+          diagnostics.push(diagnostic(root.record.sourceFile, member.name || member, 'PULSEWASM_SCHEMA_JSON_OPTIONAL_FIELD_RESERVED', `Field ${JSON.stringify(fieldName)} is optional, but optional fields are reserved in schema JSON v1.`, 'Make every compile-stream field required.', { phase: 'schema-json-compile' }));
+          continue;
+        }
+        const lowered = classifyFieldType(graph, root.record, member.type, { stack: new Set([`${root.record.file}#${typeName}`]) });
+        if (!lowered.ok) {
+          diagnostics.push(diagnostic(root.record.sourceFile, member.type || member, lowered.code, lowered.message, lowered.hint, { phase: 'schema-json-compile' }));
+          continue;
+        }
+        compiled.push({ name: fieldName, type: lowered.type, sourceType: member.type?.getText(root.record.sourceFile) || lowered.type });
+      }
+    }
+  }
+
+  if (compiled.length > 0) mode = explicit.length > 0 ? 'equivalence-check' : 'typescript';
+  const effective = compiled.length > 0 ? compiled : explicit;
+
+  if (explicit.length > 0 && compiled.length > 0) {
+    const explicitComparable = explicit.map((field) => ({ name: field.name, type: normalizeFieldType(field.type) }));
+    const compiledComparable = compiled.map((field) => ({ name: field.name, type: normalizeFieldType(field.type) }));
+    const equivalent = explicitComparable.length === compiledComparable.length && explicitComparable.every((field, index) => field.name === compiledComparable[index].name && field.type === compiledComparable[index].type);
+    if (!equivalent) {
+      diagnostics.push(makeDiag(
+        'PULSEWASM_SCHEMA_JSON_COMPILE_MISMATCH',
+        `Explicit field declarations for ${JSON.stringify(id)} do not match the TypeScript compile output.`,
+        'Keep explicit schema declarations and TypeScript source aligned, or omit fields and let the compile stream own the schema declaration.',
+        sourceFile ? stableFileName(sourceFile, cwd) : '<config>',
+        { schema: id, explicit: explicitComparable, compiled: compiledComparable }
+      ));
+    }
+  }
+
+  return {
+    id,
+    namespace,
+    name,
+    type: typeName,
+    source: sourceRef,
+    mode,
+    explicitFields: explicit,
+    compiledFields: compiled,
+    fields: effective,
+    loweredFrom: sourceRef ? { source: stableFileName(sourceFile, cwd), type: typeName } : undefined,
+    diagnostics,
+    sidecarCompatible: diagnostics.every((diag) => diag.severity !== 'error')
+  };
+}
+
+function clone(value) {
+  return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+
+function buildSchemaJsonCompile(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const config = configArtifact(options);
+  const json = jsonConfig(config);
+  const target = typeof json.target === 'string' && json.target ? json.target : 'generic';
+  const schemas = Array.isArray(json.schemas) ? json.schemas : [];
+  const effectiveTarget = target === 'auto' && schemas.length > 0 ? 'schema' : target;
+  const defaultNamespace = typeof json.defaultNamespace === 'string' && json.defaultNamespace ? json.defaultNamespace : 'app';
+  const diagnostics = [];
+  const warnings = [];
+  const files = [];
+  const graph = new TypeGraph(cwd, diagnostics);
+  const configSource = typeof config.source === 'string' ? path.resolve(cwd, config.source) : undefined;
+
+  if (effectiveTarget !== 'schema') {
+    warnings.push(makeWarn('PULSEWASM_SCHEMA_JSON_COMPILE_INACTIVE', 'Schema JSON compile stream is inactive because json.target is not "schema" and auto mode did not provide schemas.', 'Set runtime.payload.json.target = "schema", or use target = "auto" with schemas to enable the compile stream.', configSource ? stableFileName(configSource, cwd) : '<config>', { target, effectiveTarget }));
+  }
+
+  const compiledSchemas = [];
+  for (const schema of schemas) {
+    const result = compileSchemaSchema(graph, schema, { cwd, configFile: configSource, defaultNamespace });
+    compiledSchemas.push(result);
+    diagnostics.push(...(result.diagnostics || []));
+  }
+
+  const effectiveSchemas = compiledSchemas.map((schema) => ({
+    namespace: schema.namespace,
+    name: schema.name,
+    type: schema.type,
+    source: schema.source,
+    codec: 'json',
+    fields: Object.fromEntries(schema.fields.map((field) => [field.name, field.type]))
+  }));
+
+  const compiledConfig = clone(config);
+  const runtime = plainObject(compiledConfig.runtime);
+  const payload = plainObject(runtime.payload);
+  const compiledJson = plainObject(payload.json || compiledConfig.json);
+  compiledJson.target = target;
+  compiledJson.defaultNamespace = defaultNamespace;
+  compiledJson.schemas = effectiveSchemas;
+  if (payload.json || runtime.payload) {
+    if (!runtime.payload) runtime.payload = {};
+    runtime.payload = payload;
+    runtime.payload.json = compiledJson;
+    compiledConfig.runtime = runtime;
+  } else {
+    compiledConfig.json = compiledJson;
+  }
+
+  const artifact = normalizeArtifact({
+    version: SCHEMA_JSON_COMPILE_VERSION,
+    generatedBy,
+    status: diagnostics.some((diag) => diag.severity === 'error') ? 'error' : 'ok',
+    phase: PHASE,
+    target,
+    defaultNamespace,
+    sourceOfTruth: ['runtime.payload.json.schemas[].source', 'runtime.payload.json.schemas[].type', 'runtime.payload.json.schemas[].fields'],
+    backend: 'schema-json-sidecar',
+    policy: {
+      supportedFieldTypes: ['string', 'bool', 'i32', 'u32', 'f64'],
+      typeAliases: { string: 'string', boolean: 'bool', number: 'f64' },
+      reserved: ['arrays', 'nested objects', 'optional fields', 'nullable fields', 'unions', 'generics'],
+      canonicalHandlerSurface: 'ctx.req.parse(schemaId)',
+      defaultNamespaceAuthoringOnly: true,
+      introducesNewRuntime: false
+    },
+    schemas: compiledSchemas.map((schema) => ({
+      id: schema.id,
+      namespace: schema.namespace,
+      name: schema.name,
+      type: schema.type,
+      source: schema.source,
+      mode: schema.mode,
+      loweredFrom: schema.loweredFrom,
+      fields: schema.fields,
+      explicitFields: schema.explicitFields,
+      compiledFields: schema.compiledFields,
+      sidecarCompatible: schema.sidecarCompatible
+    })),
+    effectiveConfig: { target, effectiveTarget, defaultNamespace, schemas: effectiveSchemas },
+    diagnostics,
+    warnings,
+    summary: {
+      active: effectiveTarget === 'schema',
+      schemas: compiledSchemas.length,
+      compiledSchemas: compiledSchemas.filter((schema) => schema.mode === 'typescript' || schema.mode === 'equivalence-check').length,
+      compileOnlySchemas: compiledSchemas.filter((schema) => schema.mode === 'typescript').length,
+      equivalenceChecks: compiledSchemas.filter((schema) => schema.mode === 'equivalence-check').length,
+      explicitOnlySchemas: compiledSchemas.filter((schema) => schema.mode === 'explicit').length,
+      diagnostics: diagnostics.length,
+      warnings: warnings.length,
+      sidecarBackendReady: diagnostics.every((diag) => diag.severity !== 'error')
+    }
+  }, cwd);
+
+  const smoke = normalizeArtifact({
+    version: SCHEMA_JSON_COMPILE_SMOKE_VERSION,
+    generatedBy,
+    status: diagnostics.some((diag) => diag.severity === 'error') ? 'error' : 'ok',
+    phase: PHASE,
+    checks: compiledSchemas.map((schema) => ({
+      schemaId: schema.id,
+      mode: schema.mode,
+      explicitFieldOrder: schema.explicitFields.map((field) => field.name),
+      compiledFieldOrder: schema.compiledFields.map((field) => field.name),
+      effectiveFieldOrder: schema.fields.map((field) => field.name),
+      effectiveFieldTypes: schema.fields.map((field) => field.type),
+      status: 'ok',
+      message: schema.mode === 'equivalence-check'
+        ? 'Explicit fields were checked against TypeScript lowering.'
+        : schema.mode === 'typescript'
+          ? 'TypeScript lowering produced the effective explicit schema declaration.'
+          : 'Explicit schema declaration used directly; compile stream did not need to synthesize fields.'
+    })),
+    summary: {
+      checks: compiledSchemas.length,
+      failedChecks: diagnostics.filter((diag) => diag.severity === 'error').length,
+      backendReady: diagnostics.every((diag) => diag.severity !== 'error'),
+      exactSchemaIdsOnly: true,
+      canonicalHandlerSurface: 'ctx.req.parse(schemaId)'
+    }
+  }, cwd);
+
+  files.push({ file: 'generated/host/schema-json-compile.md', text: buildMarkdown(artifact) });
+
+  return {
+    artifact,
+    smoke,
+    files,
+    diagnostics,
+    warnings,
+    compiledConfig,
+    compiledSchemas,
+    dependencies: Object.freeze([...graph.files.keys()].sort()),
+    active: effectiveTarget === 'schema'
+  };
+}
+
+module.exports = {
+  PHASE,
+  SCHEMA_JSON_COMPILE_VERSION,
+  SCHEMA_JSON_COMPILE_SMOKE_VERSION,
+  buildSchemaJsonCompile,
+  compileNeeded
+};