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

package/src/canonical-api-compiler.js

@@ -0,0 +1,269 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const ts = require('typescript');
+const { executeCanonicalSourceSpine } = require('./spine/canonical-source.js');
+const {
+  extractFetchChain,
+  extractProviderCall,
+  extractKvNamespaceDeclaration
+} = require('./spine/handler-surface-authority.js');
+const {
+  payloadForCanonicalHandlerIr
+} = require('./spine/canonical-handler-ir.js');
+const {
+  emitCanonicalHandlerGenerator
+} = require('./spine/handler-ir-emitter.js');
+const {
+  SUPPORTED_FETCH_DECODERS,
+  ALLOWED_IMPORTS,
+  CanonicalCompileError
+} = require('./spine/plain-handler-frontend.js');
+
+function loadCanonicalRuntimeContract() {
+  try { return require('@pulse-compute/wasm-contracts/handler/canonical-runtime'); }
+  catch (error) {
+    if (error && ['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(error.code)) return require('../../contracts/src/handler/canonical-runtime.js');
+    throw error;
+  }
+}
+
+const canonicalRuntimeContract = loadCanonicalRuntimeContract();
+
+const CANONICAL_API_COMPILER_VERSION = 'pulse.canonical-api-compiler.v7';
+
+function findSourceRoot(start) {
+  let current = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(current, 'package.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(start);
+    current = parent;
+  }
+}
+
+function stableSourceName(file, options = {}) {
+  if (options.fileName) return String(options.fileName).replace(/\\/g, '/');
+  const absolute = path.resolve(file);
+  const root = path.resolve(options.rootDir || findSourceRoot(path.dirname(absolute)));
+  const relative = path.relative(root, absolute).replace(/\\/g, '/');
+  return relative && !relative.startsWith('../') ? relative : path.basename(absolute);
+}
+
+function emitCanonicalProgramFromHandlerIr(ir, options = {}) {
+  const payload = payloadForCanonicalHandlerIr(ir);
+  const sourceFile = payload.sourceFile;
+  const schemaBundle = payload.schemaBundle;
+  const explicitParallelCount = ir.continuationSites.filter((site) => site.kind === 'parallel-group').length;
+  const metadata = Object.freeze({
+    version: ir.programVersion,
+    compilerVersion: ir.compilerVersion,
+    runtimeProtocolVersion: ir.runtimeProtocolVersion,
+    file: ir.file,
+    sourceHash: ir.sourceHash,
+    loweredSourceHash: ir.loweredSourceHash,
+    projectSourceHash: ir.projectSourceHash,
+    handler: 'default',
+    ctxParameter: ir.handler.ctxParameter,
+    capabilities: ir.capabilities,
+    providerOperations: ir.providerOperations,
+    effectSites: ir.effectSites,
+    continuationSites: ir.continuationSites,
+    effectCount: ir.effectSites.length,
+    continuationCount: ir.continuationSites.length,
+    groupedContinuationCount: ir.continuationSites.filter((site) => site.kind === 'fetch-group' || site.kind === 'parallel-group').length,
+    ...(explicitParallelCount > 0 ? { explicitParallelCount } : {}),
+    opaqueReturnCount: ir.continuationSites.filter((site) => site.kind === 'opaque-fetch-return').length,
+    schemaRegistry: ir.schema.registry,
+    schemaIds: ir.schema.ids,
+    responseCaseIds: ir.schema.responseCaseIds,
+    schemaSourceHash: ir.schema.sourceHash,
+    schemaRegistryHash: ir.schema.registryHash,
+    schemaCodecTableHash: ir.schema.codecTableHash,
+    schemaFullCodecRealization: ir.schema.fullCodecRealization,
+    schemaReferences: ir.schemaReferences,
+    schemaReferenceCount: ir.schemaReferences.length,
+    packageEffects: ir.packageEffects,
+    packageEffectCount: ir.packageEffects.length,
+    ...(ir.json ? { json: ir.json } : {}),
+    ...(ir.warnings ? { warnings: ir.warnings, warningCount: ir.warnings.length } : {}),
+    authoring: ir.authoring,
+    ...(ir.application ? { application: ir.application } : {}),
+    ...(ir.applicationEntries ? { applicationEntries: ir.applicationEntries } : {}),
+    ...(ir.events ? { events: ir.events } : {}),
+    router: ir.router,
+    compilerOwnedCalls: ir.compilerOwnedCalls,
+    compilerOwnedIntrinsics: ir.compilerOwnedIntrinsics,
+    compilerPreludeHash: ir.compilerPreludeHash,
+    userAuthoredAsync: ir.invariants.userAuthoredAsync,
+    promiseSemantics: ir.invariants.promiseSemantics,
+    asyncify: ir.invariants.asyncify,
+    ...(options.target === 'javascript' ? { target: 'javascript', promiseSemantics: true } : {})
+  });
+
+  // JavaScript executes the original module graph through its provider. The
+  // normalized IR describes recognized Pulse behavior only; erased awaits and
+  // source-runtime imports must never become an executable generator.
+  if (options.target === 'javascript') return Object.freeze({
+    ok: true,
+    version: CANONICAL_API_COMPILER_VERSION,
+    target: 'javascript',
+    metadata,
+    schemaBundle,
+    diagnostics: Object.freeze([])
+  });
+
+  const emitted = emitCanonicalHandlerGenerator(payload.operationIr);
+  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+  const generatorText = printer.printNode(ts.EmitHint.Unspecified, emitted.generator, sourceFile);
+  const metadataSource = JSON.stringify(metadata, null, 2);
+  const generatedTypeScript = [
+    schemaBundle.declarationSource,
+    payload.compilerPrelude,
+    generatorText,
+    `const __pulse_metadata = ${metadataSource};`,
+    'module.exports = Object.freeze({',
+    `  version: ${JSON.stringify(canonicalRuntimeContract.CANONICAL_PROGRAM_VERSION)},`,
+    '  metadata: Object.freeze(__pulse_metadata),',
+    '  schemaCodecs: __pulse_schema_codecs,',
+    '  createHandler() { return __pulse_handler; }',
+    '});',
+    ''
+  ].join('\n');
+  const transpiled = ts.transpileModule(generatedTypeScript, {
+    fileName: `${ir.file}.generated.ts`,
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.CommonJS,
+      strict: true,
+      removeComments: false,
+      esModuleInterop: false
+    },
+    reportDiagnostics: true
+  });
+  const generatedSource = transpiled.outputText;
+  const generatedEsmTypeScript = [
+    schemaBundle.declarationSource,
+    payload.compilerPrelude,
+    generatorText,
+    `export const version = ${JSON.stringify(canonicalRuntimeContract.CANONICAL_PROGRAM_VERSION)};`,
+    `export const metadata = Object.freeze(${metadataSource});`,
+    'export const schemaCodecs = __pulse_schema_codecs;',
+    'export function createHandler() { return __pulse_handler; }',
+    ''
+  ].join('\n');
+  const esmTranspiled = ts.transpileModule(generatedEsmTypeScript, {
+    fileName: `${ir.file}.generated.mts`,
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ES2022,
+      strict: true,
+      removeComments: false
+    },
+    reportDiagnostics: true
+  });
+  const generatedEsmSource = esmTranspiled.outputText;
+
+  return Object.freeze({
+    ok: true,
+    version: CANONICAL_API_COMPILER_VERSION,
+    metadata,
+    schemaBundle,
+    generatedSource,
+    generatedEsmSource,
+    diagnostics: Object.freeze([])
+  });
+}
+
+const PLAIN_HANDLER_IMPLEMENTATION = Object.freeze({
+  compilerVersion: CANONICAL_API_COMPILER_VERSION,
+  programVersion: canonicalRuntimeContract.CANONICAL_PROGRAM_VERSION,
+  runtimeProtocolVersion: canonicalRuntimeContract.CANONICAL_RUNTIME_PROTOCOL_VERSION,
+  emitCanonicalProgram: emitCanonicalProgramFromHandlerIr
+});
+
+const JAVASCRIPT_HANDLER_INSPECTION = Object.freeze({
+  ...PLAIN_HANDLER_IMPLEMENTATION,
+  emitCanonicalProgram: (ir) => emitCanonicalProgramFromHandlerIr(ir, { target: 'javascript' })
+});
+
+function compileCanonicalSource(sourceText, options = {}) {
+  if (options.target !== undefined && !['native', 'javascript'].includes(options.target)) throw new TypeError('target must be native or javascript.');
+  return executeCanonicalSourceSpine(sourceText, options, options.target === 'javascript'
+    ? JAVASCRIPT_HANDLER_INSPECTION
+    : PLAIN_HANDLER_IMPLEMENTATION);
+}
+
+function compileCanonicalFile(file, options = {}) {
+  const absolute = path.resolve(file);
+  return compileCanonicalSource(fs.readFileSync(absolute, 'utf8'), { ...options, fileName: stableSourceName(absolute, options) });
+}
+
+function loadCanonicalModule(compiled, options = {}) {
+  if (!compiled || compiled.ok !== true || typeof compiled.generatedSource !== 'string') throw new TypeError('loadCanonicalModule requires a successful canonical compilation.');
+  const filename = options.fileName || `${compiled.metadata.file}.generated.cjs`;
+  const module = { exports: {} };
+  const script = new vm.Script(`(function(module, exports, require, __filename, __dirname) {\n${compiled.generatedSource}\n})`, { filename });
+  const fn = script.runInThisContext();
+  fn(module, module.exports, require, filename, path.dirname(filename));
+  return module.exports;
+}
+
+function writeCanonicalBuild(compiled, outDir, options = {}) {
+  if (!compiled || compiled.ok !== true || typeof compiled.generatedSource !== 'string') {
+    throw new TypeError('writeCanonicalBuild requires an executable canonical compilation; JavaScript projects use provider source packaging.');
+  }
+  const target = path.resolve(outDir);
+  fs.mkdirSync(target, { recursive: true });
+  const handlerFile = path.join(target, options.handlerFile || 'canonical-handler.cjs');
+  const programFile = path.join(target, options.programFile || 'canonical-program.json');
+  const esmHandlerFile = options.esmHandlerFile ? path.join(target, options.esmHandlerFile) : undefined;
+  const schemaActive = Boolean(compiled.schemaBundle && compiled.schemaBundle.active);
+  const schemaRegistryFile = schemaActive ? path.join(target, options.schemaRegistryFile || 'schema-json-registry.json') : undefined;
+  const schemaCodecsFile = schemaActive ? path.join(target, options.schemaCodecsFile || 'schema-json-codecs.cjs') : undefined;
+  fs.writeFileSync(handlerFile, compiled.generatedSource);
+  if (esmHandlerFile) fs.writeFileSync(esmHandlerFile, compiled.generatedEsmSource);
+  if (schemaRegistryFile) fs.writeFileSync(schemaRegistryFile, `${JSON.stringify(compiled.schemaBundle.registry, null, 2)}\n`);
+  if (schemaCodecsFile) fs.writeFileSync(schemaCodecsFile, compiled.schemaBundle.moduleSource);
+  const packageInspectionArtifacts = Object.freeze((compiled.packageInspection && compiled.packageInspection.artifacts || []).map((artifact) => {
+    const relativeFile = String(artifact.file || '').replace(/\\/g, '/');
+    const artifactFile = path.resolve(target, relativeFile);
+    const relativeArtifact = path.relative(target, artifactFile);
+    if (!relativeFile || relativeArtifact.startsWith('..') || path.isAbsolute(relativeArtifact)) {
+      const error = new Error(`Package inspection artifact ${artifact.id || '<unknown>'} must remain inside the canonical build output.`);
+      error.code = 'PULSE_PACKAGE_INSPECTION_ARTIFACT_UNSAFE';
+      error.detail = Object.freeze({ id: artifact.id, file: relativeFile });
+      throw error;
+    }
+    fs.mkdirSync(path.dirname(artifactFile), { recursive: true });
+    fs.writeFileSync(artifactFile, `${JSON.stringify(artifact.data, null, 2)}\n`);
+    return Object.freeze({ id: artifact.id, contractId: artifact.contractId, file: artifactFile });
+  }));
+  fs.writeFileSync(programFile, `${JSON.stringify({
+    ...compiled.metadata,
+    generatedHandler: path.basename(handlerFile),
+    generatedEsmHandler: esmHandlerFile ? path.basename(esmHandlerFile) : undefined,
+    generatedSchemaRegistry: schemaRegistryFile ? path.basename(schemaRegistryFile) : undefined,
+    generatedSchemaCodecs: schemaCodecsFile ? path.basename(schemaCodecsFile) : undefined
+  }, null, 2)}\n`);
+  return Object.freeze({ outDir: target, handlerFile, esmHandlerFile, programFile, schemaRegistryFile, schemaCodecsFile, packageInspectionArtifacts, metadata: compiled.metadata });
+}
+
+module.exports = {
+  CANONICAL_API_COMPILER_VERSION,
+  CANONICAL_PROGRAM_VERSION: canonicalRuntimeContract.CANONICAL_PROGRAM_VERSION,
+  CANONICAL_RUNTIME_PROTOCOL_VERSION: canonicalRuntimeContract.CANONICAL_RUNTIME_PROTOCOL_VERSION,
+  SUPPORTED_FETCH_DECODERS,
+  ALLOWED_IMPORTS,
+  CanonicalCompileError,
+  compileCanonicalSource,
+  compileCanonicalFile,
+  loadCanonicalModule,
+  writeCanonicalBuild,
+  extractFetchChain,
+  extractProviderCall,
+  extractKvNamespaceDeclaration,
+  stableSourceName
+};

