@shapeshift-labs/frontier-lang-compiler 0.2.20 → 0.2.22

package/README.md

@@ -64,6 +64,25 @@ console.log(readiness.readiness);
 
 The loss taxonomy separates broad scanner limits from specific round-trip risks such as conditional compilation, reflection, overload/type-inference gaps, comments/trivia preservation, source-map approximation, parser diagnostics, and target projection loss. These records are evidence labels for merge admission; they are not claims that the lightweight scanner expanded macros, evaluated inactive branches, resolved overloads, or ran a type checker.
 
+High-risk native features also have explicit evidence policies. These policies are advisory in this package: they tell a swarm or admission queue what evidence is missing without silently changing the existing readiness classification.
+
+```js
+import {
+  getNativeImportFeatureEvidencePolicy,
+  summarizeNativeImportFeatureEvidence
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const policy = getNativeImportFeatureEvidencePolicy('preprocessor');
+console.log(policy.requiredEvidenceKeys); // ["preprocessedOutputHash", "definesHash"]
+
+const featureEvidence = summarizeNativeImportFeatureEvidence(imported.losses, {
+  evidence: imported.evidence
+});
+
+console.log(featureEvidence.highestRisk);
+console.log(featureEvidence.missingRequiredEvidence);
+```
+
 Ask the compiler what is actually covered before sending native imports into a merge queue:
 
 ```js
@@ -183,15 +202,18 @@ console.log(compiledJs.readiness.readiness); // scanner imports can still be "ne
 
 const rustCandidate = compileNativeSource(compiledJs.importResult, {
   target: 'rust',
+  targetPath: 'dist/runtime.rs',
   emitOnBlocked: true
 });
 
 console.log(rustCandidate.outputMode); // "target-stubs"
 console.log(rustCandidate.targetCoverage.lossClass); // "missingAdapter" without a JS-to-Rust adapter
 console.log(rustCandidate.ok); // true only because emitOnBlocked requested code anyway
+console.log(rustCandidate.sourceMap.targetPath); // "dist/runtime.rs"
+console.log(rustCandidate.sourceMap.mappings[0]?.semanticSymbolId); // generated span -> source symbol
 ```
 
-`compileNativeSource` returns the import result, projection, target loss matrix cell, combined losses, readiness, evidence, and output hash. Admission queues should treat `ok` as "code was emitted", not as merge approval; `readiness` and `targetCoverage` carry the merge signal.
+`compileNativeSource` returns the import result, projection, target loss matrix cell, combined losses, readiness, evidence, output hash, and generated-output source maps. Same-language preserved output uses exact source mappings when the hash matches; generated stubs use declaration-level spans; adapter output uses adapter-supplied maps when present and otherwise gets an estimated fallback. Admission queues should treat `ok` as "code was emitted", not as merge approval; `readiness`, `targetCoverage`, and source-map precision carry the merge signal.
 
 Provide a target projection adapter when the host owns real native-to-target translation semantics:
 
@@ -220,12 +242,14 @@ const jsToRustAdapter = {
 
 const rustWithAdapter = compileNativeSource(compiledJs.importResult, {
   target: 'rust',
+  targetPath: 'dist/runtime.rs',
   targetAdapters: [jsToRustAdapter]
 });
 
 console.log(rustWithAdapter.outputMode); // "target-adapter"
 console.log(rustWithAdapter.targetCoverage.lossClass); // "targetAdapterProjection"
 console.log(rustWithAdapter.targetProjection.adapter.id); // "app-js-to-rust"
+console.log(rustWithAdapter.sourceMaps.length); // adapter maps or compiler fallback map
 ```
 
 Project a native import back to source. Exact source is preserved when the import carries matching source-preservation evidence or when supplied text matches the import hash; otherwise the compiler emits declaration stubs with review-required loss evidence:

package/bench/smoke.mjs

@@ -9,7 +9,8 @@ import {
   createSemanticImportSidecar,
   importNativeSource,
   projectNativeImportToSource,
-  runNativeImporterAdapter
+  runNativeImporterAdapter,
+  summarizeNativeImportFeatureEvidence
 } from '../dist/index.js';
 
 const source = `
@@ -88,6 +89,13 @@ const semanticSidecars = nativeImportResults.map((imported) => createSemanticImp
 const sidecarDurationMs = performance.now() - sidecarStart;
 const sidecarOwnershipRegions = semanticSidecars.reduce((sum, sidecar) => sum + sidecar.ownershipRegions.length, 0);
 
+const featureEvidenceStart = performance.now();
+const featureEvidenceSummaries = nativeImportResults.map((imported) => summarizeNativeImportFeatureEvidence(imported.losses, {
+  evidence: imported.evidence
+}));
+const featureEvidenceDurationMs = performance.now() - featureEvidenceStart;
+const featureEvidencePolicyMatches = featureEvidenceSummaries.reduce((sum, summary) => sum + summary.total, 0);
+
 const projectionStart = performance.now();
 const nativeProjections = nativeImportResults.map((imported) => projectNativeImportToSource(imported));
 const projectionDurationMs = performance.now() - projectionStart;
@@ -100,6 +108,8 @@ const nativeCompiles = nativeImportResults.map((imported, index) => compileNativ
 }));
 const nativeCompileDurationMs = performance.now() - nativeCompileStart;
 const nativeCompileBytes = nativeCompiles.reduce((sum, result) => sum + result.output.length, 0);
