@pulse-compute/wasm-compiler 1.0.0-beta.8 → 1.0.0-beta.9

package/README.md

@@ -8,9 +8,9 @@
 > **Stability:** Internal compiler interface; no application-author compatibility guarantee.<br>
 > **npm:** [`@pulse-compute/wasm-compiler`](https://www.npmjs.com/package/@pulse-compute/wasm-compiler)<br>
 > **Canonical replacement:** `@pulse-compute/cli`<br>
-> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.8/packages/implementation-packages/)
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.9/packages/implementation-packages/)
 >
-> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.8` package policy.
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.9` package policy.
 <!-- pulse-package-status:end -->
 
 Whole-project compiler implementation used by the `pulse` workflow. Application projects should use `@pulse-compute/cli`, not import this package directly.
@@ -63,4 +63,4 @@ The package exports its root implementation plus focused compiler, CLI, extracto
 
 Compiler changes should be covered by focused static/lowering tests, canonical project inspection, provider-plan parity, packed-package discovery where relevant, and the release documentation gates.
 
-See the installed [implementation package guide](https://pulsecompute.io/v1.0.0-beta.8/packages/implementation-packages/) and [compilation concepts](https://pulsecompute.io/v1.0.0-beta.8/concepts/compilation-and-lowering/).
+See the installed [implementation package guide](https://pulsecompute.io/v1.0.0-beta.9/packages/implementation-packages/) and [compilation concepts](https://pulsecompute.io/v1.0.0-beta.9/concepts/compilation-and-lowering/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-compute/wasm-compiler",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-beta.9",
   "license": "Apache-2.0",
   "description": "PulseWasm compiler package inside the Pulse monorepo.",
   "type": "commonjs",
@@ -9,13 +9,13 @@
     "pulsewasm": "./bin/pulsewasm-extract.js"
   },
   "dependencies": {
-    "@pulse-compute/wasm-build-support": "1.0.0-beta.8",
-    "@pulse-compute/wasm-contracts": "1.0.0-beta.8",
-    "@pulse-compute/wasm-guest-link": "1.0.0-beta.8",
-    "@pulse-compute/wasm-host-runtime": "1.0.0-beta.8",
-    "@pulse-compute/wasm-library-kit": "1.0.0-beta.8",
-    "@pulse-compute/wasm-runtime-core-as": "1.0.0-beta.8",
-    "@pulse-compute/wasm-schema-json": "1.0.0-beta.8",
+    "@pulse-compute/wasm-build-support": "1.0.0-beta.9",
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.9",
+    "@pulse-compute/wasm-guest-link": "1.0.0-beta.9",
+    "@pulse-compute/wasm-host-runtime": "1.0.0-beta.9",
+    "@pulse-compute/wasm-library-kit": "1.0.0-beta.9",
+    "@pulse-compute/wasm-runtime-core-as": "1.0.0-beta.9",
+    "@pulse-compute/wasm-schema-json": "1.0.0-beta.9",
     "assemblyscript": "0.28.18",
     "json-as": "1.5.0",
     "typescript": "5.9.3"
@@ -56,7 +56,7 @@
     "url": "git+https://github.com/pulse-compute/pulse.git",
     "directory": "wasm/packages/compiler"
   },
-  "homepage": "https://pulsecompute.io/v1.0.0-beta.8/packages/implementation-packages/",
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.9/packages/implementation-packages/",
   "bugs": {
     "url": "https://github.com/pulse-compute/pulse/issues"
   },

package/src/canonical-native-compiler.js

@@ -142,7 +142,14 @@ function realizeCanonicalNativePlan(plan, options = {}, providerRequirements) {
     source, sourceHash: sha256(source), manifest: Object.freeze({
       ...application.manifest, planVersion: plan.version, planHash: plan.planHash, sourceHash: sha256(source)
     })
-  }) : runtimeCore.generateCanonicalNativeAssemblyScript(plan, options);
+  }) : runtimeCore.generateCanonicalNativeAssemblyScript(plan, {
+    ...options,
+    // This compiler emits the pulse_host artifact consumed by Node Native.
+    // Provider writers own their final emission policies. Linked guests retain
+    // their existing path until separately qualified; budgeted plans are gated
+    // by the canonical numeric proof itself.
+    numericRegions: guestUnits.length === 0 ? 'host-numeric-regions-v1' : undefined
+  });
   const schemaCodecsActive = generated.manifest.schemaCodecs && generated.manifest.schemaCodecs.active === true;
   let jsonAs;
   if (schemaCodecsActive) {

package/src/canonical-project-compiler.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { retainSourceInputs, sourceInputsForCompiled } = require('./report-source-inputs');
+
 const fs = require('node:fs');
 const path = require('node:path');
 const ts = require('typescript');
@@ -395,6 +397,7 @@ function prepareReachableProjectPackageOperations(graphBuild, options = {}) {
       // identity checkout-independent. Absolute paths remain private graph
       // facts and must not feed project or native-plan hashes.
       ...(preserveSingleFilePublicEnvelope ? { publicSourceName: module.path } : {}),
+      packageDirs: context.packageContractCatalog.contracts.map(entry => entry.packageDir),
       selectedContracts: [...selectedContracts].sort()
     }));
   }