package/src/canonical-native-compiler.js

@@ -0,0 +1,411 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { executeCanonicalNativeModuleSpine } = require('./spine/canonical-native-module.js');
+const {
+  packageLoweringForCanonicalNativePlan,
+  providerRequirementsForCanonicalNativePlan
+} = require('./spine/canonical-native-plan.js');
+const { packageOperationRecognitionFromEffects, lowerCanonicalPackageOperations } = require('./spine/package-operation-seam.js');
+const { collectProviderRequirements, assertProviderRequirementsForPlan } = require('./spine/provider-requirement-authority.js');
+const { realizeSelectedGuestUnits } = require('./spine/guest-unit-stage.js');
+const {
+  PACKAGE_REALIZATION_ARTIFACT_SET_VERSION
+} = require('@pulse-compute/wasm-contracts/package/package-contract');
+
+function loadNativePlanCompiler() {
+  try { return require('@pulse-compute/wasm-compiler/canonical-native-plan'); }
+  catch (error) {
+    if (error && ['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(error.code)) return require('./canonical-native-plan.js');
+    throw error;
+  }
+}
+
+function loadRuntimeCore() {
+  try { return require('@pulse-compute/wasm-runtime-core-as/compiler/canonical-native'); }
+  catch (error) {
+    if (error && ['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(error.code)) return require('../../runtime-core-as/src/compiler/canonical-native.js');
+    throw error;
+  }
+}
+
+function loadRuntimeContract() {
+  try { return require('@pulse-compute/wasm-contracts/handler/canonical-native-runtime'); }
+  catch (error) {
+    if (error && ['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(error.code)) return require('../../contracts/src/handler/canonical-native-runtime.js');
+    throw error;
+  }
+}
+
+function loadEventContract() {
+  try { return require('@pulse-compute/wasm-contracts/events'); }
+  catch (error) {
+    if (error && ['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(error.code)) return require('../../contracts/src/events/contracts.js');
+    throw error;
+  }
+}
+
+function loadBuildSupport() {
+  try { return require('@pulse-compute/wasm-build-support/assemblyscript-compile'); }
+  catch (error) {
+    if (error && ['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(error.code)) return require('../../build-support/src/assemblyscript-compile.js');
+    throw error;
+  }
+}
+
+const nativePlanCompiler = loadNativePlanCompiler();
+const runtimeCore = loadRuntimeCore();
+const runtimeContract = loadRuntimeContract();
+const eventContract = loadEventContract();
+const { resolveAsc } = loadBuildSupport();
+const { memoryAbi } = (() => {
+  try {
+    return require('@pulse-compute/wasm-guest-link');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND') return require('../../wasm-guest-link/src/index.js');
+    throw error;
+  }
+})();
+const {
+  appendAssemblyScriptOptimizationArgs,
+  resolveNativeOptimization
+} = require('@pulse-compute/wasm-build-support/native-optimization');
+
+class CanonicalNativeCompileError extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = 'CanonicalNativeCompileError';
+    this.code = 'PULSE_CANONICAL_NATIVE_COMPILE_FAILED';
+    this.detail = Object.freeze({ ...detail });
+  }
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function stableObject(value) {
+  if (Array.isArray(value)) return value.map(stableObject);
+  if (!value || typeof value !== 'object') return value;
+  const out = {};
+  for (const key of Object.keys(value).sort()) if (value[key] !== undefined) out[key] = stableObject(value[key]);
+  return out;
+}
+
+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 stableStringify(value, space = 0) {
+  return JSON.stringify(stableObject(value), null, space);
+}
+
+function inspectCanonicalNativeWasm(input, options = {}) {
+  const bytes = Buffer.isBuffer(input) ? input : fs.readFileSync(path.resolve(input));
+  if (!WebAssembly.validate(bytes)) throw new CanonicalNativeCompileError('Generated canonical native Wasm is not valid WebAssembly.');
+  const module = new WebAssembly.Module(bytes);
+  const imports = WebAssembly.Module.imports(module).map((entry) => Object.freeze({ module: entry.module, name: entry.name, kind: entry.kind }));
+  const exports = WebAssembly.Module.exports(module).map((entry) => Object.freeze({ name: entry.name, kind: entry.kind }));
+  const unexpectedModules = [...new Set(imports.map((entry) => entry.module).filter((name) => !['pulse_host', 'env'].includes(name)))];
+  if (unexpectedModules.length > 0) throw new CanonicalNativeCompileError('Canonical native Wasm imports an unsupported module.', { unexpectedModules, imports });
+
+  const allowedPulseImports = new Set(runtimeContract.CANONICAL_NATIVE_IMPORT_NAMES);
+  const pulseImports = imports.filter((entry) => entry.module === 'pulse_host').map((entry) => entry.name).sort();
+  const unexpectedPulseImports = pulseImports.filter((name) => !allowedPulseImports.has(name));
+  if (unexpectedPulseImports.length > 0) {
+    throw new CanonicalNativeCompileError('Canonical native Wasm imports a function outside the versioned pulse_host ABI.', { unexpectedPulseImports, pulseImports });
+  }
+
+  const allowedEnvImports = new Set(runtimeContract.CANONICAL_NATIVE_ALLOWED_ENV_IMPORTS);
+  const unexpectedEnvImports = imports.filter((entry) => entry.module === 'env' && !allowedEnvImports.has(entry.name));
+  if (unexpectedEnvImports.length > 0) {
+    throw new CanonicalNativeCompileError('Canonical native Wasm imports an unsupported AssemblyScript environment function.', { unexpectedEnvImports });
+  }
+
+  const exportNames = new Set(exports.map((entry) => entry.name));
+  const missingExports = runtimeContract.CANONICAL_NATIVE_EXPORT_NAMES.filter((name) => !exportNames.has(name));
+  if (missingExports.length > 0) throw new CanonicalNativeCompileError('Canonical native Wasm is missing required ABI exports.', { missingExports, exports });
+  const plan = options.plan;
+  const eventReachable = Boolean(plan && plan.events && plan.events.catalog && plan.events.catalog.events.length > 0);
+  const eventExportNames = eventContract.EVENT_NATIVE_ABI_EXTENSION.exports.map((entry) => entry.name);
+  const presentEventExports = eventExportNames.filter((name) => exportNames.has(name));
+  if (eventReachable && presentEventExports.length !== eventExportNames.length) {
+    throw new CanonicalNativeCompileError('Event-reachable canonical native Wasm is missing its conditional event ABI exports.', {
+      missingEventExports: eventExportNames.filter((name) => !exportNames.has(name)),
+      exports
+    });
+  }
+  if (plan && !eventReachable && presentEventExports.length > 0) {
+    throw new CanonicalNativeCompileError('HTTP-only canonical native Wasm unexpectedly exposes the conditional event ABI.', { presentEventExports });
+  }
+  return Object.freeze({
+    valid: true,
+    bytes: bytes.length,
+    sha256: sha256(bytes),
+    magic: bytes.subarray(0, 8).toString('hex'),
+    imports: Object.freeze(imports),
+    exports: Object.freeze(exports),
+    importModules: Object.freeze([...new Set(imports.map((entry) => entry.module))].sort())
+  });
+}
+
+function resolveProviderRequirements(plan) {
+  const attached = providerRequirementsForCanonicalNativePlan(plan);
+  if (attached) return attached;
+  const recognition = packageOperationRecognitionFromEffects((plan.packages && plan.packages.effects) || []);
+  return collectProviderRequirements(plan, lowerCanonicalPackageOperations(recognition));
+}
+
+function realizeCanonicalNativePlan(plan, options = {}, providerRequirements) {
+  try {
+    assertProviderRequirementsForPlan(providerRequirements, plan);
+  } catch (error) {
+    throw new CanonicalNativeCompileError('Canonical native realization requires the matching provider-neutral requirement record.', {
+      causeCode: error && error.code,
+      cause: error && error.message,
+      causeDetail: error && error.detail
+    });
+  }
+  const validation = nativePlanCompiler.validateCanonicalNativePlan(plan);
+  const packageLowering = packageLoweringForCanonicalNativePlan(plan);
+  const realizationArtifacts = Object.freeze((packageLowering && packageLowering.realizationArtifacts || [])
+    .map((artifact) => deepFreeze(stableObject(artifact))));
+  const guestUnits = Object.freeze((packageLowering && packageLowering.guestUnits || [])
+    .map((unit) => deepFreeze(stableObject(unit))));
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const compilerPackageRoot = path.resolve(__dirname, '..');
+  const asc = resolveAsc(cwd) || resolveAsc(compilerPackageRoot);
+  if (!asc) throw new CanonicalNativeCompileError('AssemblyScript compiler dependency was not found.', { cwd, remediation: 'Install the lockfile-pinned AssemblyScript dependency before compiling native Wasm.' });
+  const generated = runtimeCore.generateCanonicalNativeAssemblyScript(plan, options);
+  const schemaCodecsActive = generated.manifest.schemaCodecs && generated.manifest.schemaCodecs.active === true;
+  let jsonAs;
+  if (schemaCodecsActive) {
+    let transform;
+    try {
+      transform = require.resolve('json-as', { paths: [compilerPackageRoot, cwd] });
+    } catch (error) {
+      throw new CanonicalNativeCompileError('The lockfile-pinned json-as transform was not found for Native schema codec compilation.', {
+        cwd,
+        package: 'json-as',
+        version: '1.5.0',
+        cause: error && error.message
+      });
+    }
+    const packageRoot = path.resolve(transform, '..', '..', '..');
+    const dependencyRoot = path.dirname(packageRoot);
+    const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    if (packageJson.version !== '1.5.0') {
+      throw new CanonicalNativeCompileError('Native schema codec compilation requires json-as 1.5.0 exactly.', {
+        expected: '1.5.0',
+        actual: packageJson.version,
+        packageRoot
+      });
+    }
+    jsonAs = Object.freeze({ transform, packageRoot, dependencyRoot, version: packageJson.version });
+  }
+  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-canonical-native-'));
+  const requestedOutDir = options.outDir ? path.resolve(options.outDir) : undefined;
+  const outputDir = requestedOutDir || stagingDir;
+  fs.mkdirSync(outputDir, { recursive: true });
+  const sourceFile = path.join(stagingDir, 'canonical-native.as.ts');
+  const wasmFile = path.join(outputDir, options.wasmFile || 'canonical-native.wasm');
+  const watFile = path.join(outputDir, options.watFile || 'canonical-native.wat');
+  try {
+    fs.writeFileSync(sourceFile, generated.source, 'utf8');
+    // Compile from a stable, relative entry name so AssemblyScript's name section and
+    // text output do not capture the random staging directory.
+    const args = [
+      asc.script,
+      path.basename(sourceFile),
+      '--outFile', wasmFile,
+      '--textFile', watFile,
+      '--runtime', schemaCodecsActive ? 'incremental' : 'stub',
+      '--noAssert',
+      '--optimize'
+    ];
+    const optimization = appendAssemblyScriptOptimizationArgs(args, options.nativeOptimization);
+    if (guestUnits.length > 0) {
+      args.push(
+        '--importMemory',
+        '--noExportMemory',
+        '--initialMemory', String(memoryAbi.minimumPages),
+        '--maximumMemory', String(memoryAbi.maximumPages),
+        '--memoryBase', String(memoryAbi.layout.primaryStatic.start)
+      );
+    }
+    if (schemaCodecsActive) {
+      args.push(
+        '--exportRuntime',
+        '--transform', jsonAs.transform,
+        '--path', path.join(compilerPackageRoot, 'node_modules'),
+        '--path', jsonAs.dependencyRoot
+      );
+    }
+    const startedAt = Date.now();
+    const result = spawnSync(asc.executable, args, {
+      cwd: stagingDir,
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+      timeout: Number(options.timeoutMs || 120000),
+      env: schemaCodecsActive
+        ? { ...process.env, JSON_STRICT: 'true', JSON_USE_FAST_PATH: '0' }
+        : process.env
+    });
+    const durationMs = Date.now() - startedAt;
+    if (result.error || result.status !== 0 || !fs.existsSync(wasmFile)) {
+      throw new CanonicalNativeCompileError('AssemblyScript failed to compile the canonical native plan.', {
+        status: result.status,
+        signal: result.signal,
+        error: result.error && result.error.message,
+        stdout: String(result.stdout || '').slice(-12000),
+        stderr: String(result.stderr || '').slice(-12000),
+        source: generated.source,
+        durationMs
+      });
+    }
+    return Object.freeze({
+      plan,
+      validation,
+      realizationArtifacts,
+      guestUnits,
+      generated,
+      wasm: fs.readFileSync(wasmFile),
+      wat: fs.existsSync(watFile) ? fs.readFileSync(watFile, 'utf8') : '',
+      assemblyScriptVersion: require(path.join(asc.packageRoot, 'package.json')).version,
+      jsonAsVersion: jsonAs && jsonAs.version,
+      optimization,
+      durationMs,
+      output: requestedOutDir ? Object.freeze({ outDir: outputDir, wasmFile, watFile }) : undefined
+    });
+  } finally {
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+  }
+}
+
+function realizeCanonicalNativeGuestUnits(realization, plan, options = {}) {
+  return realizeSelectedGuestUnits(realization, realization.guestUnits, options);
+}
+
+function verifyCanonicalNativeRealization(realization) {
+  const inspection = inspectCanonicalNativeWasm(realization.wasm, { plan: realization.plan });
+  const artifactBytes = Buffer.from(stableStringify(realization.realizationArtifacts), 'utf8');
+  const packageRealizationArtifacts = Object.freeze({
+    version: PACKAGE_REALIZATION_ARTIFACT_SET_VERSION,
+    count: realization.realizationArtifacts.length,
+    ids: Object.freeze(realization.realizationArtifacts.map((artifact) => String(artifact.id)).sort()),
+    bytes: artifactBytes.length,
+    sha256: sha256(artifactBytes)
+  });
+  const manifest = Object.freeze({
+    ...realization.generated.manifest,
+    compilerVersion: runtimeContract.CANONICAL_NATIVE_COMPILER_VERSION,
+    assemblyScript: Object.freeze({ package: 'assemblyscript', version: realization.assemblyScriptVersion }),
+    optimization: resolveNativeOptimization(realization.optimization),
+    jsonAs: realization.jsonAsVersion
+      ? Object.freeze({ package: 'json-as', version: realization.jsonAsVersion, transform: true, strict: true })
+      : null,
+    wasm: Object.freeze({ bytes: inspection.bytes, sha256: inspection.sha256, magic: inspection.magic }),
+    wat: Object.freeze({ bytes: Buffer.byteLength(realization.wat), sha256: sha256(realization.wat) }),
+    importModules: inspection.importModules,
+    imports: inspection.imports,
+    exports: inspection.exports,
+    packageRealizationArtifacts,
+    ...(realization.guestLink ? {
+      guestUnitPlan: realization.guestLink.plan,
+      guestLinkReport: realization.guestLink.report,
+      finalWasmAudit: realization.guestLink.audit,
+      providerPackaging: realization.guestLink.providerPackaging
+    } : {}),
+    policy: runtimeContract.CANONICAL_NATIVE_POLICY
+  });
+  return Object.freeze({
+    version: runtimeContract.CANONICAL_NATIVE_WASM_VERSION,
+    compilerVersion: runtimeContract.CANONICAL_NATIVE_COMPILER_VERSION,
+    plan: realization.plan,
+    validation: realization.validation,
+    generated: realization.generated,
+    source: realization.generated.source,
+    sourceHash: realization.generated.sourceHash,
+    realizationArtifacts: realization.realizationArtifacts,
+    guestUnits: realization.guestUnits,
+    guestLink: realization.guestLink,
+    wasm: realization.wasm,
+    wat: realization.wat,
+    inspection,
+    manifest,
+    durationMs: realization.durationMs,
+    output: realization.output
+  });
+}
+
+function compileCanonicalNativePlan(plan, options = {}) {
+  return executeCanonicalNativeModuleSpine(plan, options, {
+    resolveProviderRequirements,
+    realize: realizeCanonicalNativePlan,
+    realizeGuests: realizeCanonicalNativeGuestUnits,
+    verify: verifyCanonicalNativeRealization
+  });
+}
+
+function writeCanonicalNativeModule(compiled, outDir, options = {}) {
+  if (!compiled || !Buffer.isBuffer(compiled.wasm) || !compiled.manifest) throw new TypeError('writeCanonicalNativeModule requires a compiled canonical native module.');
+  const target = path.resolve(outDir);
+  fs.mkdirSync(target, { recursive: true });
+  const sourceFile = path.join(target, options.sourceFile || 'canonical-native.as.ts');
+  const wasmFile = path.join(target, options.wasmFile || 'canonical-native.wasm');
+  const watFile = path.join(target, options.watFile || 'canonical-native.wat');
+  const planFile = path.join(target, options.planFile || 'canonical-native-plan.json');
+  const manifestFile = path.join(target, options.manifestFile || 'canonical-native-manifest.json');
+  const realizationArtifactsFile = compiled.realizationArtifacts.length > 0
+    ? path.join(target, options.realizationArtifactsFile || 'package-artifacts.json')
+    : undefined;
+  const guestUnitPlanFile = compiled.guestLink
+    ? path.join(target, options.guestUnitPlanFile || 'guest-unit-plan.json')
+    : undefined;
+  const guestLinkReportFile = compiled.guestLink
+    ? path.join(target, options.guestLinkReportFile || 'guest-link-report.json')
+    : undefined;
+  const finalWasmAuditFile = compiled.guestLink
+    ? path.join(target, options.finalWasmAuditFile || 'final-wasm-audit.json')
+    : undefined;
+  fs.writeFileSync(sourceFile, compiled.source, 'utf8');
+  fs.writeFileSync(wasmFile, compiled.wasm);
+  fs.writeFileSync(watFile, compiled.wat, 'utf8');
+  fs.writeFileSync(planFile, `${nativePlanCompiler.stableStringify(compiled.plan, 2)}\n`, 'utf8');
+  fs.writeFileSync(manifestFile, `${stableStringify(compiled.manifest, 2)}\n`, 'utf8');
+  if (realizationArtifactsFile) {
+    fs.writeFileSync(realizationArtifactsFile, `${stableStringify(compiled.realizationArtifacts, 2)}\n`, 'utf8');
+  }
+  if (guestUnitPlanFile) fs.writeFileSync(guestUnitPlanFile, `${stableStringify(compiled.guestLink.plan, 2)}\n`, 'utf8');
+  if (guestLinkReportFile) fs.writeFileSync(guestLinkReportFile, `${stableStringify(compiled.guestLink.report, 2)}\n`, 'utf8');
+  if (finalWasmAuditFile) fs.writeFileSync(finalWasmAuditFile, `${stableStringify(compiled.guestLink.audit, 2)}\n`, 'utf8');
+  return Object.freeze({
+    target,
+    sourceFile,
+    wasmFile,
+    watFile,
+    planFile,
+    manifestFile,
+    realizationArtifactsFile,
+    guestUnitPlanFile,
+    guestLinkReportFile,
+    finalWasmAuditFile,
+    manifest: compiled.manifest
+  });
+}
+
+module.exports = Object.freeze({
+  CANONICAL_NATIVE_WASM_VERSION: runtimeContract.CANONICAL_NATIVE_WASM_VERSION,
+  CANONICAL_NATIVE_COMPILER_VERSION: runtimeContract.CANONICAL_NATIVE_COMPILER_VERSION,
+  CanonicalNativeCompileError,
+  compileCanonicalNativePlan,
+  inspectCanonicalNativeWasm,
+  writeCanonicalNativeModule,
+  stableStringify
+});