+const nativeCompileSourceMaps = nativeCompiles.reduce((sum, result) => sum + result.sourceMaps.length, 0);
+const nativeCompileSourceMapMappings = nativeCompiles.reduce((sum, result) => sum + result.sourceMaps.reduce((mapSum, sourceMap) => mapSum + sourceMap.mappings.length, 0), 0);
 const nativeCompileBlocked = nativeCompiles.filter((result) => result.readiness.readiness === 'blocked').length;
 const nativeTargetAdapterStart = performance.now();
 const nativeTargetAdapterCompiles = nativeImportResults.slice(0, 25).map((imported, index) => {
@@ -122,6 +132,7 @@ const nativeTargetAdapterCompiles = nativeImportResults.slice(0, 25).map((import
 });
 const nativeTargetAdapterDurationMs = performance.now() - nativeTargetAdapterStart;
 const nativeTargetAdapterBytes = nativeTargetAdapterCompiles.reduce((sum, result) => sum + result.output.length, 0);
+const nativeTargetAdapterSourceMaps = nativeTargetAdapterCompiles.reduce((sum, result) => sum + result.sourceMaps.length, 0);
 
 console.log(JSON.stringify({
   compiles: 250,
@@ -147,14 +158,19 @@ console.log(JSON.stringify({
   semanticSidecars: semanticSidecars.length,
   sidecarOwnershipRegions,
   sidecarDurationMs: Number(sidecarDurationMs.toFixed(2)),
+  featureEvidencePolicyMatches,
+  featureEvidenceDurationMs: Number(featureEvidenceDurationMs.toFixed(2)),
   nativeProjections: nativeProjections.length,
   projectionBytes,
   projectionDurationMs: Number(projectionDurationMs.toFixed(2)),
   nativeCompiles: nativeCompiles.length,
   nativeCompileBytes,
+  nativeCompileSourceMaps,
+  nativeCompileSourceMapMappings,
   nativeCompileBlocked,
   nativeCompileDurationMs: Number(nativeCompileDurationMs.toFixed(2)),
   nativeTargetAdapterCompiles: nativeTargetAdapterCompiles.length,
   nativeTargetAdapterBytes,
+  nativeTargetAdapterSourceMaps,
   nativeTargetAdapterDurationMs: Number(nativeTargetAdapterDurationMs.toFixed(2))
 }));

package/dist/index.d.ts

@@ -151,6 +151,49 @@ export interface NativeImportLossSummaryOptions {
   readonly semanticStatus?: string;
 }
 
+export type NativeImportFeatureEvidenceRisk = 'low' | 'medium' | 'high' | 'critical' | string;
+
+export interface NativeImportFeatureEvidencePolicy {
+  readonly kind: NativeImportKnownLossKind;
+  readonly category: NativeImportTaxonomyKind;
+  readonly risk: NativeImportFeatureEvidenceRisk;
+  readonly minimumReadiness: SemanticMergeReadiness;
+  readonly missingEvidenceReadiness: SemanticMergeReadiness;
+  readonly requiredEvidenceKeys: readonly string[];
+  readonly recommendedEvidenceKeys: readonly string[];
+  readonly notes: readonly string[];
+}
+
+export interface NativeImportFeatureEvidenceIssue {
+  readonly lossId: string;
+  readonly kind: NativeImportKnownLossKind;
+  readonly policyKind: NativeImportKnownLossKind;
+  readonly risk: NativeImportFeatureEvidenceRisk;
+  readonly category: NativeImportTaxonomyKind;
+  readonly readiness: SemanticMergeReadiness;
+  readonly missingRequiredEvidence: readonly string[];
+  readonly presentRequiredEvidence: readonly string[];
+  readonly presentRecommendedEvidence: readonly string[];
+  readonly evidenceIds: readonly string[];
+}
+
+export interface NativeImportFeatureEvidenceSummary {
+  readonly total: number;
+  readonly policyKinds: readonly NativeImportKnownLossKind[];
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly byRisk: Readonly<Record<string, number>>;
+  readonly highestRisk: NativeImportFeatureEvidenceRisk;
+  readonly semanticMergeReadiness: SemanticMergeReadiness;
+  readonly missingRequiredEvidence: readonly {
+    readonly lossId: string;
+    readonly kind: NativeImportKnownLossKind;
+    readonly policyKind: NativeImportKnownLossKind;
+    readonly evidenceKey: string;
+  }[];
+  readonly issues: readonly NativeImportFeatureEvidenceIssue[];
+  readonly reasons: readonly string[];
+}
+
 export interface NativeImportLossSummary {
   readonly total: number;
   readonly hasLosses: boolean;
@@ -165,6 +208,7 @@ export interface NativeImportLossSummary {
   readonly reviewLossIds: readonly string[];
   readonly informationalLossIds: readonly string[];
   readonly failedEvidenceIds: readonly string[];
+  readonly featureEvidence: NativeImportFeatureEvidenceSummary;
   readonly parser?: string;
   readonly scanKind?: string;
   readonly semanticStatus?: string;
@@ -1331,6 +1375,10 @@ export interface CompileNativeSourceOptions extends ProjectNativeImportToSourceO
   readonly languages?: readonly NativeImportLanguageProfile[];
   readonly generatedAt?: number;
   readonly emitOnBlocked?: boolean;
+  readonly emitSourceMap?: boolean;
+  readonly targetPath?: string;
+  readonly targetHash?: string;
+  readonly sourceMapId?: string;
   readonly projectionId?: string;
   readonly projectionEvidenceId?: string;
   readonly compileEvidenceId?: string;
@@ -1349,6 +1397,8 @@ export interface NativeSourceCompileResult {
   readonly output: string;
   readonly outputHash: string;
   readonly outputMode: NativeSourceCompileOutputMode;
+  readonly sourceMap?: SourceMapRecord;
+  readonly sourceMaps: readonly SourceMapRecord[];
   readonly importResult: NativeSourceImportResult;
   readonly projection: NativeSourceProjectionResult;
   readonly targetProjection?: NativeTargetProjectionResult;
@@ -1422,6 +1472,7 @@ export declare const NativeImportLossKinds: readonly NativeImportKnownLossKind[]
 export declare const NativeImportRegionTaxonomyKinds: readonly NativeImportRegionTaxonomyKind[];
 export declare const ProjectionTargetLossClasses: readonly ProjectionTargetLossClass[];
 export declare const NativeImportReadinessBySeverity: Readonly<Record<NativeImportLossSummary['highestSeverity'], SemanticMergeReadiness>>;
+export declare const NativeImportFeatureEvidencePolicies: Readonly<Record<string, NativeImportFeatureEvidencePolicy>>;
 export declare const NativeImportLanguageProfiles: readonly NativeImportLanguageProfile[];
 export declare function normalizeCompileTarget(target?: string): FrontierCompileTarget;
 export declare function compileFrontierSource(source: string, options?: FrontierCompileOptions): FrontierCompileResult;
@@ -1432,6 +1483,8 @@ export declare function renderTargetAst(ast: FrontierTargetAst, target?: Frontie
 export declare function renderTargetAstWithSourceMap(ast: FrontierTargetAst, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetSourceMapResult;
 export declare function emitForTargetWithSourceMap(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetDocumentSourceMapResult;
 export declare function resolveCapabilityAdapters(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: { readonly platform?: string }): readonly CapabilityResolution[];
+export declare function getNativeImportFeatureEvidencePolicy(kind: NativeImportKnownLossKind | string): NativeImportFeatureEvidencePolicy | undefined;
+export declare function summarizeNativeImportFeatureEvidence(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportFeatureEvidenceSummary;
 export declare function summarizeNativeImportLosses(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportLossSummary;
 export declare function classifyNativeImportReadiness(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportReadinessClassification;
 export declare function classifyNativeImportRoundtripReadiness(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: NativeImportRoundtripReadinessOptions): NativeImportRoundtripReadinessClassification;

package/dist/index.js

@@ -76,6 +76,13 @@ const semanticMergeReadinessRank = Object.freeze({
   blocked: 3
 });
 
+const nativeFeatureEvidenceRiskRank = Object.freeze({
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3
+});
+
 export const NativeImportRoundtripReadinessStatuses = Object.freeze([
   'exact',
   'preserved-source',
@@ -136,6 +143,117 @@ export const NativeImportReadinessBySeverity = Object.freeze({
   error: 'blocked'
 });
 
+export const NativeImportFeatureEvidencePolicies = Object.freeze({
+  macroExpansion: nativeImportFeatureEvidencePolicy('macroExpansion', {
+    category: 'macroExpansion',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['macroDefinitionsHash', 'expandedSourceHash'],
+    recommendedEvidenceKeys: ['expansionMapId', 'sourceMapId', 'macroCallSites'],
+    notes: ['Macro-expanded code must retain a link from generated output back to macro call sites before semantic merges can be trusted.']
+  }),
+  macroHygiene: nativeImportFeatureEvidencePolicy('macroHygiene', {
+    category: 'macroExpansion',
+    risk: 'critical',
+    minimumReadiness: 'needs-review',
+    missingEvidenceReadiness: 'blocked',
+    requiredEvidenceKeys: ['hygieneContextHash', 'bindingMapId'],
+    recommendedEvidenceKeys: ['expansionMapId', 'captureSetHash'],
+    notes: ['Hygiene-sensitive macros can change binding identity even when emitted text looks equivalent.']
+  }),
+  preprocessor: nativeImportFeatureEvidencePolicy('preprocessor', {
+    category: 'preprocessor',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['preprocessedOutputHash', 'definesHash'],
+    recommendedEvidenceKeys: ['includeGraphHash', 'conditionalBranches', 'sourceMapId'],
+    notes: ['Preprocessor imports need the active defines/includes and preprocessed output hash to make replayable claims.']
+  }),
+  conditionalCompilation: nativeImportFeatureEvidencePolicy('conditionalCompilation', {
+    category: 'conditionalCompilation',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['activeBranches', 'inactiveBranchesHash'],
+    recommendedEvidenceKeys: ['compileTarget', 'featureFlags', 'preprocessedOutputHash'],
+    notes: ['Conditional branches that were not active still affect portability and conflict review.']
+  }),
+  metaprogramming: nativeImportFeatureEvidencePolicy('metaprogramming', {
+    category: 'metaprogramming',
+    risk: 'critical',
+    minimumReadiness: 'needs-review',
+    missingEvidenceReadiness: 'blocked',
+    requiredEvidenceKeys: ['generatedArtifactHash', 'generatorIdentity'],
+    recommendedEvidenceKeys: ['generatorInputsHash', 'generatedRanges', 'replayCommand'],
+    notes: ['Generated or metaprogrammed declarations need replayable generator identity and input evidence.']
+  }),
+  reflection: nativeImportFeatureEvidencePolicy('reflection', {
+    category: 'reflection',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['reflectionSurface', 'runtimeContract'],
+    recommendedEvidenceKeys: ['observedMembers', 'fixtureIds', 'runtimeVersion'],
+    notes: ['Reflection-heavy code needs a declared runtime contract because static AST evidence is incomplete.']
+  }),
+  dynamicRuntime: nativeImportFeatureEvidencePolicy('dynamicRuntime', {
+    category: 'reflection',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['runtimeContract'],
+    recommendedEvidenceKeys: ['fixtureIds', 'observedEffects', 'runtimeVersion'],
+    notes: ['Dynamic runtime behavior should stay review-required until fixtures or traces describe the observed contract.']
+  }),
+  dynamicDispatch: nativeImportFeatureEvidencePolicy('dynamicDispatch', {
+    category: 'overloadTypeInference',
+    risk: 'medium',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['dispatchTargets'],
+    recommendedEvidenceKeys: ['callGraphId', 'typeEvidenceId', 'fixtureIds'],
+    notes: ['Dynamic dispatch needs candidate target evidence before call graph or porting claims are merge-ready.']
+  }),
+  generatedCode: nativeImportFeatureEvidencePolicy('generatedCode', {
+    category: 'generatedCode',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['generatedArtifactHash', 'generatedRanges'],
+    recommendedEvidenceKeys: ['generatorIdentity', 'generatorInputsHash', 'sourceMapId'],
+    notes: ['Generated code must preserve generated ranges and artifact hashes so workers can avoid editing derived output blindly.']
+  }),
+  overloadResolution: nativeImportFeatureEvidencePolicy('overloadResolution', {
+    category: 'overloadTypeInference',
+    risk: 'medium',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['resolvedOverloads'],
+    recommendedEvidenceKeys: ['typeEvidenceId', 'compilerVersion', 'callSiteSpans'],
+    notes: ['Overload-sensitive imports should record compiler/type evidence for each call site.']
+  }),
+  typeInference: nativeImportFeatureEvidencePolicy('typeInference', {
+    category: 'overloadTypeInference',
+    risk: 'medium',
+    minimumReadiness: 'needs-review',
+    requiredEvidenceKeys: ['inferredTypesHash'],
+    recommendedEvidenceKeys: ['typeEvidenceId', 'compilerVersion', 'symbolTableHash'],
+    notes: ['Inferred types need a stable type-evidence hash before cross-language projection can claim fidelity.']
+  }),
+  unsupportedSyntax: nativeImportFeatureEvidencePolicy('unsupportedSyntax', {
+    category: 'unsupportedSyntax',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    missingEvidenceReadiness: 'blocked',
+    requiredEvidenceKeys: ['unsupportedSyntaxKind', 'sourceSpan'],
+    recommendedEvidenceKeys: ['parserDiagnosticId', 'nativeAstNodeId', 'sourceSnippetHash'],
+    notes: ['Unsupported syntax must remain anchored to source spans and parser diagnostics for later adapter work.']
+  }),
+  unsupportedSemantic: nativeImportFeatureEvidencePolicy('unsupportedSemantic', {
+    category: 'unsupportedSyntax',
+    risk: 'high',
+    minimumReadiness: 'needs-review',
+    missingEvidenceReadiness: 'blocked',
+    requiredEvidenceKeys: ['unsupportedSemanticKind', 'semanticSymbolId'],
+    recommendedEvidenceKeys: ['semanticIndexId', 'sourceMapId', 'reason'],
+    notes: ['Unsupported semantics should name the affected symbol so merge tools can isolate the unsafe region.']
+  })
+});
+
 export const NativeImportRegionTaxonomyKinds = Object.freeze([
   'symbol',
   'declaration',
@@ -359,6 +477,25 @@ export function compileNativeSource(input, options = {}) {
     scanKind: 'native-source-compile',
     semanticStatus: importResult.metadata?.semanticStatus ?? options.semanticStatus
   });
+  const sourceMaps = options.emitSourceMap === false
+    ? []
+    : nativeSourceCompileSourceMaps({
+      id: options.sourceMapId ?? `source_map_${idFragment(id)}_${idFragment(target)}`,
+      importResult,
+      projection,
+      targetProjection,
+      sourceLanguage,
+      target,
+      targetPath: options.targetPath ?? targetProjection?.targetPath,
+      targetHash: options.targetHash ?? outputHash,
+      output,
+      outputHash,
+      outputMode,
+      evidence,
+      losses,
+      compileResultId: id
+    });
+  const sourceMap = sourceMaps[0];
   return {
     kind: 'frontier.lang.nativeSourceCompileResult',
     version: 1,
@@ -370,6 +507,8 @@ export function compileNativeSource(input, options = {}) {
     output,
     outputHash,
     outputMode,
+    sourceMap,
+    sourceMaps,
     importResult,
     projection,
     targetProjection,
@@ -388,8 +527,13 @@ export function compileNativeSource(input, options = {}) {
       projectionId: projection.id,
       targetProjectionId: targetProjection?.id,
       targetProjectionAdapterId: targetProjection?.adapter?.id,
+      sourceMapId: sourceMap?.id,
+      sourceMapIds: sourceMaps.map((record) => record.id).filter(Boolean),
+      sourceMapMappings: sourceMaps.reduce((sum, record) => sum + (record.mappings?.length ?? 0), 0),
       projectionMode: projection.mode,
       outputMode,
+      targetPath: sourceMap?.targetPath ?? options.targetPath ?? targetProjection?.targetPath,
+      targetHash: sourceMap?.targetHash ?? options.targetHash ?? outputHash,
       sourceTarget,
       sameSourceTarget,
       targetLossClass: targetCoverage.lossClass,
@@ -447,6 +591,70 @@ export function resolveCapabilityAdapters(document, target = 'typescript', optio
     });
 }
 
+export function getNativeImportFeatureEvidencePolicy(kind) {
+  const normalized = normalizeNativeLossKind({ kind }, 'warning');
+  return NativeImportFeatureEvidencePolicies[normalized] ?? NativeImportFeatureEvidencePolicies[String(kind ?? '')];
+}
+
+export function summarizeNativeImportFeatureEvidence(losses = [], options = {}) {
+  const normalizedLosses = normalizeNativeLossRecords(losses);
+  const evidence = options.evidence ?? [];
+  const issues = [];
+  const byKind = {};
+  const byRisk = {};
+  const policyKinds = [];
+  let highestRisk = 'low';
+  let semanticMergeReadiness = 'ready';
+
+  for (const loss of normalizedLosses) {
+    const policy = getNativeImportFeatureEvidencePolicy(loss.kind);
+    if (!policy) continue;
+    byKind[policy.kind] = (byKind[policy.kind] ?? 0) + 1;
+    byRisk[policy.risk] = (byRisk[policy.risk] ?? 0) + 1;
+    if ((nativeFeatureEvidenceRiskRank[policy.risk] ?? 0) > (nativeFeatureEvidenceRiskRank[highestRisk] ?? 0)) {
+      highestRisk = policy.risk;
+    }
+    policyKinds.push(policy.kind);
+    semanticMergeReadiness = maxSemanticMergeReadiness(semanticMergeReadiness, policy.minimumReadiness);
+    const missingRequiredEvidence = policy.requiredEvidenceKeys.filter((key) => !nativeImportFeatureEvidenceHasKey(loss, evidence, key));
+    const presentRequiredEvidence = policy.requiredEvidenceKeys.filter((key) => !missingRequiredEvidence.includes(key));
+    const presentRecommendedEvidence = policy.recommendedEvidenceKeys.filter((key) => nativeImportFeatureEvidenceHasKey(loss, evidence, key));
+    if (missingRequiredEvidence.length) {
+      semanticMergeReadiness = maxSemanticMergeReadiness(semanticMergeReadiness, policy.missingEvidenceReadiness);
+    }
+    issues.push({
+      lossId: loss.id,
+      kind: loss.kind,
+      policyKind: policy.kind,
+      risk: policy.risk,
+      category: policy.category,
+      readiness: missingRequiredEvidence.length ? policy.missingEvidenceReadiness : policy.minimumReadiness,
+      missingRequiredEvidence,
+      presentRequiredEvidence,
+      presentRecommendedEvidence,
+      evidenceIds: nativeImportFeatureEvidenceIds(loss, evidence, policy)
+    });
+  }
+
+  const missingRequiredEvidence = issues.flatMap((issue) => issue.missingRequiredEvidence.map((key) => ({
+    lossId: issue.lossId,
+    kind: issue.kind,
+    policyKind: issue.policyKind,
+    evidenceKey: key
+  })));
+  return {
+    total: issues.length,
+    policyKinds: uniqueStrings(policyKinds),
+    byKind,
+    byRisk,
+    highestRisk: issues.length ? highestRisk : 'low',
+    semanticMergeReadiness,
+    missingRequiredEvidence,
+    issues,
+    reasons: nativeImportFeatureEvidenceReasons(issues)
+  };
+}
+
 export function summarizeNativeImportLosses(losses = [], options = {}) {
   const normalizedLosses = normalizeNativeLossRecords(losses);
   const bySeverity = { info: 0, warning: 0, error: 0 };
@@ -486,6 +694,9 @@ export function summarizeNativeImportLosses(losses = [], options = {}) {
     reviewLossIds,
     informationalLossIds
   });
+  const featureEvidence = summarizeNativeImportFeatureEvidence(normalizedLosses, {
+    evidence: options.evidence
+  });
 
   return {
     total: normalizedLosses.length,
@@ -501,6 +712,7 @@ export function summarizeNativeImportLosses(losses = [], options = {}) {
     reviewLossIds,
     informationalLossIds,
     failedEvidenceIds,
+    featureEvidence,
     parser: options.parser,
     scanKind: options.scanKind,
     semanticStatus: options.semanticStatus
@@ -4086,6 +4298,61 @@ function nativeImportCategoryForLossKind(kind) {
   return String(kind ?? 'opaqueNative');
 }
 
+function nativeImportFeatureEvidencePolicy(kind, input = {}) {
+  return Object.freeze({
+    kind,
+    category: input.category ?? nativeImportCategoryForLossKind(kind),
+    risk: input.risk ?? 'medium',
+    minimumReadiness: normalizeSemanticMergeReadiness(input.minimumReadiness) ?? 'needs-review',
+    missingEvidenceReadiness: normalizeSemanticMergeReadiness(input.missingEvidenceReadiness) ?? 'needs-review',
+    requiredEvidenceKeys: Object.freeze(uniqueStrings(input.requiredEvidenceKeys ?? [])),
+    recommendedEvidenceKeys: Object.freeze(uniqueStrings(input.recommendedEvidenceKeys ?? [])),
+    notes: Object.freeze(uniqueStrings(input.notes ?? []))
+  });
+}
+
+function nativeImportFeatureEvidenceHasKey(loss, evidence, key) {
+  return nativeImportFeatureEvidenceValuePresent(nativeImportFeatureEvidenceValue(loss, key))
+    || (evidence ?? []).some((record) => nativeImportFeatureEvidenceValuePresent(nativeImportFeatureEvidenceValue(record, key)));
+}
+
+function nativeImportFeatureEvidenceValue(record, key) {
+  if (!record || !key) return undefined;
+  const candidates = [record, record.metadata].filter(Boolean);
+  for (const candidate of candidates) {
+    const direct = candidate[key];
+    if (direct !== undefined) return direct;
+    const dotted = String(key).split('.').reduce((current, part) => current?.[part], candidate);
+    if (dotted !== undefined) return dotted;
+  }
+  return undefined;
+}
+
+function nativeImportFeatureEvidenceValuePresent(value) {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'string') return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.keys(value).length > 0;
+  return true;
+}
+
+function nativeImportFeatureEvidenceIds(loss, evidence, policy) {
+  const keys = [...policy.requiredEvidenceKeys, ...policy.recommendedEvidenceKeys];
+  return uniqueStrings((evidence ?? [])
+    .filter((record) => keys.some((key) => nativeImportFeatureEvidenceValuePresent(nativeImportFeatureEvidenceValue(record, key))))
+    .map((record) => record.id)
+    .filter(Boolean)
+    .concat(loss.evidenceIds ?? []));
+}
+
+function nativeImportFeatureEvidenceReasons(issues) {
+  return uniqueStrings((issues ?? []).flatMap((issue) => {
+    const missing = issue.missingRequiredEvidence ?? [];
+    if (!missing.length) return [];
+    return [`${issue.kind} loss ${issue.lossId} is missing required evidence: ${missing.join(', ')}.`];
+  }));
+}
+
 function normalizeProjectionMatrixTargets(targets) {
   return uniqueStrings((Array.isArray(targets) ? targets : [targets])
     .map((target) => {
@@ -4544,6 +4811,251 @@ function nativeSourceCompileEvidence(input) {
   };
 }
 
+function nativeSourceCompileSourceMaps(input) {
+  const adapterSourceMaps = input.targetProjection?.sourceMaps ?? [];
+  if (adapterSourceMaps.length) return adapterSourceMaps;
+  const targetPath = nativeSourceCompileTargetPath(input);
+  const targetHash = input.targetHash ?? input.outputHash;
+  const target = nativeSourceCompileMapTarget(input, targetPath);
+  const mappings = input.projection.mode === 'preserved-source'
+    ? nativeSourceCompilePreservedMappings({ ...input, targetPath, targetHash, target })
+    : nativeSourceCompileDeclarationMappings({ ...input, targetPath, targetHash, target });
+  const resolvedMappings = mappings.length
+    ? mappings
+    : [nativeSourceCompileFileMapping({ ...input, targetPath, targetHash, target })];
+  return [createSourceMapRecord({
+    id: input.id,
+    sourcePath: input.importResult.sourcePath ?? input.importResult.nativeSource?.sourcePath,
+    sourceHash: input.importResult.nativeSource?.sourceHash ?? input.importResult.nativeAst?.sourceHash ?? input.importResult.sourceHash,
+    target,
+    targetPath: targetPath ?? commonGeneratedTargetPath(resolvedMappings),
+    targetHash,
+    semanticIndexId: input.importResult.semanticIndex?.id ?? input.importResult.universalAst?.semanticIndex?.id,
+    universalAstId: input.importResult.universalAst?.id,
+    nativeAstId: input.importResult.nativeAst?.id ?? input.importResult.nativeSource?.ast?.id,
+    nativeSourceId: input.importResult.nativeSource?.id,
+    mappings: resolvedMappings,
+    evidence: input.evidence ?? [],
+    metadata: {
+      compileResultId: input.compileResultId,
+      importId: input.importResult.id,
+      projectionId: input.projection.id,
+      targetProjectionId: input.targetProjection?.id,
+      targetProjectionAdapterId: input.targetProjection?.adapter?.id,
+      sourceLanguage: input.sourceLanguage,
+      target: input.target,
+      outputMode: input.outputMode,
+      outputHash: input.outputHash,
+      generatedBy: 'compileNativeSource'
+    }
+  })];
+}
+
+function nativeSourceCompilePreservedMappings(input) {
+  const sourceMaps = input.importResult.sourceMaps ?? input.importResult.universalAst?.sourceMaps ?? [];
+  const sourceHash = input.importResult.nativeSource?.sourceHash ?? input.importResult.nativeAst?.sourceHash ?? input.importResult.sourceHash;
+  const exact = input.projection.mode === 'preserved-source' && (!input.projection.sourceHash || input.outputHash === input.projection.sourceHash);
+  const usedIds = new Set();
+  return sourceMaps
+    .flatMap((sourceMap) => sourceMap?.mappings ?? [])
+    .filter((mapping) => mapping?.sourceSpan)
+    .map((mapping, index) => ({
+      id: reserveUniqueId(`compile_map_${idFragment(mapping.id ?? mapping.semanticSymbolId ?? mapping.nativeAstNodeId ?? index + 1)}`, usedIds),
+      nativeSourceId: mapping.nativeSourceId ?? input.importResult.nativeSource?.id,
+      nativeAstNodeId: mapping.nativeAstNodeId,
+      semanticSymbolId: mapping.semanticSymbolId,
+      semanticOccurrenceId: mapping.semanticOccurrenceId,
+      semanticNodeId: mapping.semanticNodeId,
+      mergeCandidateId: mapping.mergeCandidateId,
+      sourceSpan: {
+        ...mapping.sourceSpan,
+        sourceId: mapping.sourceSpan.sourceId ?? sourceHash,
+        path: mapping.sourceSpan.path ?? input.importResult.sourcePath ?? input.importResult.nativeSource?.sourcePath
+      },
+      generatedSpan: nativeSourceCompileGeneratedSpanFromSource(mapping.sourceSpan, input, mapping.generatedName),
+      target: input.target,
+      generatedName: mapping.generatedName,
+      evidenceIds: uniqueStrings([
+        ...(mapping.evidenceIds ?? []),
+        ...(input.evidence ?? []).map((record) => record.id).filter(Boolean)
+      ]),
+      lossIds: uniqueStrings([
+        ...(mapping.lossIds ?? []),
+        ...lossIdsForNativeNode(input.losses ?? [], mapping.nativeAstNodeId)
+      ]),
+      ownershipRegionId: mapping.ownershipRegionId,
+      ownershipRegionKey: mapping.ownershipRegionKey,
+      ownershipRegionKind: mapping.ownershipRegionKind,
+      precision: exact ? 'exact' : mapping.precision === 'exact' ? 'line' : mapping.precision ?? 'line',
+      metadata: {
+        ...mapping.metadata,
+        compileResultId: input.compileResultId,
+        sourceMapOrigin: 'preserved-source'
+      }
+    }));
+}
+
+function nativeSourceCompileDeclarationMappings(input) {
+  const usedIds = new Set();
+  return (input.projection.declarations ?? []).map((declaration, index) => {
+    const generated = nativeSourceCompileDeclarationGeneratedSpan(input, declaration);
+    return {
+      id: reserveUniqueId(`compile_map_${idFragment(declaration.symbolId ?? declaration.nativeAstNodeId ?? declaration.name ?? index + 1)}`, usedIds),
+      nativeSourceId: input.importResult.nativeSource?.id,
+      nativeAstNodeId: declaration.nativeAstNodeId,
+      semanticSymbolId: declaration.symbolId,
+      sourceSpan: declaration.sourceSpan,
+      generatedSpan: generated.span,
+      target: input.target,
+      generatedName: generated.name,
+      evidenceIds: (input.evidence ?? []).map((record) => record.id).filter(Boolean),
+      lossIds: lossIdsForNativeNode(input.losses ?? [], declaration.nativeAstNodeId),
+      ownershipRegionId: declaration.ownershipRegionId,
+      ownershipRegionKey: declaration.metadata?.ownershipRegionKey,
+      ownershipRegionKind: declaration.metadata?.ownershipRegionKind,
+      precision: generated.exactName ? 'declaration' : 'estimated',
+      metadata: {
+        ...declaration.metadata,
+        compileResultId: input.compileResultId,
+        declarationKind: declaration.kind,
+        sourceMapOrigin: input.outputMode === 'target-adapter' ? 'target-adapter-fallback' : 'declaration-stub'
+      }
+    };
+  });
+}
+
+function nativeSourceCompileFileMapping(input) {
+  const rootSpan = input.importResult.nativeAst?.nodes?.[input.importResult.nativeAst?.rootId]?.span
+    ?? input.importResult.nativeSource?.ast?.nodes?.[input.importResult.nativeSource?.ast?.rootId]?.span
+    ?? input.projection.declarations?.find((declaration) => declaration.sourceSpan)?.sourceSpan;
+  return {
+    id: `compile_map_${idFragment(input.compileResultId ?? input.id)}_file`,
+    nativeSourceId: input.importResult.nativeSource?.id,
+    sourceSpan: rootSpan,
+    generatedSpan: nativeSourceCompileFullGeneratedSpan(input),
+    target: input.target,
+    evidenceIds: (input.evidence ?? []).map((record) => record.id).filter(Boolean),
+    precision: input.projection.mode === 'preserved-source' && input.outputHash === input.projection.sourceHash ? 'line' : 'estimated',
+    metadata: {
+      compileResultId: input.compileResultId,
+      sourceMapOrigin: 'file-fallback'
+    }
+  };
+}
+
+function nativeSourceCompileGeneratedSpanFromSource(sourceSpan, input, generatedName) {
+  if (!sourceSpan) return nativeSourceCompileFullGeneratedSpan(input, generatedName);
+  return {
+    ...sourceSpan,
+    sourceId: input.targetHash ?? input.outputHash,
+    path: input.targetPath,
+    target: input.target,
+    targetPath: input.targetPath,
+    targetHash: input.targetHash ?? input.outputHash,
+    generatedName
+  };
+}
+
+function nativeSourceCompileDeclarationGeneratedSpan(input, declaration) {
+  const identifiers = uniqueStrings([
+    declaration.name,
+    safeProjectionIdentifier(declaration.name),
+    upperFirst(safeProjectionIdentifier(declaration.name)),
+    safeProjectionIdentifier(declaration.name).toUpperCase()
+  ]).filter(Boolean);
+  for (const identifier of identifiers) {
+    const offset = input.output.indexOf(identifier);
+    if (offset >= 0) {
+      return {
+        name: identifier,
+        exactName: true,
+        span: nativeSourceCompileGeneratedSpanForOffset(input, offset, identifier.length, identifier)
+      };
+    }
+  }
+  return {
+    name: safeProjectionIdentifier(declaration.name),
+    exactName: false,
+    span: nativeSourceCompileFullGeneratedSpan(input, safeProjectionIdentifier(declaration.name))
+  };
+}
+
+function nativeSourceCompileGeneratedSpanForOffset(input, offset, length, generatedName) {
+  const start = lineColumnForOffset(input.output, offset);
+  const end = lineColumnForOffset(input.output, offset + Math.max(1, length));
+  return {
+    sourceId: input.targetHash ?? input.outputHash,
+    path: input.targetPath,
+    startLine: start.line,
+    startColumn: start.column,
+    endLine: end.line,
+    endColumn: end.column,
+    target: input.target,
+    targetPath: input.targetPath,
+    targetHash: input.targetHash ?? input.outputHash,
+    generatedName
+  };
+}
+
+function nativeSourceCompileFullGeneratedSpan(input, generatedName) {
+  const lines = String(input.output ?? '').split(/\r?\n/);
+  const lastLine = lines.at(-1) ?? '';
+  return {
+    sourceId: input.targetHash ?? input.outputHash,
+    path: input.targetPath,
+    startLine: 1,
+    startColumn: 1,
+    endLine: Math.max(1, lines.length),
+    endColumn: Math.max(1, lastLine.length + 1),
+    target: input.target,
+    targetPath: input.targetPath,
+    targetHash: input.targetHash ?? input.outputHash,
+    generatedName
+  };
+}
+
+function nativeSourceCompileTargetPath(input) {
+  if (input.targetPath) return input.targetPath;
+  const sourcePath = input.importResult.sourcePath ?? input.importResult.nativeSource?.sourcePath;
+  if (!sourcePath) return undefined;
+  const targetExt = nativeSourceCompileTargetExtension(input.target);
+  if (!targetExt) return sourcePath;
+  return sourcePath.replace(/(\.[^./\\]+)?$/, targetExt);
+}
+
+function nativeSourceCompileTargetExtension(target) {
+  const normalized = normalizeNativeLanguageId(target);
+  if (normalized === 'typescript') return '.ts';
+  if (normalized === 'javascript') return '.js';
+  if (normalized === 'rust') return '.rs';
+  if (normalized === 'python') return '.py';
+  if (normalized === 'c') return '.h';
+  return undefined;
+}
+
+function nativeSourceCompileMapTarget(input, targetPath) {
+  return {
+    language: input.target,
+    emitPath: targetPath
+  };
+}
+
+function lineColumnForOffset(source, offset) {
+  const text = String(source ?? '');
+  const safeOffset = Math.max(0, Math.min(offset, text.length));
+  let line = 1;
+  let column = 1;
+  for (let index = 0; index < safeOffset; index += 1) {
+    if (text[index] === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+  return { line, column };
+}
+
 function nativeProjectionTargetsForLanguage(language, aliases = []) {
   const target = nativeLanguageCompileTarget(language, aliases);
   return target ? [target] : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-compiler",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "Compiler facade for Frontier Lang source documents and language projection adapters.",
   "type": "module",
   "main": "./dist/index.js",