@@ -995,6 +998,7 @@ function compileCanonicalProjectLegacy(entryFile, options = {}) {
   try {
     graphBuild = buildReachableProjectGraph(absoluteEntry, {
       rootDir,
+      target: options.target,
       workspaceRoot: options.workspaceRoot,
       tsconfigFile: options.tsconfigFile,
       resolver: options.moduleResolver,
@@ -1230,10 +1234,12 @@ function compileCanonicalProjectLegacy(entryFile, options = {}) {
     ...(applicationEnvelope ? { application: applicationEnvelope } : {}),
     watchFiles: Object.freeze([...new Set([
       ...graphBuild.projectFiles,
+      ...graphBuild.packageSourceManifests,
       ...schema.dependencies,
       ...(packageOperationRecognition.dependencies || [])
     ].map((file) => path.resolve(file)))])
   });
+  retainSourceInputs(project, projectGraphContext(graphBuild));
   attachPackageOperationRecognition(project, packageOperationRecognition);
   if (terminalPackageApplication) attachTerminalPackageNative(project, {
     application: terminalPackageApplication, recognition: packageOperationRecognition,
@@ -1261,5 +1267,6 @@ module.exports = Object.freeze({
   compileProjectSchemas,
   compileProjectPackageExtensions,
   compileCanonicalProject,
-  packageRealizationArtifactsForCompiled
+  packageRealizationArtifactsForCompiled,
+  sourceInputsForCompiled
 });

package/src/javascript-application-plan.js

@@ -112,6 +112,7 @@ function buildJavascriptApplicationPlan(entryFile, options = {}) {
   let graphBuild;
   try {
     graphBuild = buildReachableProjectGraph(absoluteEntry, {
+      target: 'javascript',
       rootDir: options.rootDir,
       workspaceRoot: options.workspaceRoot,
       configFile: options.configFile,

package/src/project/npm-source-resolution.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const ts = require('typescript');
+const { sourceResolution } = require('../report-source-inputs');
+const reportOwners = new WeakMap();
+
+// This resolver reads source; it never imports a package or its compiler metadata.
+const CONDITIONS = new Set(['pulse', 'import', 'default']);
+
+function fail(message) { throw new Error(message); }
+
+function exportTarget(exports, subpath) {
+  let selected = exports;
+  if (exports && typeof exports === 'object' && !Array.isArray(exports)) {
+    const keys = Object.keys(exports);
+    if (keys.some(key => key.startsWith('.'))) {
+      if (keys.some(key => !key.startsWith('.'))) fail('Mixed export subpaths and conditions are unsupported.');
+      if (!Object.hasOwn(exports, subpath)) fail(`No exact declared export for ${subpath}; wildcard exports are unsupported.`);
+      selected = exports[subpath];
+    } else if (subpath !== '.') fail(`No exact declared export for ${subpath}.`);
+  } else if (subpath !== '.') fail(`No exact declared export for ${subpath}.`);
+  while (selected && typeof selected === 'object' && !Array.isArray(selected)) {
+    const key = Object.keys(selected).find(key => CONDITIONS.has(key));
+    if (!key) fail('No pulse, import or default export condition.');
+    selected = selected[key];
+  }
+  if (typeof selected !== 'string') fail('A source export must select one string target; blocked, missing and array targets are unsupported.');
+  if (!selected.startsWith('./') || /[\\%?#*\0]/.test(selected)
+      || selected.slice(2).split('/').some(part => !part || part === '.' || part === '..' || part.toLowerCase() === 'node_modules')) {
+    fail('A source export must name a contained relative file without traversal or node_modules.');
+  }
+  return selected;
+}
+
+function sourceFile(root, candidate, declaration = false, reportOwner, prefix) {
+  const relative = path.relative(root, candidate);
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)
+      || relative.split(path.sep).some(part => part.toLowerCase() === 'node_modules')) fail('Source file escapes its package root.');
+  const supported = file => /\.(?:ts|mts|js|mjs)$/.test(file) && (declaration || !/\.d\.(?:ts|mts)$/.test(file));
+  if (!supported(candidate)) fail('Only .ts, .mts, .js and .mjs ESM source files are supported.');
+  if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) fail('Declared source file does not exist.');
+  const real = fs.realpathSync(candidate);
+  if (!supported(real)) fail('Source symlink must resolve to a supported ESM source file.');
+  const realRelative = path.relative(root, real);
+  if (!realRelative || realRelative === '..' || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative)
+      || realRelative.split(path.sep).some(part => part.toLowerCase() === 'node_modules')) fail('Source symlink escapes its package root.');
+  sourceResolution(reportOwner, candidate, real, `${prefix}/${realRelative.split(path.sep).join('/')}`);
+  return real;
+}
+
+function packageSource(manifestPath, manifest, packageName, subpath, manifestHash, reportOwner) {
+  if (manifest.name !== packageName || typeof manifest.version !== 'string'
+      || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(manifest.version)) fail('Source packages require a matching name and concrete version.');
+  const root = fs.realpathSync(path.dirname(manifestPath));
+  const target = exportTarget(manifest.exports, subpath);
+  const prefix = `npm/${packageName}@${manifest.version}/${manifestHash}`;
+  const absolute = sourceFile(root, path.resolve(root, target), false, reportOwner, prefix);
+  if (manifest.type === 'commonjs' && /\.(?:js|ts)$/.test(absolute)) fail('Explicit CommonJS package sources are unsupported; declare an ESM source export.');
+  const owner = Object.freeze({ root, absolute, packageName, packageVersion: manifest.version, packageManifestHash: manifestHash, packageType: manifest.type,
+    prefix });
+  if (reportOwner) reportOwners.set(owner, reportOwner);
+  return owner;
+}
+
+function relativeSource(owner, importer, specifier, declaration = false) {
+  if (!specifier.startsWith('./') && !specifier.startsWith('../')) fail('Package source cannot use application tsconfig aliases.');
+  if (/[\\%?#\0]/.test(specifier)) fail('Unsupported package source specifier.');
+  // Exact ESM file links only: no extension substitution, directory or main fallback.
+  const absolute = sourceFile(owner.root, path.resolve(path.dirname(importer), specifier), declaration, reportOwners.get(owner), owner.prefix);
+  if (!declaration && owner.packageType === 'commonjs' && /\.(?:js|ts)$/.test(absolute)) fail('Explicit CommonJS package sources are unsupported.');
+  return absolute;
+}
+
+function unsupportedStatement(sourceFile) {
+  const functionValue = node => {
+    while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node))) node = node.expression;
+    return node && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+  };
+  return sourceFile.statements.find(statement => {
+    if (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement) || ts.isFunctionDeclaration(statement)
+        || ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEmptyStatement(statement)) return false;
+    if (ts.isExportAssignment(statement)) return statement.isExportEquals || !(ts.isIdentifier(statement.expression) || functionValue(statement.expression));
+    if (ts.isVariableStatement(statement)) return !(statement.declarationList.flags & ts.NodeFlags.Const)
+      || statement.declarationList.declarations.some(declaration => !ts.isIdentifier(declaration.name) || !functionValue(declaration.initializer));
+    return true;
+  });
+}
+
+module.exports = Object.freeze({ packageSource, relativeSource, unsupportedStatement });

package/src/project/package-reachability.js

@@ -337,7 +337,7 @@ function packageRelationsForModule(context, targetKey) {
   for (const module of context.projectModules.values()) {
     for (const relation of [...module.imports, ...module.reExports]) {
       const resolution = module.resolutions.find((entry) => entry.relation === relation);
-      if (!resolution || resolution.targetKey !== targetKey) continue;
+      if (!resolution || (resolution.packageKey || resolution.targetKey) !== targetKey) continue;
       records.push(Object.freeze({ module, relation }));
     }
   }
@@ -505,6 +505,7 @@ function derivePackageReachabilityProjection(context, manifest, states) {
     const reExportSources = relations.filter((entry) => entry.relation.kind === 're-export' && entry.relation.typeOnly !== true).map((entry) => entry.relation.source);
     let nativeStatus = 'unsupported';
     if (module.coreAuthoring) nativeStatus = 'core-authoring';
+    else if (module.sourceModule) nativeStatus = 'static-source';
     else if (module.packageContract && module.contract && module.contract.targetSupport.native === true) nativeStatus = 'trusted-lowerable';
     if (module.runtime && nativeStatus === 'trusted-lowerable') selectedContracts.add(module.packageContract);
     packages.push({

package/src/project/reachable-graph-builder.js

@@ -2,8 +2,10 @@
 
 const crypto = require('node:crypto');
 const fs = require('node:fs');
+const { readSourceInput, missingManifest } = require('../report-source-inputs');
 const path = require('node:path');
 const ts = require('typescript');
+const npmSource = require('./npm-source-resolution.js');
 const { discoverPackageContractCatalog } = require('../spine/package-operation-seam.js');
 const {
   PackageReachabilityError,
@@ -34,7 +36,8 @@ class ReachableProjectGraphError extends Error {
   constructor(message, diagnostics = [], detail = {}) {
     super(message);
     this.name = 'ReachableProjectGraphError';
-    this.code = 'PULSE_PROJECT_GRAPH_FAILED';
+    this.code = diagnostics.length > 0 && diagnostics.every(entry => entry.code === 'PULSE_NATIVE_IMPORT_UNSUPPORTED')
+      ? 'PULSE_NATIVE_IMPORT_UNSUPPORTED' : 'PULSE_PROJECT_GRAPH_FAILED';
     this.diagnostics = Object.freeze([...diagnostics]);
     this.detail = Object.freeze({ ...detail });
   }
@@ -158,8 +161,8 @@ function propertyNameText(node) {
   return undefined;
 }
 
-function parseModule(rootDir, absolutePath, logicalPathInput) {
-  const sourceText = fs.readFileSync(absolutePath, 'utf8');
+function parseModule(rootDir, absolutePath, logicalPathInput, reportOwner) {
+  const sourceText = reportOwner ? readSourceInput(reportOwner, absolutePath, 'source', logicalPathInput) : fs.readFileSync(absolutePath, 'utf8');
   const logicalPath = logicalPathInput ? graph.normalizePortablePath(logicalPathInput, 'project module path') : portableFilePath(rootDir, absolutePath);
   const sourceFile = ts.createSourceFile(logicalPath, sourceText, ts.ScriptTarget.ES2022, true, scriptKindForFile(absolutePath));
   const imports = [];
@@ -419,12 +422,13 @@ function workspacePackageIndex(workspaceRoot) {
   return out;
 }
 
-function searchNodeModulesPackage(importerFile, packageName, stopDir) {
+function searchNodeModulesPackage(importerFile, packageName, stopDir, reportOwner) {
   let current = path.dirname(importerFile);
   const stop = path.resolve(stopDir);
   while (true) {
     const candidate = path.join(current, 'node_modules', ...packageName.split('/'), 'package.json');
     if (fs.existsSync(candidate)) return candidate;
+    missingManifest(reportOwner, candidate, packageName);
     if (current === stop || current === path.dirname(current)) break;
     current = path.dirname(current);
   }
@@ -437,27 +441,73 @@ function packageOwner(packageName) {
   return 'third-party';
 }
 
+function discoverResolvedPackageContract(context, manifestPath, packageName) {
+  if (!manifestPath || context.fixedPackageContractCatalog) return;
+  const packageDir = fs.realpathSync(path.dirname(manifestPath));
+  if (context.packageContractDirs.has(packageDir)) return;
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  if (!manifest.pulse?.contract && !manifest.pulsewasm?.manifest && !manifest.pulsewasm?.lowerableManifest) return;
+  if (manifest.name !== packageName) throw new TypeError(`Resolved lowerer package identity must match ${packageName}.`);
+  context.packageContractDirs.add(packageDir);
+  const catalog = discoverPackageContractCatalog({ cwd: context.rootDir, workspaceRoot: context.workspaceRoot,
+    packageDirs: [...context.packageContractDirs] });
+  context.packageContractCatalog = catalog;
+  for (const entry of catalog.contracts) {
+    context.packageContractsBySubpath.set(entry.lowerableSubpath, entry);
+    for (const subpath of entry.compatibilitySubpaths) context.packageContractsBySubpath.set(subpath, entry);
+    context.packageContractsByPackage.set(entry.packageName, catalog.contracts.filter(value => value.packageName === entry.packageName));
+  }
+  for (const entry of catalog.productCatalog.contracts) {
+    context.packageProductContractsByPackage.set(entry.npmPackage, entry);
+    context.packageProductContractsBySpecifier.set(entry.authoring.import, { contract: entry, role: 'authoring' });
+    for (const specifier of entry.ownership.helperImports) context.packageProductContractsBySpecifier.set(specifier, { contract: entry, role: 'helper' });
+    for (const specifier of entry.ownership.reExportImports) context.packageProductContractsBySpecifier.set(specifier, { contract: entry, role: 're-export' });
+  }
+}
+
 function packageModuleForSpecifier(context, importer, classification) {
   const packageName = classification.packageName;
   const specifier = classification.specifier;
+  // Resolve the installed copy at this import before granting compiler authority.
+  const resolvedManifest = searchNodeModulesPackage(importer.absolutePath, packageName, context.workspaceRoot)
+    || context.workspacePackages.get(packageName);
+  discoverResolvedPackageContract(context, resolvedManifest, packageName);
   const contract = context.packageContractsBySubpath.get(specifier) || null;
+  const declaredOwners = context.packageContractsByPackage.get(packageName) || [];
+  if (resolvedManifest && declaredOwners.some(entry => entry.packageDir && fs.realpathSync(entry.packageDir) !== fs.realpathSync(path.dirname(resolvedManifest)))) {
+    throw new TypeError(`Resolved package ${packageName} does not match its selected lowerer owner.`);
+  }
   const productBinding = context.packageProductContractsBySpecifier.get(specifier) || null;
   const productContract = productBinding && productBinding.contract || context.packageProductContractsByPackage.get(packageName) || null;
   const productRole = productBinding && productBinding.role || null;
-  let manifestPath = context.workspacePackages.get(packageName);
-  if (!manifestPath) manifestPath = searchNodeModulesPackage(importer.absolutePath, packageName, context.workspaceRoot);
+  const trusted = CORE_AUTHORING_PACKAGES.has(packageName) || productContract || context.packageContractsByPackage.has(packageName);
+  let manifestPath = (trusted || !context.nativePackageSources) && resolvedManifest;
+  if (!manifestPath && importer.packageSource && importer.packageSource.packageName === packageName) manifestPath = path.join(importer.packageSource.root, 'package.json');
+  if (!manifestPath) manifestPath = searchNodeModulesPackage(importer.absolutePath, packageName, context.workspaceRoot, context.nativePackageSources && !trusted ? context : undefined);
   let manifest;
   let manifestHash;
   if (manifestPath) {
-    const source = fs.readFileSync(manifestPath, 'utf8');
-    manifest = JSON.parse(source);
-    manifestHash = sha256(source);
+    try {
+      const source = context.nativePackageSources && !trusted
+        ? readSourceInput(context, manifestPath, 'manifest', packageName) : fs.readFileSync(manifestPath, 'utf8');
+      manifest = JSON.parse(source);
+      if (!isPlainObject(manifest)) throw new TypeError('Expected a package manifest object.');
+      manifestHash = sha256(source);
+    } catch (_) {
+      throw new ReachableProjectGraphError(`Invalid package manifest for ${packageName}.`, [diagnostic(context.rootDir, importer.sourceFile, null,
+        'PULSE_NATIVE_IMPORT_UNSUPPORTED', `Cannot read a valid package manifest for ${packageName}.`, { packageName })]);
+    }
   } else {
     manifest = { name: packageName, version: 'unresolved' };
     manifestHash = sha256(JSON.stringify(manifest));
   }
   const packageSubpath = classification.packageSubpath || '.';
   const key = `package:${packageName}:${packageSubpath}:${manifestHash}`;
+  const existing = context.packageModules.get(key);
+  if (context.nativePackageSources && existing && existing.sourceCandidate && existing.manifestPath && manifestPath && existing.manifestPath !== fs.realpathSync(manifestPath)) {
+    throw new ReachableProjectGraphError(`Ambiguous installed copies of ${packageName}@${manifest.version}.`, [diagnostic(context.rootDir, importer.sourceFile, null,
+      'PULSE_NATIVE_IMPORT_UNSUPPORTED', 'Distinct installed package roots share one package identity; deduplicate the dependency.', { packageName, packageSubpath })]);
+  }
   if (!context.packageModules.has(key)) {
     context.packageModules.set(key, {
       key,
@@ -478,6 +528,9 @@ function packageModuleForSpecifier(context, importer, classification) {
       source: null,
       specifier,
       classification,
+      manifestPath: manifestPath && fs.realpathSync(manifestPath),
+      manifest,
+      sourceCandidate: !trusted && Boolean(manifestPath),
       contract,
       productContract,
       productRole,
@@ -487,6 +540,35 @@ function packageModuleForSpecifier(context, importer, classification) {
   return context.packageModules.get(key);
 }
 
+function loadPackageSource(context, packageModule, importer, relation) {
+  if (packageModule.sourceModule) return packageModule.sourceModule;
+  let owner;
+  try {
+    owner = npmSource.packageSource(packageModule.manifestPath, packageModule.manifest, packageModule.packageName,
+      packageModule.packageSubpath, packageModule.packageManifestHash, context);
+    const identity = `${owner.packageName}:${owner.packageManifestHash}`;
+    const priorRoot = context.packageSourceRoots.get(identity);
+    if (priorRoot && priorRoot !== owner.root) throw new Error('Distinct installed roots share this package identity; deduplicate the dependency.');
+    context.packageSourceRoots.set(identity, owner.root);
+  } catch (error) {
+    context.diagnostics.push(diagnostic(context.rootDir, importer.sourceFile, relation.statement, 'PULSE_NATIVE_IMPORT_UNSUPPORTED',
+      `Cannot resolve static source export ${relation.specifier}: ${error.message}`, { packageName: packageModule.packageName,
+        packageVersion: packageModule.packageVersion, packageSubpath: packageModule.packageSubpath, automaticFallback: false }));
+    return undefined;
+  }
+  const sourcePath = `${owner.prefix}/${portableFilePath(owner.root, owner.absolute)}`;
+  // Register before following imports so cycles are reported by the graph, not recursion.
+  packageModule.sourceModule = sourcePath;
+  packageModule.source = { file: sourcePath, line: 1, column: 1 };
+  const module = loadProjectModule(context, owner.absolute, sourcePath, owner);
+  packageModule.contentHash = sha256(`${packageModule.contentHash}:${module.contentHash}`);
+  packageModule.exports = exportedNamesForModule(module);
+  context.edges.push({ kind: 're-export', from: packageModule.key, to: sourcePath,
+    specifier: `./${portableFilePath(owner.root, owner.absolute)}`, resolutionKind: 'project-relative', runtime: true,
+    importedNames: [], exportedNames: packageModule.exports, packageContract: null, source: packageModule.source });
+  return sourcePath;
+}
+
 function generatedConfigModule(context) {
   if (!context.configFile) return undefined;
   const key = 'generated:pulse-project-config';
@@ -562,9 +644,19 @@ function scanUnsupportedBoundaries(context, module) {
 function resolveModuleEdges(context, module) {
   const relations = [...module.imports, ...module.reExports];
   for (const relation of relations) {
-    const classification = graph.classifyModuleSpecifier(relation.specifier, context.resolver);
+    const classification = graph.classifyModuleSpecifier(relation.specifier, module.packageSource ? graph.normalizeModuleResolverInput({ baseUrl: '.' }) : context.resolver);
     if (classification.kind === 'project-relative' || classification.kind === 'tsconfig-path') {
-      const resolved = resolveProjectSpecifier(context, module, relation.specifier);
+      let resolved;
+      if (module.packageSource) {
+        try {
+          const absolute = npmSource.relativeSource(module.packageSource, module.absolutePath, relation.specifier, relation.kind === 'type-import' || relation.typeOnly === true);
+          resolved = { status: 'resolved', absolute, portable: `${module.packageSource.prefix}/${portableFilePath(module.packageSource.root, absolute)}` };
+        } catch (error) {
+          context.diagnostics.push(diagnostic(context.rootDir, module.sourceFile, relation.statement, 'PULSE_NATIVE_IMPORT_UNSUPPORTED',
+            `Cannot resolve package source ${relation.specifier}: ${error.message}`, { automaticFallback: false }));
+          continue;
+        }
+      } else resolved = resolveProjectSpecifier(context, module, relation.specifier);
       if (resolved.status === 'missing') {
         context.diagnostics.push(diagnostic(context.rootDir, module.sourceFile, relation.statement, 'PULSE_PROJECT_MODULE_NOT_FOUND', `Unable to resolve project module ${JSON.stringify(relation.specifier)} from ${module.path}.`, { specifier: relation.specifier, candidates: resolved.candidates }));
         continue;
@@ -590,7 +682,7 @@ function resolveModuleEdges(context, module) {
         });
         continue;
       }
-      const target = loadProjectModule(context, resolved.absolute, resolved.portable);
+      const target = loadProjectModule(context, resolved.absolute, resolved.portable, module.packageSource);
       module.resolutions.push(Object.freeze({ relation, classification, targetKey: target.path }));
       context.edges.push({
         kind: relation.kind,
@@ -638,7 +730,9 @@ function resolveModuleEdges(context, module) {
     }
 
     const packageModule = packageModuleForSpecifier(context, module, classification);
-    module.resolutions.push(Object.freeze({ relation, classification, targetKey: packageModule.key }));
+    const sourceKey = context.nativePackageSources && relation.kind !== 'type-import' && relation.typeOnly !== true && packageModule.sourceCandidate
+      ? loadPackageSource(context, packageModule, module, relation) : undefined;
+    module.resolutions.push(Object.freeze({ relation, classification, targetKey: sourceKey || packageModule.key, packageKey: packageModule.key }));
     const packageContractEdge = relation.kind !== 'type-import' && packageModule.packageContract != null;
     context.edges.push({
       kind: packageContractEdge ? 'package-contract' : relation.kind,
@@ -655,13 +749,17 @@ function resolveModuleEdges(context, module) {
   }
 }
 
-function loadProjectModule(context, absolutePath, logicalPath) {
-  const contained = realContainedPath(context.rootDir, absolutePath);
+function loadProjectModule(context, absolutePath, logicalPath, packageSource) {
+  const contained = realContainedPath(packageSource ? packageSource.root : context.rootDir, absolutePath);
   if (!contained) throw new ReachableProjectGraphError(`Project module ${absolutePath} is outside the workspace or missing.`, [], { rootDir: context.rootDir, file: absolutePath });
   const key = logicalPath
     ? graph.normalizePortablePath(logicalPath, 'project module path')
     : portablePath(context.rootDir, path.resolve(absolutePath));
-  if (context.projectModules.has(key)) return context.projectModules.get(key);
+  if (context.projectModules.has(key)) {
+    const existing = context.projectModules.get(key);
+    if (existing.absolutePath !== contained) throw new ReachableProjectGraphError(`Source identity collision at ${key}.`);
+    return existing;
+  }
   const folded = key.toLocaleLowerCase('en-US');
   const collision = [...context.projectModules.keys()].find((existing) => existing.toLocaleLowerCase('en-US') === folded && existing !== key);
   if (collision) {
@@ -675,9 +773,16 @@ function loadProjectModule(context, absolutePath, logicalPath) {
       detail: Object.freeze({ existing: collision, candidate: key })
     })], { rootDir: context.rootDir, existing: collision, candidate: key });
   }
-  const module = parseModule(context.rootDir, contained, key);
+  const module = parseModule(context.rootDir, contained, key, packageSource ? context : undefined);
+  module.packageSource = packageSource;
   context.projectModules.set(key, module);
   context.diagnostics.push(...module.parseDiagnostics);
+  if (packageSource) {
+    const unsupported = npmSource.unsupportedStatement(module.sourceFile);
+    if (unsupported) context.diagnostics.push(diagnostic(context.rootDir, module.sourceFile, unsupported, 'PULSE_NATIVE_IMPORT_UNSUPPORTED',
+      'Package source permits static imports/re-exports, types and function declarations only; module initialization and captured values are unsupported.',
+      { packageName: packageSource.packageName, packageVersion: packageSource.packageVersion, automaticFallback: false }));
+  }
   scanUnsupportedBoundaries(context, module);
   resolveModuleEdges(context, module);
   return module;
@@ -721,7 +826,9 @@ function moduleInputs(context) {
     modules.push({
       key: module.path,
       kind: 'project',
-      owner: 'application',
+      owner: module.packageSource ? packageOwner(module.packageSource.packageName) : 'application',
+      ...(module.packageSource ? { packageName: module.packageSource.packageName, packageVersion: module.packageSource.packageVersion,
+        packageManifestHash: module.packageSource.packageManifestHash, packageSubpath: `./${portableFilePath(module.packageSource.root, module.absolutePath)}` } : {}),
       format: module.format,
       runtime: module.runtime === true,
       path: module.path,
@@ -764,7 +871,7 @@ function createContext(entryFile, options = {}) {
   const packageContractCatalog = options.packageContractCatalog || discoverPackageContractCatalog({
     cwd: rootDir,
     workspaceRoot,
-    scanNodeModules: true
+    packageDirs: []
   });
   const packageContractsBySubpath = new Map();
   for (const entry of packageContractCatalog.contracts) {
@@ -797,14 +904,18 @@ function createContext(entryFile, options = {}) {
       ? Object.freeze({ ...options.projectFragments })
       : Object.freeze({}),
     resolver: resolverInputFromProject(rootDir, options),
+    nativePackageSources: options.target !== 'javascript',
     workspacePackages: workspacePackageIndex(workspaceRoot),
     packageContractCatalog,
+    fixedPackageContractCatalog: Boolean(options.packageContractCatalog),
+    packageContractDirs: new Set(),
     packageContractsBySubpath,
     packageContractsByPackage,
     packageProductContractsByPackage,
     packageProductContractsBySpecifier,
     projectModules: new Map(),
     packageModules: new Map(),
+    packageSourceRoots: new Map(),
     generatedModules: new Map(),
     externalModules: new Map(),
     edges: [],
@@ -915,6 +1026,7 @@ function buildReachableProjectGraph(entryFile, options = {}) {
     entryKey: entry.path,
     graph: preliminary,
     projectFiles: Object.freeze([...context.projectModules.values()].map((module) => module.absolutePath).sort()),
+    packageSourceManifests: Object.freeze([...context.packageModules.values()].filter(module => module.sourceModule).map(module => module.manifestPath).sort()),
     runtimeProjectFiles: Object.freeze([...context.projectModules.values()].filter((module) => module.runtime).map((module) => module.absolutePath).sort()),
     projectModulePaths: Object.freeze([...context.projectModules.values()].map((module) => module.path).sort()),
     runtimeProjectModulePaths: Object.freeze([...context.projectModules.values()].filter((module) => module.runtime).map((module) => module.path).sort()),

package/src/report-handler-topology.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { topologyForCanonicalRouterOutput, surfaceFactsForCanonicalRouterOutput, handlerIrsForCanonicalRouterOutput } = require('./spine/canonical-router');
+const { sourceModelForRouterRecognition, capabilityForHandlerSurface, staticString } = require('./spine/handler-surface-authority');
+const { projectRouterControl } = require('./report-router-control');
+const { bindingOwnership } = require('./spine/binding-ownership');
+const unavailable = () => ({ state: 'unavailable', value: null, reason: 'not-recorded' });
+const available = value => ({ state: 'available', value, reason: null });
+const freeze = value => { if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); } return value; };
+
+// Post-emission observation only. Read retained compiler objects, never reparse
+// emitted source or read files. Nothing here enters executable metadata/hashes.
+function collectHandlerTopology(compiled) {
+  const topology = topologyForCanonicalRouterOutput(compiled.router);
+  if (!topology) return undefined;
+  // A newer/other topology must not turn successful compilation into a report
+  // failure, nor acquire a fabricated role. Its analytics remain unavailable.
+  if (topology.entries.some(({ entry }) => !['route', 'use', 'mount', 'error', 'event', 'fallback'].includes(entry.kind))) return undefined;
+  const linked = topology.options.linkedProjectModules;
+  const files = new Map();
+  const sourceFile = file => linked?.sourceFileForPath(file)
+    || (topology.sourceFile.fileName === file ? topology.sourceFile : undefined);
+  function span(file, start, end) {
+    const source = sourceFile(file);
+    if (!source || !Number.isSafeInteger(start) || !Number.isSafeInteger(end)
+      || start < 0 || end <= start || end > source.text.length) return unavailable();
+    if (!files.has(file)) files.set(file, createHash('sha256').update(source.text).digest('hex'));
+    const point = offset => { const p = source.getLineAndCharacterOfPosition(offset);
+      return { offset, line: p.line + 1, column: p.character + 1 }; };
+    return available({ file, sha256: files.get(file), start: point(start), end: point(end) });
+  }
+  const location = loc => span(loc?.file, loc?.start?.offset, loc?.end?.offset);
+  const modules = new Map((compiled.reachableGraph?.modules || []).filter(m => m.path).map(m => [m.path, m]));
+  function packageFor(file) {
+    const module = modules.get(file);
+    if (!module) return unavailable();
+    return module.packageName && module.packageVersion
+      ? available({ name: module.packageName, version: module.packageVersion, sourceIdentity: module.path })
+      : { state: 'not-applicable', value: null, reason: 'not-applicable' };
+  }
+  const handlers = topology.handlerTable.handlers.map(handler => ({
+    id: handler.id, kind: 'handler', name: handler.localName || handler.exportName || handler.inlineName || null,
+    source: location(handler.loc), package: packageFor(handler.file),
+    evidence: [{ basis: 'handler-table', producer: 'canonical-router-handler-table' }]
+  }));
+  for (const helper of linked?.sourceHelpers || []) {
+    const file = helper.source.file, node = helper.functionNode, source = sourceFile(file);
+    handlers.push({ id: helper.id, kind: 'helper', name: helper.source.name || null,
+      source: source && node ? span(file, node.getStart(source), node.end) : unavailable(), package: packageFor(file),
+      evidence: [{ basis: 'handler-table', producer: 'canonical-router-linked-helper' }] });
+  }
+  const http = new Map(topology.entries.filter(d => d.entry.kind !== 'event').map(d => [d.entry.index, d.entry.stableId]));
+  const controls = new Map((handlerIrsForCanonicalRouterOutput(compiled.router) || []).map(row => [row.entryStableId, row.operationIr]));
+  const mounts = [];
+  const registrations = topology.entries.map(({ entry, rawEntry }) => {
+    // The compiler's child/parent-return interval identifies this particular
+    // mount expansion, even when router definition paths are identical.
+    while (mounts.length && entry.index >= mounts.at(-1).end) mounts.pop();
+    const registration = {
+      id: entry.stableId, handlerId: entry.handlerId || null,
+      kind: entry.kind === 'use' ? 'middleware' : entry.kind,
+      authored: Boolean(rawEntry.loc) && entry.kind !== 'fallback',
+      source: location(rawEntry.loc), routerId: entry.router, routerPath: [...entry.routerPath],
+      mountPath: entry.kind === 'event' ? [] : mounts.map(m => m.id), order: entry.index,
+      match: available({ method: entry.method || null, path: entry.path ?? null, eventType: entry.eventType || null }),
+      control: projectRouterControl(entry, rawEntry, controls.get(entry.stableId)),
+      flow: { next: http.get(entry.nextIndex) || null, child: http.get(entry.childStartIndex) || null,
+        parentContinue: http.get(entry.parentContinueIndex) || null },
+      evidence: [{ basis: 'router-topology', producer: 'canonical-router-execution-topology' }]
+    };
+    if (entry.kind === 'mount' && entry.childStartIndex > entry.index && entry.parentContinueIndex >= entry.childStartIndex) {
+      mounts.push({ id: entry.stableId, end: entry.parentContinueIndex });
+    }
+    return registration;
+  });
+  const model = sourceModelForRouterRecognition(surfaceFactsForCanonicalRouterOutput(compiled.router)?.recognition);
+  const nodeSource = row => span(row.sourceFile.fileName, row.node.getStart(row.sourceFile), row.node.end);
+  const useSites = model?.authoredSites.map(row => {
+    const recognized = row.recognized, capability = capabilityForHandlerSurface(recognized);
+    const provider = recognized.detail?.provider, effect = recognized.detail?.packageEffect;
+    const name = provider ? staticString(provider.resource, { unwrap: true }) : effect?.resource?.kind === 'literal' ? effect.resource.value : undefined;
+    const binding = bindingOwnership(provider?.providerKind || effect?.providerKind, name,
+      Boolean(provider?.resource) && name === undefined || effect?.resource?.kind === 'dynamic');
+    return { ownerId: row.ownerId, surfaceId: recognized.surfaceId, operation: recognized.canonicalOperation,
+      capability: capability ? available(capability) : unavailable(),
+      binding: binding || { state: 'not-applicable', kind: null, canonicalId: null },
+      source: nodeSource(row), evidence: [{ basis: 'authored-recognition', producer: 'canonical-handler-surface-authority' }] };
+  });
+  const calls = new Map();
+  let helperCallsComplete = true;
+  for (const row of model?.validatedCalls || []) {
+    const source = nodeSource(row);
+    // No lowered offsets, call order or guessed identities stand in for source.
+    if (source.state !== 'available') { helperCallsComplete = false; continue; }
+    const key = JSON.stringify([row.callerId, row.calleeId, source.value.file, source.value.start.offset, source.value.end.offset]);
+    if (!calls.has(key)) calls.set(key, { canonicalId: null, callerId: row.callerId, calleeId: row.calleeId,
+      registrationIds: [], source, evidence: [{ basis: 'validated-helper-call', producer: 'canonical-router-handler-validation' }] });
+    calls.get(key).registrationIds.push(row.registrationId);
+  }
+  return freeze({ version: 'pulse.compiler-report-topology.v1', handlers, registrations,
+    ...(model ? { useSites, helperCalls: [...calls.values()], helperCallsComplete } : {}) });
+}
+module.exports = { collectHandlerTopology };

package/src/report-reference-provenance.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const { bindingOwnership } = require('./spine/binding-ownership');
 const { packageOperationRecognitionForCompiled } = require('./spine/package-operation-seam');
 
 // Build-time projection of compiler facts. This record never enters the Native
@@ -65,9 +66,8 @@ function collectCanonicalReportReferences(compiled, plan) {
         : input(effect, kind === 'kv' ? 'store' : 'name');
       const resolved = literal(expression);
       const name = resolved ?? (effect.resource?.kind === 'literal' && typeof effect.resource.value === 'string' ? effect.resource.value : null);
-      add('binding', name, kind, consumers, effect.id, {
-        dynamic: effect.resource?.kind === 'dynamic' || Boolean(expression && expression.kind !== 'literal')
-      });
+      const binding = bindingOwnership(kind, name, effect.resource?.kind === 'dynamic' || Boolean(expression && expression.kind !== 'literal'));
+      add('binding', binding.canonicalId, binding.kind, consumers, effect.id, { dynamic: binding.state === 'dynamic' });
     }
     if (effect.kind === 'event.emit') {
       const schema = literal(field(input(effect, 'emission'), 'schema'));
@@ -110,7 +110,9 @@ function collectCanonicalReportReferences(compiled, plan) {
   // Only compact allowlisted data crosses into Report. No provider metadata,
   // effect payloads, binding values, resource bodies or expression text survives.
   const routeBehaviors = require('./report-route-behavior').routeBehaviorForMetadata(compiled.metadata.router);
+  const topology = require('./report-handler-topology').collectHandlerTopology(compiled);
   return Object.freeze({ version: 'pulse.compiler-report-references.v1',
+    ...(topology ? { topology } : {}),
     ...(routeBehaviors ? { routeBehaviors } : {}),
     responsePayloads: require('./report-response-payloads').collectResponsePayloads(plan, entries, helpers),
     references: Object.freeze([...rows.values()].map(row => Object.freeze({ ...row, entryIds: Object.freeze(unique(row.entryIds)),

package/src/report-router-control.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// Project only accepted canonical operations. No AST text, predicates, provider
+// values or generated positions enter the report, and no runtime IR is changed.
+function projectRouterControl(entry, rawEntry, ir) {
+  const unavailable = { state: 'unavailable', value: null, reason: 'not-recorded' };
+  const value = { pattern: null, eligibility: Boolean(rawEntry.eligibility),
+    normal: false, error: false, terminal: false, basis: 'canonical-router-control' };
+  if (entry.kind === 'route' || entry.kind === 'mount' || entry.kind === 'use' && entry.scoped) {
+    if (!rawEntry.pattern?.normalized) return unavailable;
+    value.pattern = rawEntry.pattern.normalized;
+  }
+  if (entry.kind === 'mount' || !entry.handlerId) value.normal = true;
+  else {
+    if (!ir?.body) return unavailable;
+    let known = true;
+    function visit(operation) {
+      if (!operation) return;
+      switch (operation.kind) {
+        case 'block': operation.statements.forEach(visit); break;
+        case 'if': visit(operation.thenOperation); visit(operation.elseOperation); break;
+        case 'router-guard': visit(operation.body); break;
+        case 'router-transfer':
+          if (operation.clearNormalMode) value.normal = true;
+          else if (operation.errorExpression) value.error = true;
+          else known = false;
+          break;
+        case 'source-statement':
+          if (operation.role === 'router-return') value.terminal = true;
+          else if (operation.role !== 'router-source') known = false;
+          break;
+        default: known = false;
+      }
+    }
+    visit(ir.body);
+    if (entry.kind === 'event') value.terminal = true; // Accepted void fallthrough.
+    if (!known || !value.normal && !value.error && !value.terminal) return unavailable;
+  }
+  return { state: 'available', value, reason: null };
+}
+
+module.exports = { projectRouterControl };

package/src/report-source-inputs.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const reads = new WeakMap(), outputs = new WeakMap();
+const stamp = s => (s.isDirectory() ? [s.dev, s.ino, s.mode] : [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs]).map(String).join(':');
+// In-memory read receipts only: never enter the graph, plan or executable hashes.
+function state(file) {
+  const chain = []; let directory = path.parse(file).root;
+  for (const part of path.relative(directory, file).split(path.sep)) {
+    directory = path.join(directory, part); chain.push(stamp(fs.lstatSync(directory, { bigint: true })));
+  }
+  return { real: fs.realpathSync(file), token: JSON.stringify(chain) };
+}
+function receiptFor(owner) {
+  if (!reads.has(owner)) reads.set(owner, { rows: [], error: null, bytes: 0 });
+  return reads.get(owner);
+}
+function readSourceInput(owner, file, kind, identity) {
+  const receipt = receiptFor(owner);
+  let before; try { before = state(file); } catch { receipt.error = 'REPORT_INPUT_UNBOUND'; }
+  const source = fs.readFileSync(file, 'utf8'); // Preserve the compiler's ordinary read/error behavior.
+  try {
+    const after = state(file), bytes = Buffer.byteLength(source);
+    if (!before || before.real !== after.real || before.token !== after.token) receipt.error = 'REPORT_CONCURRENT_CHANGE';
+    receipt.bytes += bytes;
+    if (receipt.rows.length >= 20000 || receipt.bytes > 256 * 1024 * 1024) receipt.error = 'REPORT_LIMIT';
+    if (!receipt.error) receipt.rows.push(Object.freeze({ file, ...after, kind, identity, bytes,
+      sha256: createHash('sha256').update(source).digest('hex') }));
+  } catch { receipt.error = 'REPORT_INPUT_UNBOUND'; }
+  return source;
+}
+function missingManifest(owner, file, identity) {
+  if (!owner) return;
+  const receipt = receiptFor(owner);
+  if (receipt.rows.length >= 20000) receipt.error = 'REPORT_LIMIT';
+  if (!receipt.error) receipt.rows.push(Object.freeze({ file, real: null, token: 'absent', kind: 'missing-manifest', identity, bytes: 0, sha256: null }));
+}
+function sourceResolution(owner, file, real, identity) {
+  if (!owner || file === real) return;
+  const receipt = receiptFor(owner);
+  try {
+    const observed = state(file);
+    if (observed.real !== real) receipt.error = 'REPORT_CONCURRENT_CHANGE';
+    if (receipt.rows.length >= 20000) receipt.error = 'REPORT_LIMIT';
+    if (!receipt.error) receipt.rows.push(Object.freeze({ file, ...observed, kind: 'source-link', identity, bytes: 0, sha256: null }));
+  } catch { receipt.error = 'REPORT_INPUT_UNBOUND'; }
+}
+function retainSourceInputs(compiled, context) {
+  const receipt = reads.get(context);
+  outputs.set(compiled, Object.freeze({ rows: Object.freeze([...(receipt?.rows || [])]), error: receipt?.error || null }));
+}
+function sourceInputsForCompiled(compiled) { return outputs.get(compiled); }
+module.exports = { readSourceInput, missingManifest, sourceResolution, retainSourceInputs, sourceInputsForCompiled };

package/src/spine/binding-ownership.js

@@ -0,0 +1,13 @@
+'use strict';
+
+// A named binding is compiler evidence, independent of a host's configured
+// value. Both authored recognition and lowered-reference projection use this
+// state policy; absence of a literal never invents a resolved binding.
+function bindingOwnership(kind, name, dynamic = false) {
+  if (!['config', 'secret', 'kv', 's3'].includes(kind)) return undefined;
+  const canonicalId = typeof name === 'string' ? name : null;
+  return Object.freeze({ kind, canonicalId,
+    state: canonicalId !== null ? 'resolved' : dynamic ? 'dynamic' : 'unknown' });
+}
+
+module.exports = { bindingOwnership };

package/src/spine/handler-surface-authority.js

@@ -469,6 +469,25 @@ function routerHandlerNames(entry) {
   });
 }
 
+// Shared compiler projection. Recognition details own provider/package capability
+// names; synchronous surfaces use the same mapping as router analysis.
+function capabilityForHandlerSurface(fact) {
+  if (fact.detail?.provider) return fact.detail.provider.capability;
+  if (fact.detail?.packageEffect) return String(fact.detail.packageEffect.capability || fact.detail.packageEffect.kind);
+  const id = fact.surfaceId;
+  if (id === 'ctx.req.body') return 'request.body.forward';
+  if (id.startsWith('ctx.fetch.')) return 'fetch';
+  if (id.startsWith('ctx.req.')) return id.slice(4);
+  if (id.startsWith('ctx.config.')) return 'config.get';
+  if (id.startsWith('ctx.secret.')) return 'secret.get';
+  if (id.startsWith('ctx.kv.') || id.startsWith('ctx.state.')) return id.slice(4);
+  if (id === 'ctx.emit') return 'event.emit';
+  if (id.startsWith('ctx.log.')) return 'logging';
+  if (['ctx.json', 'ctx.text', 'ctx.response'].includes(id)) return `response.${id.slice(4)}`;
+  if (id === 'ctx.param') return 'route.param';
+  return undefined;
+}
+
 function inspectCanonicalRouterSurfaces(topology, options = {}) {
   if (!topology || topology.frontend !== 'canonical-router' || !topology.sourceFile || !Array.isArray(topology.entries)) {
     throw new TypeError('inspectCanonicalRouterSurfaces requires a prepared canonical Router topology.');
@@ -476,6 +495,47 @@ function inspectCanonicalRouterSurfaces(topology, options = {}) {
   const sourceFile = topology.sourceFile;
   const facts = [];
   const surfacesByEntry = new Map();
+  // Private observations retain original nodes before normalization. They never
+  // enter recognition facts, summaries, executable metadata or identity hashes.
+  const authoredSites = [], validatedCalls = [], seenOwners = new Set();
+  function retainAuthored(ownerId, fn, file, names) {
+    if (seenOwners.has(ownerId)) return;
+    seenOwners.add(ownerId);
+    const seenNodes = new WeakSet();
+    function visit(node, aliases) {
+      if (seenNodes.has(node)) return;
+      seenNodes.add(node);
+      if (ts.isTypeNode(node) || ts.isFunctionLike(node)) return;
+      if (ts.isBlock(node)) {
+        const local = new Map(aliases);
+        for (const statement of node.statements) {
+          const namespace = extractKvNamespaceDeclaration(statement, names.ctxName, { unwrap: true });
+          if (namespace) local.set(namespace.variableName, namespace.store);
+          visit(statement, local);
+        }
+        return;
+      }
+      // Await/parentheses are syntax wrappers, not additional operation sites.
+      const current = expressionFor(node, { unwrap: true });
+      if (current !== node) { visit(current, aliases); return; }
+      if (ts.isAwaitExpression(node)) { visit(node.expression, aliases); return; }
+      const recognized = recognizeHandlerSurface(node, { ...names, unwrap: true,
+        kvAliases: aliases, packageEffectForCall: options.packageEffectForCall });
+      if (recognized && recognized.class !== 'handler-wrapper') {
+        authoredSites.push(Object.freeze({ ownerId, sourceFile: file, node, recognized }));
+        if (ts.isCallExpression(node)) {
+          for (const argument of node.arguments) visit(argument, aliases);
+          // A fetch projection owns its fetch receiver; provider receiver inputs
+          // can themselves contain synchronous context operations.
+          if (recognized.detail?.provider?.resource) visit(recognized.detail.provider.resource, aliases);
+          for (const argument of recognized.detail?.fetch?.fetchCall?.arguments || []) visit(argument, aliases);
+          return;
+        }
+      }
+      ts.forEachChild(node, child => visit(child, aliases));
+    }
+    if (fn.body) visit(fn.body, new Map());
+  }
 
   function record(entry, node, names) {
     const recognized = recognizeHandlerSurface(node, {
@@ -514,6 +574,7 @@ function inspectCanonicalRouterSurfaces(topology, options = {}) {
   for (const entry of topology.entries) {
     if (!entry.functionNode) continue;
     const names = routerHandlerNames(entry);
+    retainAuthored(entry.entry.handlerId, entry.functionNode, entry.sourceFile || sourceFile, names);
     record(entry, entry.functionNode, names);
     function visit(node) {
       if (typeof ts.isTypeNode === 'function' && ts.isTypeNode(node)) return;
@@ -528,6 +589,9 @@ function inspectCanonicalRouterSurfaces(topology, options = {}) {
     if (entry.functionNode.body) visit(entry.functionNode.body);
   }
 
+  for (const helper of options.linkedProjectModules?.sourceHelpers || []) {
+    if (!helper.pure) retainAuthored(helper.id, helper.functionNode, helper.sourceFile, { ctxName: 'ctx' });
+  }
   const recognition = Object.freeze({
     version: HANDLER_SURFACE_AUTHORITY_VERSION,
     contractVersion: contract.HANDLER_SURFACE_CONTRACT_VERSION,
@@ -543,6 +607,12 @@ function inspectCanonicalRouterSurfaces(topology, options = {}) {
   });
   canonicalRouterModels.set(recognition, Object.freeze({
     topology,
+    authoredSites: Object.freeze(authoredSites),
+    get validatedCalls() { return Object.freeze([...validatedCalls]); },
+    retainValidatedCall(entry, helper, node, sourceFile) {
+      validatedCalls.push(Object.freeze({ callerId: entry.handlerId, calleeId: helper.id,
+        registrationId: entry.stableId, node: ts.getOriginalNode(node), sourceFile }));
+    },
     namesForEntry(entryStableId) {
       const entry = topology.entries.find((candidate) => candidate.entry.stableId === entryStableId);
       return entry ? routerHandlerNames(entry) : undefined;
@@ -587,6 +657,7 @@ module.exports = Object.freeze({
   staticString,
   recognizeManagedHandlerWrapper,
   recognizeHandlerSurface,
+  capabilityForHandlerSurface,
   classifyRecognizedHandlerSurface,
   extractFetchChain,
   extractEventEmitCall,

package/src/spine/package-operation-seam.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('node:crypto');
+const { isTrustedLowerer } = require('@pulse-compute/wasm-contracts/library/manifest');
 const fs = require('node:fs');
 const { createRequire } = require('node:module');
 const path = require('node:path');
@@ -82,7 +83,7 @@ function catalogDescriptor(record, productRecord) {
   const nativeSupported = Boolean(
     product
     && ['supported', 'provider-dependent'].includes(product.targets.native.status)
-    && compiler.trust === 'first-party'
+    && isTrustedLowerer(compiler.trust)
     && validation.status === 'ok'
     && wasm.mode !== 'lowering-plan-only'
     && wasm.sidecar
@@ -130,11 +131,13 @@ function discoverPackageContractCatalog(options = {}) {
   const records = discoverLowerableLibraryManifests({
     cwd,
     workspaceRoot: options.workspaceRoot,
+    packageDirs: options.packageDirs,
     scanNodeModules: options.scanNodeModules !== false
   });
   const productCatalog = discoverPulsePackageContracts({
     cwd,
     workspaceRoot: options.workspaceRoot,
+    packageDirs: options.packageDirs,
     scanNodeModules: options.scanNodeModules !== false
   });
   const productsByContract = new Map(productCatalog.contracts.map((entry) => [entry.contractId, { contract: entry, metadataHash: entry.metadataHash }]));
@@ -168,7 +171,7 @@ function discoverPackageContractCatalog(options = {}) {
     }),
     contracts: Object.freeze(contracts),
     policy: Object.freeze({
-      trustedFirstPartyOnly: true,
+      trustedBuildDependencies: true,
       sourceSubstringSelection: false,
       graphReachabilitySelection: true,
       publicRegistration: false,
@@ -333,6 +336,10 @@ function canonicalRealizationArtifact(artifact, record) {
       { id, version, kind, mediaType, contractId, package: packageName }
     );
   }
+  if (kind === 'package-runtime-wasm') {
+    try { return require('@pulse-compute/wasm-contracts/package/runtime-binding').validateRuntimeBinding(value).artifact; }
+    catch { throw new PackageOperationSeamError('PULSE_PACKAGE_REALIZATION_ARTIFACT_INVALID', 'Package runtime Wasm must match the supported bounded ABI.', { id }); }
+  }
   return deepFreeze(value);
 }
 
@@ -615,6 +622,7 @@ function recognizeProjectPackageOperations(entryFile, options = {}) {
   const manifestRecords = discoverLowerableLibraryManifests({
     cwd: rootDir,
     workspaceRoot: options.workspaceRoot,
+    packageDirs: options.packageDirs,
     scanNodeModules: true
   });
   const selected = selectPackageRecords(manifestRecords, sourceText, options.selectedContracts);
@@ -638,8 +646,10 @@ function recognizeProjectPackageOperations(entryFile, options = {}) {
     // This source-aware step is package recognition and validation. The later
     // package-lowering phase receives only the canonical operations below.
     const result = buildPackageOwnedLoweringPlan({
+      typescript: ts,
       cwd: rootDir,
       workspaceRoot: options.workspaceRoot,
+    packageDirs: options.packageDirs,
       manifestRecords,
       contractId: record.manifest.contractId,
       sourcePath: sourceName,
@@ -666,8 +676,12 @@ function recognizeProjectPackageOperations(entryFile, options = {}) {
       .map(canonicalPackageSchemaReference)
       .map((reference) => schemaReferenceWithSourceFile(reference, sourceName));
     schemaReferences.push(...recognizedSchemaReferences);
-    realizationArtifacts.push(...(contributions.realizationArtifacts || [])
-      .map((artifact) => canonicalRealizationArtifact(artifact, record)));
+    const runtimeArtifacts = (contributions.realizationArtifacts || []).map(artifact => canonicalRealizationArtifact(artifact, record));
+    for (const effect of canonicalEffects.filter(effect => effect.kind === 'package.invoke')) {
+      try { require('@pulse-compute/wasm-contracts/package/runtime-binding').validateRuntimeInvocation(effect, runtimeArtifacts); }
+      catch { throw new PackageOperationSeamError('PULSE_PACKAGE_REALIZATION_ARTIFACT_INVALID', 'Package invocation requires an exact declared static runtime binding.', { contractId: record.manifest.contractId }); }
+    }
+    realizationArtifacts.push(...runtimeArtifacts);
     inspectionArtifacts.push(...(contributions.inspectionArtifacts || [])
       .map((artifact) => canonicalInspectionArtifact(artifact, record)));
     managedHandlers.push(...(contributions.managedHandlers || [])
@@ -736,7 +750,7 @@ function recognizeProjectPackageOperations(entryFile, options = {}) {
       lateLoweringReceivesSourceAst: false,
       lateLoweringReceivesSourceText: false,
       lateLoweringInput: CANONICAL_PACKAGE_OPERATION_VERSION,
-      firstPartyBuildersOnly: true,
+      trustedBuildDependencies: true,
       externalRegistration: false
     })
   });
@@ -880,7 +894,7 @@ function combinePackageOperationRecognitions(recognitions = []) {
       lateLoweringReceivesSourceAst: false,
       lateLoweringReceivesSourceText: false,
       lateLoweringInput: CANONICAL_PACKAGE_OPERATION_VERSION,
-      firstPartyBuildersOnly: true,
+      trustedBuildDependencies: true,
       externalRegistration: false
     })
   });
@@ -944,7 +958,7 @@ function packageOperationRecognitionFromEffects(effects = []) {
       lateLoweringReceivesSourceAst: false,
       lateLoweringReceivesSourceText: false,
       lateLoweringInput: CANONICAL_PACKAGE_OPERATION_VERSION,
-      firstPartyBuildersOnly: true,
+      trustedBuildDependencies: true,
       externalRegistration: false
     })
   });

package/src/spine/router-handler-frontend.js

@@ -7,6 +7,7 @@ const {
   staticString,
   recognizeManagedHandlerWrapper,
   recognizeHandlerSurface,
+  capabilityForHandlerSurface,
   sourceModelForRouterRecognition
 } = require('./handler-surface-authority.js');
 const { normalizeManagedHandler } = require('./async-surface-normalizer.js');
@@ -130,17 +131,9 @@ function analysisForSurfaceFacts(surfaceFacts) {
   const capabilities = new Set();
   let fetchCount = 0;
   for (const fact of facts) {
-    if (fact.surfaceId === 'ctx.req.body') { capabilities.add('request.body.forward'); continue; }
-    if (fact.surfaceId.startsWith('ctx.fetch.')) { capabilities.add('fetch'); fetchCount += 1; continue; }
-    if (fact.surfaceId.startsWith('ctx.req.')) capabilities.add(fact.surfaceId.slice('ctx.'.length));
-    else if (fact.surfaceId.startsWith('ctx.config.')) capabilities.add('config.get');
-    else if (fact.surfaceId.startsWith('ctx.secret.')) capabilities.add('secret.get');
-    else if (fact.surfaceId.startsWith('ctx.kv.')) capabilities.add(fact.surfaceId.slice('ctx.'.length));
-    else if (fact.surfaceId.startsWith('ctx.state.')) capabilities.add(fact.surfaceId.slice('ctx.'.length));
-    else if (fact.surfaceId === 'ctx.emit') capabilities.add('event.emit');
-    else if (fact.surfaceId.startsWith('ctx.log.')) capabilities.add('logging');
-    else if (['ctx.json', 'ctx.text', 'ctx.response'].includes(fact.surfaceId)) capabilities.add(`response.${fact.surfaceId.slice('ctx.'.length)}`);
-    else if (fact.surfaceId === 'ctx.param') capabilities.add('route.param');
+    const capability = capabilityForHandlerSurface(fact);
+    if (capability) capabilities.add(capability);
+    if (fact.surfaceId.startsWith('ctx.fetch.')) fetchCount += 1;
   }
   return Object.freeze({
     capabilities: Object.freeze([...capabilities].sort()),
@@ -283,7 +276,7 @@ function normalizeRouterHandler(topology, descriptor, recognition, classificatio
             || node.arguments.length !== helper.functionNode.parameters.length || !['route', 'middleware'].includes(role)) {
             diagnostics.push(diagnostic(sourceFile, original, 'PULSE_NATIVE_PURE_HELPER_CALL_UNSUPPORTED',
               'Pure helpers require a static unshadowed synchronous pure call in an HTTP handler.'));
-          }
+          } else sourceModelForRouterRecognition(recognition)?.retainValidatedCall(entry, helper, original, sourceFile);
           return ts.factory.updateCallExpression(node, ts.factory.createIdentifier(helper.name), undefined,
             node.arguments.map(arg => ts.visitNode(arg, visit)));
         }
@@ -292,7 +285,7 @@ function normalizeRouterHandler(topology, descriptor, recognition, classificatio
           || !ts.isIdentifier(node.arguments[0]) || node.arguments[0].text !== ctxName
           || !['route', 'middleware'].includes(role)) {
           diagnostics.push(diagnostic(sourceFile, original, 'PULSE_NATIVE_HELPER_CALL_UNSUPPORTED', 'A source helper requires an unshadowed, directly awaited local binding and the current request context in an HTTP handler.'));
-        }
+        } else sourceModelForRouterRecognition(recognition)?.retainValidatedCall(entry, helper, original, sourceFile);
         return ts.factory.updateCallExpression(node, ts.factory.createIdentifier(helper.name), undefined, node.arguments.slice(1));
       }
       if (errorName && ts.isShorthandPropertyAssignment(node) && node.name.text === errorName) {

package/src/spine/terminal-package-native.js

@@ -3,6 +3,8 @@
 const { findLowerableManifestRecord } = require('@pulse-compute/wasm-library-kit/compiler/package-lowering');
 const { loadLowerableCompilerBuilder } = require('@pulse-compute/wasm-library-kit/compiler/handler-library-contracts');
 const { compileManagedHandlerNativeBundle } = require('./handler-ir-managed.js');
+const { isTrustedLowerer } = require('@pulse-compute/wasm-contracts/library/manifest');
+const path = require('node:path');
 const applications = new WeakMap();
 
 function attachTerminalPackageNative(compiled, inputs) {
@@ -14,8 +16,8 @@ function terminalPackageNativeForCompiled(compiled) {
   if (!inputs) return null;
   const { application, recognition, managedHandlers, schemaBundle, cwd, workspaceRoot } = inputs;
   const selected = recognition.packages.find(entry => entry.contractId === application.contractId);
-  if (!selected || selected.builder.trust !== 'first-party') throw new TypeError('Native application requires its selected trusted lowerer.');
-  const { record } = findLowerableManifestRecord({ cwd, workspaceRoot, contractId: selected.contractId, npmPackage: selected.package });
+  if (!selected || !isTrustedLowerer(selected.builder.trust)) throw new TypeError('Native application requires its selected trusted lowerer.');
+  const { record } = findLowerableManifestRecord({ cwd, workspaceRoot, packageDirs: recognition.dependencies.map(file => path.dirname(file)), contractId: selected.contractId, npmPackage: selected.package });
   const exportName = record?.manifest?.compiler?.nativeApplicationExport;
   if (!exportName) return null;
   const loaded = loadLowerableCompilerBuilder(record);