@shapeshift-labs/frontier-lang-compiler 0.2.12 → 0.2.14

package/README.md

@@ -57,6 +57,7 @@ Ask the compiler what is actually covered before sending native imports into a m
 ```js
 import {
   createNativeImportCoverageMatrix,
+  createProjectionTargetLossMatrix,
   importNativeSource
 } from '@shapeshift-labs/frontier-lang-compiler';
 
@@ -71,8 +72,22 @@ const python = matrix.languages.find((entry) => entry.language === 'python');
 
 console.log(python.imports.readiness); // scanner imports are intentionally review-required
 console.log(python.parserAdapters); // host-owned exact parsers such as LibCST can be injected
+
+const projectionMatrix = createProjectionTargetLossMatrix({ imports: [imported] });
+const pythonProjection = projectionMatrix.languages.find((entry) => entry.language === 'python');
+
+console.log(pythonProjection.sourceProjection.exactSource.lossClass); // "exactSourceProjection"
+console.log(pythonProjection.sourceProjection.stubs.lossClass); // "nativeSourceStubs"
+console.log(pythonProjection.targets.find((entry) => entry.target === 'rust').lossClass); // "missingAdapter"
 ```
 
+The projection target matrix separates four runtime/API classes:
+
+- `exactSourceProjection`: exact source can be emitted when the import carries matching source text or source-preservation evidence.
+- `nativeSourceStubs`: declaration stubs can be emitted, but bodies, resolved types, and executable semantics are review-required.
+- `unsupportedTargetFeatures`: a target slot exists, but the source profile or import evidence declares features such as macros, preprocessors, dynamic runtime behavior, generated code, unsupported syntax, or unresolved inference that this facade cannot prove lossless.
+- `missingAdapter`: no native-to-target projection adapter is declared; preserve or stub the original source language instead, or inject host-owned parser/semantic adapter evidence.
+
 Preserve exact native source text, token/trivia hashes, comments, whitespace, and source directives as evidence. This does not claim full semantic understanding; it keeps round-trip material available while exact parser adapters catch up:
 
 ```js
@@ -171,6 +186,9 @@ const project = await importNativeProject({
 console.log(imported.universalAst.sourceMaps.length);
 console.log(project.semanticIndex.symbols.length);
 console.log(imported.adapter.coverage.exactness);
+console.log(imported.adapter.coverage.capabilityEvidence.declared.exactness);
+console.log(imported.adapter.coverage.capabilityEvidence.observed.sourceRanges);
+console.log(imported.adapter.coverage.capabilityEvidence.gaps);
 console.log(imported.adapter.coverage.semanticCoverage.level);
 console.log(project.metadata.sourcePreservationSummary.total);
 ```
@@ -184,6 +202,8 @@ The built-in adapter factories are dependency-light wrappers for caller-owned pa
 
 Adapter summaries include a structured `coverage` record so merge queues can distinguish exact parser AST imports from declaration scans. The record declares exactness, parser token/trivia support, diagnostics support, source-range and generated-range support, and semantic coverage. Built-in wrappers normalize native AST/CST nodes and declaration-level semantic indexes; they do not claim resolved references, types, control flow, generated ranges, or token/trivia fidelity unless the host adapter supplies that evidence.
 
+Coverage records also keep declared, observed, and effective capability evidence separate. `coverage.capabilityEvidence.gaps` highlights missing exact AST, token/trivia, parser diagnostics, source range, generated range, reference, type, and control-flow evidence for the current adapter/import. `observedOnly` means the import produced evidence the adapter did not declare, while `declaredOnly` means the adapter declared support that this run did not exercise.
+
 ## Related Packages
 
 The published Frontier package family is generated from one shared package catalog so READMEs stay in sync across packages:

package/bench/smoke.mjs

@@ -3,6 +3,7 @@ import {
   compileFrontierSource,
   createEstreeNativeImporterAdapter,
   createNativeImportCoverageMatrix,
+  createProjectionTargetLossMatrix,
   createNativeSourcePreservation,
   createSemanticImportSidecar,
   importNativeSource,
@@ -68,6 +69,10 @@ const matrixStart = performance.now();
 const coverageMatrix = createNativeImportCoverageMatrix({ imports: nativeImportResults });
 const matrixDurationMs = performance.now() - matrixStart;
 
+const projectionMatrixStart = performance.now();
+const projectionLossMatrix = createProjectionTargetLossMatrix({ imports: nativeImportResults });
+const projectionMatrixDurationMs = performance.now() - projectionMatrixStart;
+
 const preservationStart = performance.now();
 const preservationRecords = nativeImportResults.map((imported) => imported.metadata.sourcePreservation ?? createNativeSourcePreservation({
   language: imported.language,
@@ -96,7 +101,15 @@ console.log(JSON.stringify({
   nativeImportDurationMs: Number(importDurationMs.toFixed(2)),
   coverageMatrixLanguages: coverageMatrix.summary.languages,
   coverageMatrixImports: coverageMatrix.summary.imports,
+  adapterCoverageSummaries: coverageMatrix.summary.adapterCoverage.total,
+  adapterCoverageSourceRanges: coverageMatrix.summary.adapterCoverage.effective.sourceRanges ?? 0,
+  adapterCoverageTokenGaps: coverageMatrix.summary.adapterCoverage.gaps.tokens ?? 0,
+  adapterCoverageReferenceGaps: coverageMatrix.summary.adapterCoverage.gaps.references ?? 0,
   coverageMatrixDurationMs: Number(matrixDurationMs.toFixed(2)),
+  projectionMatrixLanguages: projectionLossMatrix.summary.languages,
+  projectionMatrixMissingAdapters: projectionLossMatrix.summary.missingAdapters,
+  projectionMatrixUnsupportedTargetFeatures: projectionLossMatrix.summary.unsupportedTargetFeatures,
+  projectionMatrixDurationMs: Number(projectionMatrixDurationMs.toFixed(2)),
   sourcePreservationRecords: preservationRecords.length,
   sourcePreservationTokens: preservationTokens,
   sourcePreservationDurationMs: Number(preservationDurationMs.toFixed(2)),

package/dist/index.d.ts

@@ -168,22 +168,45 @@ export interface NativeImportLanguageProfile {
   readonly extensions: readonly string[];
   readonly supportsLightweightScan: boolean;
   readonly parserAdapters: readonly string[];
-  readonly projectionTargets: readonly FrontierCompileTarget[];
+  readonly projectionTargets: readonly (FrontierCompileTarget | string)[];
   readonly knownLossKinds: readonly NativeImportKnownLossKind[];
   readonly defaultReadiness: SemanticMergeReadiness;
   readonly notes: readonly string[];
 }
 
+export interface NativeImporterAdapterCoverageAggregate {
+  readonly total: number;
+  readonly declared: Readonly<Record<string, number>>;
+  readonly observed: Readonly<Record<string, number>>;
+  readonly effective: Readonly<Record<string, number>>;
+  readonly gaps: Readonly<Record<string, number>>;
+  readonly declaredOnly: Readonly<Record<string, number>>;
+  readonly observedOnly: Readonly<Record<string, number>>;
+  readonly summaries: readonly {
+    readonly adapterId?: string;
+    readonly language?: FrontierSourceLanguage | string;
+    readonly parser?: string;
+    readonly exactness?: NativeImporterAdapterExactness;
+    readonly declared: readonly string[];
+    readonly observed: readonly string[];
+    readonly effective: readonly string[];
+    readonly gaps: readonly string[];
+    readonly declaredOnly: readonly string[];
+    readonly observedOnly: readonly string[];
+  }[];
+}
+
 export interface NativeImportCoverageLanguage {
   readonly language: FrontierSourceLanguage;
   readonly aliases: readonly string[];
   readonly extensions: readonly string[];
   readonly supportsLightweightScan: boolean;
   readonly parserAdapters: readonly string[];
-  readonly projectionTargets: readonly FrontierCompileTarget[];
+  readonly projectionTargets: readonly (FrontierCompileTarget | string)[];
   readonly knownLossKinds: readonly NativeImportKnownLossKind[];
   readonly defaultReadiness: SemanticMergeReadiness;
   readonly notes: readonly string[];
+  readonly adapterCoverage: NativeImporterAdapterCoverageAggregate;
   readonly imports: {
     readonly total: number;
     readonly parsers: readonly string[];
@@ -214,9 +237,11 @@ export interface NativeImportCoverageMatrix {
     readonly losses: number;
     readonly byReadiness: Readonly<Record<string, number>>;
     readonly lossKinds: Readonly<Record<string, number>>;
+    readonly adapterCoverage: NativeImporterAdapterCoverageAggregate;
   };
   readonly metadata: {
     readonly compileTargets: readonly FrontierCompileTarget[];
+    readonly projectionTargetLossClasses: readonly ProjectionTargetLossClass[];
     readonly note: string;
   };
 }
@@ -228,6 +253,96 @@ export interface NativeImportCoverageMatrixOptions {
   readonly generatedAt?: number;
 }
 
+export type ProjectionTargetLossClass =
+  | 'exactSourceProjection'
+  | 'nativeSourceStubs'
+  | 'unsupportedTargetFeatures'
+  | 'missingAdapter'
+  | string;
+
+export interface ProjectionSourceProjectionCoverage {
+  readonly lossClass: ProjectionTargetLossClass;
+  readonly mode: NativeSourceProjectionMode;
+  readonly supported: boolean;
+  readonly readiness: SemanticMergeReadiness;
+  readonly lossKinds: readonly NativeImportKnownLossKind[];
+  readonly categories: readonly NativeImportTaxonomyKind[];
+  readonly reason: string;
+  readonly evidence: {
+    readonly imports: number;
+    readonly importsWithExactSource?: number;
+    readonly importsWithDeclarations?: number;
+  };
+  readonly notes: readonly string[];
+}
+
+export interface ProjectionTargetCoverageEntry {
+  readonly target: FrontierCompileTarget | string;
+  readonly lossClass: ProjectionTargetLossClass;
+  readonly supported: boolean;
+  readonly readiness: SemanticMergeReadiness;
+  readonly lossKinds: readonly NativeImportKnownLossKind[];
+  readonly categories: readonly NativeImportTaxonomyKind[];
+  readonly reason: string;
+  readonly adapter?: string;
+  readonly notes: readonly string[];
+}
+
+export interface ProjectionTargetLanguageCoverage {
+  readonly language: FrontierSourceLanguage | string;
+  readonly aliases: readonly string[];
+  readonly extensions: readonly string[];
+  readonly supportsLightweightScan: boolean;
+  readonly parserAdapters: readonly string[];
+  readonly projectionTargets: readonly (FrontierCompileTarget | string)[];
+  readonly knownLossKinds: readonly NativeImportKnownLossKind[];
+  readonly defaultReadiness: SemanticMergeReadiness;
+  readonly notes: readonly string[];
+  readonly sourceProjection: {
+    readonly exactSource: ProjectionSourceProjectionCoverage;
+    readonly stubs: ProjectionSourceProjectionCoverage;
+  };
+  readonly targets: readonly ProjectionTargetCoverageEntry[];
+  readonly summary: {
+    readonly imports: number;
+    readonly parserAdapters: number;
+    readonly targetEntries: number;
+    readonly byLossClass: Readonly<Record<ProjectionTargetLossClass, number>>;
+    readonly exactSourceImports: number;
+    readonly stubDeclarationImports: number;
+  };
+}
+
+export interface ProjectionTargetLossMatrix {
+  readonly kind: 'frontier.lang.projectionTargetLossMatrix';
+  readonly version: 1;
+  readonly generatedAt: number;
+  readonly languages: readonly ProjectionTargetLanguageCoverage[];
+  readonly summary: {
+    readonly languages: number;
+    readonly targetEntries: number;
+    readonly byLossClass: Readonly<Record<ProjectionTargetLossClass, number>>;
+    readonly sourceProjectionByLossClass: Readonly<Record<ProjectionTargetLossClass, number>>;
+    readonly exactSourceProjection: number;
+    readonly nativeSourceStubs: number;
+    readonly unsupportedTargetFeatures: number;
+    readonly missingAdapters: number;
+  };
+  readonly metadata: {
+    readonly compileTargets: readonly (FrontierCompileTarget | string)[];
+    readonly lossClasses: readonly ProjectionTargetLossClass[];
+    readonly note: string;
+  };
+}
+
+export interface ProjectionTargetLossMatrixOptions {
+  readonly languages?: readonly NativeImportLanguageProfile[];
+  readonly imports?: readonly NativeSourceImportResult[];
+  readonly adapters?: readonly NativeImporterAdapter[];
+  readonly targets?: readonly (FrontierCompileTarget | string)[];
+  readonly generatedAt?: number;
+}
+
 export interface NativeImportContractSource {
   readonly id: string;
   readonly language?: FrontierSourceLanguage | string;
@@ -618,14 +733,97 @@ export interface NativeImporterAdapterSemanticCoverage {
   readonly controlFlow: boolean;
 }
 
+export interface NativeImporterAdapterCoverageSnapshot {
+  readonly exactness: NativeImporterAdapterExactness;
+  readonly exactAst: boolean;
+  readonly tokens: boolean;
+  readonly trivia: boolean;
+  readonly diagnostics: boolean;
+  readonly sourceRanges: boolean;
+  readonly generatedRanges: boolean;
+  readonly semanticCoverage: NativeImporterAdapterSemanticCoverage;
+}
+
 export interface NativeImporterAdapterCoverageObserved {
+  readonly exactness?: NativeImporterAdapterExactness;
+  readonly exactAst?: boolean;
+  readonly tokens?: boolean;
+  readonly tokenCount?: number;
+  readonly trivia?: boolean;
+  readonly triviaCount?: number;
   readonly diagnostics: number;
+  readonly parserDiagnostics?: number;
+  readonly diagnosticErrors?: number;
+  readonly diagnosticWarnings?: number;
+  readonly diagnosticInfos?: number;
   readonly losses: number;
   readonly nativeAstNodes: number;
   readonly semanticSymbols: number;
+  readonly semanticReferences?: number;
+  readonly semanticTypes?: number;
+  readonly semanticControlFlow?: number;
+  readonly references?: boolean;
+  readonly types?: boolean;
+  readonly controlFlow?: boolean;
   readonly sourceMapMappings: number;
   readonly sourceRanges: boolean;
+  readonly sourceRangeNodes?: number;
+  readonly sourceRangeMappings?: number;
   readonly generatedRanges: boolean;
+  readonly generatedRangeMappings?: number;
+  readonly semanticCoverage?: NativeImporterAdapterSemanticCoverage;
+}
+
+export interface NativeImporterAdapterCoverageCapabilityRow {
+  readonly capability: string;
+  readonly declared: boolean;
+  readonly observed: boolean;
+  readonly effective: boolean;
+  readonly count: number;
+  readonly status: 'declared-and-observed' | 'declared-unobserved' | 'observed-undeclared' | 'absent';
+}
+
+export interface NativeImporterAdapterCoverageCapabilityEvidence {
+  readonly declared: NativeImporterAdapterCoverageSnapshot;
+  readonly observed: NativeImporterAdapterCoverageObserved;
+  readonly effective: NativeImporterAdapterCoverageSnapshot;
+  readonly capabilities: readonly NativeImporterAdapterCoverageCapabilityRow[];
+  readonly gaps: readonly string[];
+  readonly declaredOnly: readonly string[];
+  readonly observedOnly: readonly string[];
+  readonly parserDiagnostics: {
+    readonly declared: boolean;
+    readonly observed: boolean;
+    readonly count: number;
+    readonly errors: number;
+    readonly warnings: number;
+    readonly infos: number;
+  };
+  readonly sourceRanges: {
+    readonly declared: boolean;
+    readonly observed: boolean;
+    readonly nativeAstNodes: number;
+    readonly sourceRangeNodes: number;
+    readonly sourceMapMappings: number;
+    readonly sourceRangeMappings: number;
+    readonly generatedRangeMappings: number;
+  };
+  readonly tokensTrivia: {
+    readonly tokens: { readonly declared: boolean; readonly observed: boolean; readonly count: number };
+    readonly trivia: { readonly declared: boolean; readonly observed: boolean; readonly count: number };
+  };
+  readonly semantic: {
+    readonly level: {
+      readonly declared: string;
+      readonly observed: string;
+      readonly effective: string;
+    };
+    readonly declarations: NativeImporterAdapterCoverageCapabilityRow;
+    readonly symbols: NativeImporterAdapterCoverageCapabilityRow;
+    readonly references: NativeImporterAdapterCoverageCapabilityRow;
+    readonly types: NativeImporterAdapterCoverageCapabilityRow;
+    readonly controlFlow: NativeImporterAdapterCoverageCapabilityRow;
+  };
 }
 
 export interface NativeImporterAdapterCoverageSummary {
@@ -638,11 +836,13 @@ export interface NativeImporterAdapterCoverageSummary {
   readonly generatedRanges: boolean;
   readonly semanticCoverage: NativeImporterAdapterSemanticCoverage;
   readonly notes: readonly string[];
+  readonly declared?: NativeImporterAdapterCoverageSnapshot;
   readonly observed?: NativeImporterAdapterCoverageObserved;
+  readonly capabilityEvidence?: NativeImporterAdapterCoverageCapabilityEvidence;
 }
 
 export type NativeImporterAdapterCoverageInput =
-  Omit<Partial<NativeImporterAdapterCoverageSummary>, 'semanticCoverage' | 'observed'> & {
+  Omit<Partial<NativeImporterAdapterCoverageSummary>, 'semanticCoverage' | 'observed' | 'declared' | 'capabilityEvidence'> & {
     readonly semanticCoverage?: Partial<NativeImporterAdapterSemanticCoverage>;
     readonly observed?: Partial<NativeImporterAdapterCoverageObserved>;
   };
@@ -972,6 +1172,7 @@ export declare const NativeImportRoundtripReadinessStatuses: readonly NativeImpo
 export declare const NativeImportTaxonomyKinds: readonly NativeImportTaxonomyKind[];
 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 NativeImportLanguageProfiles: readonly NativeImportLanguageProfile[];
 export declare function normalizeCompileTarget(target?: string): FrontierCompileTarget;
@@ -984,6 +1185,7 @@ export declare function summarizeNativeImportLosses(losses?: readonly NativeAstL
 export declare function classifyNativeImportReadiness(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportReadinessClassification;
 export declare function classifyNativeImportRoundtripReadiness(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: NativeImportRoundtripReadinessOptions): NativeImportRoundtripReadinessClassification;
 export declare function createNativeImportCoverageMatrix(options?: NativeImportCoverageMatrixOptions): NativeImportCoverageMatrix;
+export declare function createProjectionTargetLossMatrix(options?: ProjectionTargetLossMatrixOptions): ProjectionTargetLossMatrix;
 export declare function createNativeSourcePreservation(options: CreateNativeSourcePreservationOptions): NativeSourcePreservation;
 export declare function createSemanticImportSidecar(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: SemanticImportSidecarOptions): SemanticImportSidecar;
 export declare function createNativeImportResultContract(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: NativeImportResultContractOptions): NativeImportResultContract;

package/dist/index.js

@@ -138,6 +138,13 @@ export const NativeImportRegionTaxonomyKinds = Object.freeze([
   'generatedOutput'
 ]);
 
+export const ProjectionTargetLossClasses = Object.freeze([
+  'exactSourceProjection',
+  'nativeSourceStubs',
+  'unsupportedTargetFeatures',
+  'missingAdapter'
+]);
+
 export const NativeImportLanguageProfiles = Object.freeze([
   nativeImportLanguageProfile('javascript', {
     aliases: ['js', 'mjs', 'cjs', 'jsx'],
@@ -493,6 +500,7 @@ export function createNativeImportCoverageMatrix(input = {}) {
     for (const [kind, count] of Object.entries(entry.imports.lossKinds)) {
       totals.lossKinds[kind] = (totals.lossKinds[kind] ?? 0) + count;
     }
+    totals.adapterCoverage = mergeNativeImporterAdapterCoverageAggregates(totals.adapterCoverage, entry.adapterCoverage);
     return totals;
   }, {
     languages: 0,
@@ -504,7 +512,8 @@ export function createNativeImportCoverageMatrix(input = {}) {
     sourceMapMappings: 0,
     losses: 0,
     byReadiness: {},
-    lossKinds: {}
+    lossKinds: {},
+    adapterCoverage: emptyNativeImporterAdapterCoverageAggregate()
   });
   return {
     kind: 'frontier.lang.nativeImportCoverageMatrix',
@@ -514,11 +523,37 @@ export function createNativeImportCoverageMatrix(input = {}) {
     summary,
     metadata: {
       compileTargets: [...FrontierCompileTargets],
+      projectionTargetLossClasses: [...ProjectionTargetLossClasses],
       note: 'Coverage is evidence and capability metadata, not a claim that every language feature is losslessly portable.'
     }
   };
 }
 
+export function createProjectionTargetLossMatrix(input = {}) {
+  const imports = input.imports ?? [];
+  const adapters = input.adapters ?? [];
+  const profiles = mergeNativeImportProfiles(input.languages ?? NativeImportLanguageProfiles, imports, adapters);
+  const targets = normalizeProjectionMatrixTargets(input.targets ?? FrontierCompileTargets);
+  const languages = profiles.map((profile) => projectionTargetCoverageForProfile(profile, {
+    imports,
+    adapters,
+    targets
+  }));
+  const summary = projectionTargetLossMatrixSummary(languages);
+  return {
+    kind: 'frontier.lang.projectionTargetLossMatrix',
+    version: 1,
+    generatedAt: input.generatedAt ?? Date.now(),
+    languages,
+    summary,
+    metadata: {
+      compileTargets: targets,
+      lossClasses: [...ProjectionTargetLossClasses],
+      note: 'Projection target coverage separates exact source preservation, declaration stubs, known unsupported target features, and missing native-to-target adapters.'
+    }
+  };
+}
+
 export function createNativeSourcePreservation(options) {
   if (!options || typeof options.sourceText !== 'string') {
     throw new Error('createNativeSourcePreservation requires sourceText');
@@ -3369,15 +3404,273 @@ function nativeImportCategoryForLossKind(kind) {
   return String(kind ?? 'opaqueNative');
 }
 
+function normalizeProjectionMatrixTargets(targets) {
+  return uniqueStrings((Array.isArray(targets) ? targets : [targets])
+    .map((target) => {
+      if (target === undefined || target === null) return undefined;
+      try {
+        return normalizeCompileTarget(target);
+      } catch {
+        return String(target).trim().toLowerCase();
+      }
+    })
+    .filter(Boolean));
+}
+
+function projectionTargetCoverageForProfile(profile, context) {
+  const aliases = new Set([profile.language, ...(profile.aliases ?? [])].map(normalizeNativeLanguageId).filter(Boolean));
+  const matchingImports = (context.imports ?? []).filter((imported) => aliases.has(normalizeNativeLanguageId(imported?.language ?? imported?.nativeAst?.language)));
+  const matchingAdapters = (context.adapters ?? []).filter((adapter) => aliases.has(normalizeNativeLanguageId(adapter?.language)));
+  const importedLossKinds = uniqueStrings(matchingImports.flatMap((imported) => (imported?.losses ?? []).map((loss) => loss.kind).filter(Boolean)));
+  const knownLossKinds = uniqueStrings([...(profile.knownLossKinds ?? []), ...importedLossKinds]);
+  const parserAdapters = uniqueStrings([
+    ...(profile.parserAdapters ?? []),
+    ...matchingAdapters.map((adapter) => adapter.parser ?? adapter.id).filter(Boolean)
+  ]);
+  const sourceProjection = sourceProjectionCoverageForProfile(profile, matchingImports, knownLossKinds);
+  const targets = (context.targets ?? FrontierCompileTargets).map((target) => projectionTargetCoverageEntry(profile, target, {
+    matchingImports,
+    matchingAdapters,
+    knownLossKinds
+  }));
+  return {
+    language: profile.language,
+    aliases: profile.aliases,
+    extensions: profile.extensions,
+    supportsLightweightScan: profile.supportsLightweightScan,
+    parserAdapters,
+    projectionTargets: profile.projectionTargets,
+    knownLossKinds,
+    defaultReadiness: profile.defaultReadiness,
+    notes: profile.notes,
+    sourceProjection,
+    targets,
+    summary: {
+      imports: matchingImports.length,
+      parserAdapters: parserAdapters.length,
+      targetEntries: targets.length,
+      byLossClass: countProjectionLossClasses(targets),
+      exactSourceImports: sourceProjection.exactSource.evidence.importsWithExactSource,
+      stubDeclarationImports: sourceProjection.stubs.evidence.importsWithDeclarations
+    }
+  };
+}
+
+function sourceProjectionCoverageForProfile(profile, imports, knownLossKinds) {
+  const exactSourceImports = imports.filter(hasExactSourceProjectionEvidence).length;
+  const declarationImports = imports.filter(hasNativeProjectionDeclarations).length;
+  return {
+    exactSource: {
+      lossClass: 'exactSourceProjection',
+      mode: 'preserved-source',
+      supported: true,
+      readiness: 'ready',
+      lossKinds: [],
+      categories: [],
+      reason: exactSourceImports
+        ? 'At least one import carries matching source-preservation evidence, so projectNativeImportToSource can emit the original source exactly.'
+        : 'Exact source projection is available when the import carries sourceText or source-preservation evidence whose hash matches the native source hash.',
+      evidence: {
+        imports: imports.length,
+        importsWithExactSource: exactSourceImports
+      },
+      notes: ['Preserved source is the only currently lossless native-source projection mode in this facade.']
+    },
+    stubs: {
+      lossClass: 'nativeSourceStubs',
+      mode: 'native-source-stubs',
+      supported: profile.supportsLightweightScan || declarationImports > 0,
+      readiness: 'needs-review',
+      lossKinds: uniqueStrings([
+        'targetProjectionLoss',
+        ...(declarationImports || profile.supportsLightweightScan ? [] : ['declarationOnlyCoverage'])
+      ]),
+      categories: uniqueStrings([
+        'targetProjectionLoss',
+        ...(declarationImports || profile.supportsLightweightScan ? [] : ['declarationsOnly'])
+      ]),
+      reason: 'Declaration stubs are emitted when exact source is unavailable or disabled; executable bodies and full type semantics remain unavailable.',
+      evidence: {
+        imports: imports.length,
+        importsWithDeclarations: declarationImports
+      },
+      notes: uniqueStrings([
+        'Stub projection is review-required and should not be treated as a round-trip proof.',
+        ...(projectionUnsupportedFeatureLossKinds(knownLossKinds).length
+          ? ['Known source-language feature losses may still be present behind preserved source or stubs.']
+          : [])
+      ])
+    }
+  };
+}
+
+function projectionTargetCoverageEntry(profile, target, context) {
+  const normalizedTarget = normalizeProjectionMatrixTargets([target])[0] ?? String(target);
+  const declaredTargets = new Set(normalizeProjectionMatrixTargets(profile.projectionTargets ?? []));
+  const adapterTargets = new Set((context.matchingAdapters ?? []).flatMap(adapterProjectionTargets));
+  const sameSourceTarget = nativeLanguageCompileTarget(profile.language, profile.aliases) === normalizedTarget;
+  const hasProjectionAdapter = declaredTargets.has(normalizedTarget) || adapterTargets.has(normalizedTarget);
+  if (!hasProjectionAdapter) {
+    return {
+      target: normalizedTarget,
+      lossClass: 'missingAdapter',
+      supported: false,
+      readiness: 'blocked',
+      lossKinds: ['targetProjectionLoss'],
+      categories: ['targetProjectionLoss'],
+      reason: `No native-to-${normalizedTarget} projection adapter is declared for ${profile.language}.`,
+      adapter: undefined,
+      notes: ['The source can still be preserved or stubbed in its original language when import evidence supports that mode.']
+    };
+  }
+
+  const featureLossKinds = projectionUnsupportedFeatureLossKinds(context.knownLossKinds);
+  if (featureLossKinds.length) {
+    return {
+      target: normalizedTarget,
+      lossClass: 'unsupportedTargetFeatures',
+      supported: true,
+      readiness: 'needs-review',
+      lossKinds: featureLossKinds,
+      categories: uniqueStrings(featureLossKinds.map(nativeImportCategoryForLossKind)),
+      reason: `${profile.language} coverage declares source features that this facade cannot prove lossless for ${normalizedTarget}: ${featureLossKinds.join(', ')}.`,
+      adapter: projectionTargetAdapterName(profile, normalizedTarget, context.matchingAdapters),
+      notes: ['Use exact parser or semantic adapter evidence before treating this target projection as merge-ready.']
+    };
+  }
+
+  if (sameSourceTarget) {
+    return {
+      target: normalizedTarget,
+      lossClass: 'exactSourceProjection',
+      supported: true,
+      readiness: 'ready',
+      lossKinds: [],
+      categories: [],
+      reason: `${profile.language} can project to its source language exactly when source preservation evidence is available.`,
+      adapter: projectionTargetAdapterName(profile, normalizedTarget, context.matchingAdapters),
+      notes: ['Without exact source text, the source projection falls back to declaration stubs.']
+    };
+  }
+
+  return {
+    target: normalizedTarget,
+    lossClass: 'nativeSourceStubs',
+    supported: true,
+    readiness: 'needs-review',
+    lossKinds: ['targetProjectionLoss'],
+    categories: ['targetProjectionLoss'],
+    reason: `${profile.language} declares a ${normalizedTarget} target slot, but this facade only exposes declaration-level native import projection evidence.`,
+    adapter: projectionTargetAdapterName(profile, normalizedTarget, context.matchingAdapters),
+    notes: ['Host-owned semantic adapters can upgrade this cell with stronger evidence.']
+  };
+}
+
+function projectionTargetLossMatrixSummary(languages) {
+  const byLossClass = {};
+  const sourceProjectionByLossClass = {};
+  let targetEntries = 0;
+  for (const language of languages) {
+    for (const projection of [language.sourceProjection?.exactSource, language.sourceProjection?.stubs].filter(Boolean)) {
+      sourceProjectionByLossClass[projection.lossClass] = (sourceProjectionByLossClass[projection.lossClass] ?? 0) + 1;
+    }
+    for (const target of language.targets ?? []) {
+      targetEntries += 1;
+      byLossClass[target.lossClass] = (byLossClass[target.lossClass] ?? 0) + 1;
+    }
+  }
+  return {
+    languages: languages.length,
+    targetEntries,
+    byLossClass,
+    sourceProjectionByLossClass,
+    exactSourceProjection: (sourceProjectionByLossClass.exactSourceProjection ?? 0) + (byLossClass.exactSourceProjection ?? 0),
+    nativeSourceStubs: (sourceProjectionByLossClass.nativeSourceStubs ?? 0) + (byLossClass.nativeSourceStubs ?? 0),
+    unsupportedTargetFeatures: byLossClass.unsupportedTargetFeatures ?? 0,
+    missingAdapters: byLossClass.missingAdapter ?? 0
+  };
+}
+
+function countProjectionLossClasses(entries) {
+  const counts = {};
+  for (const entry of entries ?? []) {
+    counts[entry.lossClass] = (counts[entry.lossClass] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function hasExactSourceProjectionEvidence(imported) {
+  const preservation = imported?.metadata?.sourcePreservation
+    ?? imported?.nativeSource?.metadata?.sourcePreservation
+    ?? imported?.nativeAst?.metadata?.sourcePreservation;
+  const expectedHash = imported?.nativeSource?.sourceHash ?? imported?.nativeAst?.sourceHash ?? imported?.sourceHash;
+  return Boolean(preservation?.summary?.exactSourceAvailable && (!expectedHash || preservation.sourceHash === expectedHash));
+}
+
+function hasNativeProjectionDeclarations(imported) {
+  const semanticIndex = imported?.semanticIndex ?? imported?.universalAst?.semanticIndex;
+  return (semanticIndex?.symbols?.length ?? 0) > 0;
+}
+
+function projectionUnsupportedFeatureLossKinds(lossKinds) {
+  const unsupported = new Set([
+    'macroExpansion',
+    'macroHygiene',
+    'preprocessor',
+    'conditionalCompilation',
+    'metaprogramming',
+    'reflection',
+    'dynamicRuntime',
+    'dynamicDispatch',
+    'generatedCode',
+    'overloadResolution',
+    'typeInference',
+    'unsupportedSyntax',
+    'unsupportedSemantic'
+  ]);
+  return uniqueStrings((lossKinds ?? []).filter((kind) => unsupported.has(kind)));
+}
+
+function adapterProjectionTargets(adapter) {
+  return normalizeProjectionMatrixTargets(
+    adapter?.projectionTargets
+      ?? adapter?.coverage?.projectionTargets
+      ?? adapter?.metadata?.projectionTargets
+      ?? []
+  );
+}
+
+function projectionTargetAdapterName(profile, target, adapters = []) {
+  const adapter = adapters.find((candidate) => adapterProjectionTargets(candidate).includes(target));
+  if (adapter) return adapter.id ?? adapter.parser;
+  return profile.projectionTargets?.includes(target) ? `frontier-native-source-${target}` : undefined;
+}
+
+function nativeLanguageCompileTarget(language, aliases = []) {
+  const ids = [language, ...aliases].map(normalizeNativeLanguageId);
+  if (ids.includes('typescript')) return 'typescript';
+  if (ids.includes('javascript')) return 'javascript';
+  if (ids.includes('rust')) return 'rust';
+  if (ids.includes('python')) return 'python';
+  if (ids.includes('c')) return 'c';
+  return undefined;
+}
+
+function nativeProjectionTargetsForLanguage(language, aliases = []) {
+  const target = nativeLanguageCompileTarget(language, aliases);
+  return target ? [target] : [];
+}
+
 function nativeImportLanguageProfile(language, input = {}) {
   const lossKinds = input.lossKinds ?? ['declarationOnlyCoverage', 'opaqueNative', 'sourceMapApproximation', 'sourcePreservation'];
+  const aliases = uniqueStrings(input.aliases ?? []);
   return Object.freeze({
     language,
-    aliases: Object.freeze(uniqueStrings(input.aliases ?? [])),
+    aliases: Object.freeze(aliases),
     extensions: Object.freeze(uniqueStrings(input.extensions ?? [])),
     supportsLightweightScan: input.supportsLightweightScan !== false,
     parserAdapters: Object.freeze(uniqueStrings(input.parserAdapters ?? ['tree-sitter'])),
-    projectionTargets: Object.freeze(uniqueStrings(input.projectionTargets ?? FrontierCompileTargets)),
+    projectionTargets: Object.freeze(uniqueStrings(input.projectionTargets ?? nativeProjectionTargetsForLanguage(language, aliases))),
     knownLossKinds: Object.freeze(uniqueStrings(lossKinds)),
     defaultReadiness: input.defaultReadiness ?? 'needs-review',
     notes: Object.freeze(uniqueStrings(input.notes ?? ['lightweight scanner records declarations only; exact parser adapters must be injected by the host']))
@@ -3421,7 +3714,7 @@ function normalizeNativeImportLanguageProfile(profile, fallbackLanguage) {
     extensions: uniqueStrings(profile.extensions ?? []),
     supportsLightweightScan: profile.supportsLightweightScan !== false,
     parserAdapters: uniqueStrings(profile.parserAdapters ?? []),
-    projectionTargets: uniqueStrings(profile.projectionTargets ?? FrontierCompileTargets),
+    projectionTargets: uniqueStrings(profile.projectionTargets ?? nativeProjectionTargetsForLanguage(language, profile.aliases ?? [])),
     knownLossKinds: uniqueStrings(profile.knownLossKinds ?? profile.lossKinds ?? []),
     defaultReadiness: profile.defaultReadiness ?? 'needs-review',
     notes: uniqueStrings(profile.notes ?? [])
@@ -3440,6 +3733,10 @@ function nativeImportCoverageForProfile(profile, imports, adapters) {
     : profile.supportsLightweightScan ? profile.defaultReadiness : 'blocked';
   const importedParsers = uniqueStrings(matchingImports.map((imported) => imported?.nativeAst?.parser ?? imported?.parser ?? imported?.metadata?.parser).filter(Boolean));
   const sourceMaps = matchingImports.flatMap((imported) => imported?.sourceMaps ?? imported?.universalAst?.sourceMaps ?? []);
+  const adapterCoverage = summarizeNativeImporterAdapterCoverageEntries([
+    ...matchingImports.map((imported) => nativeImporterAdapterCoverageEntryFromImport(imported)).filter(Boolean),
+    ...matchingAdapters.map((adapter) => nativeImporterAdapterCoverageEntryFromAdapter(adapter)).filter(Boolean)
+  ]);
   return {
     language: profile.language,
     aliases: profile.aliases,
@@ -3450,6 +3747,7 @@ function nativeImportCoverageForProfile(profile, imports, adapters) {
     knownLossKinds: uniqueStrings([...(profile.knownLossKinds ?? []), ...Object.keys(lossSummary.byKind)]),
     defaultReadiness: profile.defaultReadiness,
     notes: profile.notes,
+    adapterCoverage,
     imports: {
       total: matchingImports.length,
       parsers: importedParsers,
@@ -3465,6 +3763,125 @@ function nativeImportCoverageForProfile(profile, imports, adapters) {
   };
 }
 
+function nativeImporterAdapterCoverageEntryFromImport(imported) {
+  const coverage = imported?.adapter?.coverage
+    ?? imported?.metadata?.adapterCoverage
+    ?? imported?.nativeAst?.metadata?.adapterCoverage
+    ?? imported?.nativeSource?.metadata?.adapterCoverage;
+  if (!coverage) return undefined;
+  return {
+    adapterId: imported?.adapter?.id ?? imported?.metadata?.adapterId ?? imported?.nativeAst?.metadata?.adapterId,
+    language: imported?.adapter?.language ?? imported?.language ?? imported?.nativeAst?.language,
+    parser: imported?.adapter?.parser ?? imported?.nativeAst?.parser ?? imported?.nativeSource?.parser,
+    coverage
+  };
+}
+
+function nativeImporterAdapterCoverageEntryFromAdapter(adapter) {
+  if (!adapter) return undefined;
+  const summary = normalizeNativeImporterAdapter(adapter);
+  return {
+    adapterId: summary.id,
+    language: summary.language,
+    parser: summary.parser,
+    coverage: summary.coverage
+  };
+}
+
+function summarizeNativeImporterAdapterCoverageEntries(entries = []) {
+  const aggregate = emptyNativeImporterAdapterCoverageAggregate();
+  for (const entry of entries) {
+    const coverage = normalizeNativeImporterAdapterCoverageForEvidence(entry.coverage);
+    const capabilityEvidence = coverage.capabilityEvidence;
+    const summary = {
+      adapterId: entry.adapterId,
+      language: entry.language,
+      parser: entry.parser,
+      exactness: coverage.exactness,
+      declared: capabilityNamesByBoolean(capabilityEvidence.capabilities, 'declared'),
+      observed: capabilityNamesByBoolean(capabilityEvidence.capabilities, 'observed'),
+      effective: capabilityNamesByBoolean(capabilityEvidence.capabilities, 'effective'),
+      gaps: capabilityEvidence.gaps,
+      declaredOnly: capabilityEvidence.declaredOnly,
+      observedOnly: capabilityEvidence.observedOnly
+    };
+    aggregate.total += 1;
+    aggregate.summaries.push(summary);
+    incrementCoverageCapabilityCounts(aggregate.declared, summary.declared);
+    incrementCoverageCapabilityCounts(aggregate.observed, summary.observed);
+    incrementCoverageCapabilityCounts(aggregate.effective, summary.effective);
+    incrementCoverageCapabilityCounts(aggregate.gaps, summary.gaps);
+    incrementCoverageCapabilityCounts(aggregate.declaredOnly, summary.declaredOnly);
+    incrementCoverageCapabilityCounts(aggregate.observedOnly, summary.observedOnly);
+  }
+  return {
+    ...aggregate,
+    summaries: Object.freeze(aggregate.summaries)
+  };
+}
+
+function normalizeNativeImporterAdapterCoverageForEvidence(coverage = {}) {
+  if (coverage.capabilityEvidence) return coverage;
+  const declared = coverage.declared ?? adapterCoverageSnapshotFromSummary(coverage);
+  const observed = normalizeNativeImporterAdapterObservedCoverage(coverage.observed, declared);
+  const effective = effectiveNativeImporterAdapterCoverage(declared, observed);
+  return {
+    ...coverage,
+    ...effective,
+    declared,
+    observed,
+    capabilityEvidence: nativeImporterAdapterCapabilityEvidence(declared, observed, effective)
+  };
+}
+
+function emptyNativeImporterAdapterCoverageAggregate() {
+  return {
+    total: 0,
+    declared: {},
+    observed: {},
+    effective: {},
+    gaps: {},
+    declaredOnly: {},
+    observedOnly: {},
+    summaries: []
+  };
+}
+
+function mergeNativeImporterAdapterCoverageAggregates(left, right) {
+  const merged = emptyNativeImporterAdapterCoverageAggregate();
+  for (const aggregate of [left, right]) {
+    if (!aggregate) continue;
+    merged.total += aggregate.total ?? 0;
+    incrementCoverageCapabilityCounts(merged.declared, aggregate.declared ?? {});
+    incrementCoverageCapabilityCounts(merged.observed, aggregate.observed ?? {});
+    incrementCoverageCapabilityCounts(merged.effective, aggregate.effective ?? {});
+    incrementCoverageCapabilityCounts(merged.gaps, aggregate.gaps ?? {});
+    incrementCoverageCapabilityCounts(merged.declaredOnly, aggregate.declaredOnly ?? {});
+    incrementCoverageCapabilityCounts(merged.observedOnly, aggregate.observedOnly ?? {});
+    merged.summaries.push(...(aggregate.summaries ?? []));
+  }
+  return {
+    ...merged,
+    summaries: Object.freeze(merged.summaries)
+  };
+}
+
+function capabilityNamesByBoolean(rows, property) {
+  return rows.filter((row) => row[property]).map((row) => row.capability);
+}
+
+function incrementCoverageCapabilityCounts(target, capabilities) {
+  if (Array.isArray(capabilities)) {
+    for (const capability of capabilities) {
+      target[capability] = (target[capability] ?? 0) + 1;
+    }
+    return;
+  }
+  for (const [capability, count] of Object.entries(capabilities ?? {})) {
+    target[capability] = (target[capability] ?? 0) + count;
+  }
+}
+
 function semanticImportSidecarEntry(imported, index, options) {
   const semanticIndex = imported?.semanticIndex ?? imported?.universalAst?.semanticIndex;
   const nativeAst = imported?.nativeAst ?? imported?.nativeSource?.ast;
@@ -4828,7 +5245,7 @@ function normalizeNativeImporterAdapterCoverage(value = {}, context = {}) {
   const sourceRanges = Boolean(value.sourceRanges ?? hasCapability('sourceRanges', 'sourceRange', 'ranges', 'sourceMaps'));
   const generatedRanges = Boolean(value.generatedRanges ?? hasCapability('generatedRanges', 'generatedRange', 'generatedSourceMaps'));
   const diagnostics = Boolean(value.diagnostics ?? hasCapability('diagnostics', 'parserDiagnostics'));
-  return Object.freeze({
+  const declared = freezeNativeImporterAdapterCoverageSnapshot({
     exactness: String(value.exactness ?? inferredAdapterExactness(exactAst, capabilities)),
     exactAst,
     tokens: Boolean(value.tokens ?? hasCapability('tokens', 'tokenStream')),
@@ -4840,13 +5257,21 @@ function normalizeNativeImporterAdapterCoverage(value = {}, context = {}) {
       capabilities,
       sourceRanges,
       generatedRanges
-    }),
+    })
+  });
+  const observed = normalizeNativeImporterAdapterObservedCoverage(value.observed, declared);
+  const effective = effectiveNativeImporterAdapterCoverage(declared, observed);
+  return Object.freeze({
+    ...effective,
+    declared,
+    observed,
     notes: uniqueStrings(value.notes ?? inferredAdapterCoverageNotes(context, {
       exactAst,
       sourceRanges,
       generatedRanges,
       diagnostics
-    }))
+    })),
+    capabilityEvidence: nativeImporterAdapterCapabilityEvidence(declared, observed, effective)
   });
 }
 
@@ -4856,31 +5281,297 @@ function observeNativeImporterAdapterCoverage(coverage, parseResult = {}, contex
   const sourceMapMappings = parseResult.sourceMaps?.flatMap((sourceMap) => sourceMap.mappings ?? []) ?? parseResult.mappings ?? [];
   const semanticIndex = parseResult.semanticIndex;
   const semanticSymbols = semanticIndex?.symbols?.length ?? 0;
-  const observedSourceRanges = nodeList.some((node) => Boolean(node?.span)) || sourceMapMappings.some((mapping) => Boolean(mapping?.sourceSpan));
-  const observedGeneratedRanges = sourceMapMappings.some((mapping) => Boolean(mapping?.generatedSpan));
-  const observedSemanticCoverage = normalizeNativeImporterSemanticCoverage({
-    ...coverage.semanticCoverage,
-    level: semanticSymbols
-      ? maxSemanticCoverageLevel(coverage.semanticCoverage?.level, 'declaration-index')
-      : coverage.semanticCoverage?.level,
-    declarations: coverage.semanticCoverage?.declarations || semanticSymbols > 0,
-    symbols: coverage.semanticCoverage?.symbols || semanticSymbols > 0
-  }, {});
+  const declared = coverage.declared ?? adapterCoverageSnapshotFromSummary(coverage);
+  const observed = observeNativeImporterAdapterCoverageDetails(parseResult, context, {
+    declared,
+    nodeList,
+    sourceMapMappings,
+    semanticIndex,
+    semanticSymbols
+  });
+  const effective = effectiveNativeImporterAdapterCoverage(declared, observed);
   return Object.freeze({
     ...coverage,
-    diagnostics: coverage.diagnostics || (context.diagnostics?.length ?? 0) > 0,
-    sourceRanges: coverage.sourceRanges || observedSourceRanges,
-    generatedRanges: coverage.generatedRanges || observedGeneratedRanges,
-    semanticCoverage: observedSemanticCoverage,
-    observed: {
-      diagnostics: context.diagnostics?.length ?? 0,
-      losses: context.losses?.length ?? 0,
-      nativeAstNodes: nodeList.length,
-      semanticSymbols,
-      sourceMapMappings: sourceMapMappings.length,
-      sourceRanges: observedSourceRanges,
-      generatedRanges: observedGeneratedRanges
-    }
+    ...effective,
+    declared,
+    observed,
+    capabilityEvidence: nativeImporterAdapterCapabilityEvidence(declared, observed, effective)
+  });
+}
+
+function adapterCoverageSnapshotFromSummary(coverage = {}) {
+  return freezeNativeImporterAdapterCoverageSnapshot({
+    exactness: coverage.exactness ?? 'unknown',
+    exactAst: coverage.exactAst,
+    tokens: coverage.tokens,
+    trivia: coverage.trivia,
+    diagnostics: coverage.diagnostics,
+    sourceRanges: coverage.sourceRanges,
+    generatedRanges: coverage.generatedRanges,
+    semanticCoverage: coverage.semanticCoverage
+  });
+}
+
+function freezeNativeImporterAdapterCoverageSnapshot(value = {}) {
+  return Object.freeze({
+    exactness: String(value.exactness ?? 'unknown'),
+    exactAst: Boolean(value.exactAst),
+    tokens: Boolean(value.tokens),
+    trivia: Boolean(value.trivia),
+    diagnostics: Boolean(value.diagnostics),
+    sourceRanges: Boolean(value.sourceRanges),
+    generatedRanges: Boolean(value.generatedRanges),
+    semanticCoverage: normalizeNativeImporterSemanticCoverage(value.semanticCoverage, {})
+  });
+}
+
+function normalizeNativeImporterAdapterObservedCoverage(value = {}, declared = {}) {
+  const diagnostics = Number(value.diagnostics ?? value.parserDiagnostics ?? 0) || 0;
+  const semanticCoverage = normalizeNativeImporterSemanticCoverage({
+    ...(value.semanticCoverage ?? {}),
+    declarations: value.semanticCoverage?.declarations ?? value.declarations,
+    symbols: value.semanticCoverage?.symbols ?? value.symbols,
+    references: value.semanticCoverage?.references ?? value.references,
+    types: value.semanticCoverage?.types ?? value.types,
+    controlFlow: value.semanticCoverage?.controlFlow ?? value.controlFlow
+  }, {});
+  const nativeAstNodes = Number(value.nativeAstNodes ?? 0) || 0;
+  const exactness = String(value.exactness ?? observedAdapterExactness(declared, nativeAstNodes));
+  return Object.freeze({
+    exactness,
+    exactAst: Boolean(value.exactAst ?? (declared.exactAst && nativeAstNodes > 0)),
+    tokens: Boolean(value.tokens),
+    tokenCount: Number(value.tokenCount ?? 0) || 0,
+    trivia: Boolean(value.trivia),
+    triviaCount: Number(value.triviaCount ?? 0) || 0,
+    diagnostics,
+    parserDiagnostics: diagnostics,
+    diagnosticErrors: Number(value.diagnosticErrors ?? 0) || 0,
+    diagnosticWarnings: Number(value.diagnosticWarnings ?? 0) || 0,
+    diagnosticInfos: Number(value.diagnosticInfos ?? 0) || 0,
+    losses: Number(value.losses ?? 0) || 0,
+    nativeAstNodes,
+    semanticSymbols: Number(value.semanticSymbols ?? 0) || 0,
+    semanticReferences: Number(value.semanticReferences ?? 0) || 0,
+    semanticTypes: Number(value.semanticTypes ?? 0) || 0,
+    semanticControlFlow: Number(value.semanticControlFlow ?? 0) || 0,
+    references: Boolean(value.references ?? semanticCoverage.references),
+    types: Boolean(value.types ?? semanticCoverage.types),
+    controlFlow: Boolean(value.controlFlow ?? semanticCoverage.controlFlow),
+    sourceMapMappings: Number(value.sourceMapMappings ?? 0) || 0,
+    sourceRanges: Boolean(value.sourceRanges),
+    sourceRangeNodes: Number(value.sourceRangeNodes ?? 0) || 0,
+    sourceRangeMappings: Number(value.sourceRangeMappings ?? 0) || 0,
+    generatedRanges: Boolean(value.generatedRanges),
+    generatedRangeMappings: Number(value.generatedRangeMappings ?? 0) || 0,
+    semanticCoverage
+  });
+}
+
+function observeNativeImporterAdapterCoverageDetails(parseResult = {}, context = {}, observedContext = {}) {
+  const declared = observedContext.declared ?? {};
+  const nodeList = observedContext.nodeList ?? Object.values(parseResult.nativeAst?.nodes ?? parseResult.nodes ?? {});
+  const sourceMapMappings = observedContext.sourceMapMappings
+    ?? parseResult.sourceMaps?.flatMap((sourceMap) => sourceMap.mappings ?? [])
+    ?? parseResult.mappings
+    ?? [];
+  const semanticIndex = observedContext.semanticIndex ?? parseResult.semanticIndex;
+  const semanticSymbols = observedContext.semanticSymbols ?? semanticIndex?.symbols?.length ?? 0;
+  const diagnostics = context.diagnostics ?? [];
+  const diagnosticErrors = diagnostics.filter((diagnostic) => diagnostic.severity === 'error').length;
+  const diagnosticWarnings = diagnostics.filter((diagnostic) => diagnostic.severity === 'warning').length;
+  const diagnosticInfos = diagnostics.filter((diagnostic) => diagnostic.severity === 'info').length;
+  const sourceRangeNodes = nodeList.filter((node) => Boolean(node?.span)).length;
+  const sourceRangeMappings = sourceMapMappings.filter((mapping) => Boolean(mapping?.sourceSpan)).length;
+  const generatedRangeMappings = sourceMapMappings.filter((mapping) => Boolean(mapping?.generatedSpan)).length;
+  const preservation = adapterCoverageSourcePreservation(parseResult);
+  const tokenCount = preservation?.summary?.tokens ?? preservation?.tokens?.length ?? 0;
+  const triviaCount = preservation?.summary?.trivia ?? preservation?.trivia?.length ?? 0;
+  const semanticEvidence = observeNativeImporterSemanticEvidence(semanticIndex);
+  const semanticCoverage = normalizeNativeImporterSemanticCoverage({
+    level: maxSemanticCoverageLevel(
+      semanticSymbols || semanticEvidence.declarations
+        ? 'declaration-index'
+        : 'native-ast',
+      semanticEvidence.references || semanticEvidence.types || semanticEvidence.controlFlow
+        ? 'semantic-index'
+        : semanticSymbols ? 'declaration-index' : 'native-ast'
+    ),
+    declarations: semanticSymbols > 0 || semanticEvidence.declarations > 0,
+    symbols: semanticSymbols > 0,
+    references: semanticEvidence.references > 0,
+    types: semanticEvidence.types > 0,
+    controlFlow: semanticEvidence.controlFlow > 0
+  }, {});
+  return normalizeNativeImporterAdapterObservedCoverage({
+    exactness: observedAdapterExactness(declared, nodeList.length),
+    exactAst: Boolean(declared.exactAst && nodeList.length > 0),
+    tokens: tokenCount > 0,
+    tokenCount,
+    trivia: triviaCount > 0,
+    triviaCount,
+    diagnostics: diagnostics.length,
+    parserDiagnostics: diagnostics.length,
+    diagnosticErrors,
+    diagnosticWarnings,
+    diagnosticInfos,
+    losses: context.losses?.length ?? 0,
+    nativeAstNodes: nodeList.length,
+    semanticSymbols,
+    semanticReferences: semanticEvidence.references,
+    semanticTypes: semanticEvidence.types,
+    semanticControlFlow: semanticEvidence.controlFlow,
+    references: semanticEvidence.references > 0,
+    types: semanticEvidence.types > 0,
+    controlFlow: semanticEvidence.controlFlow > 0,
+    sourceMapMappings: sourceMapMappings.length,
+    sourceRanges: sourceRangeNodes > 0 || sourceRangeMappings > 0,
+    sourceRangeNodes,
+    sourceRangeMappings,
+    generatedRanges: generatedRangeMappings > 0,
+    generatedRangeMappings,
+    semanticCoverage
+  }, declared);
+}
+
+function adapterCoverageSourcePreservation(parseResult = {}) {
+  return parseResult.sourcePreservation
+    ?? parseResult.nativeAst?.metadata?.sourcePreservation
+    ?? parseResult.nativeAstMetadata?.sourcePreservation
+    ?? parseResult.metadata?.sourcePreservation;
+}
+
+function observeNativeImporterSemanticEvidence(semanticIndex = {}) {
+  const occurrences = semanticIndex?.occurrences ?? [];
+  const relations = semanticIndex?.relations ?? [];
+  const facts = semanticIndex?.facts ?? [];
+  const symbols = semanticIndex?.symbols ?? [];
+  const referenceRelations = relations.filter((relation) => semanticPredicateMatches(relation?.predicate, ['reference', 'call', 'read', 'write', 'use']));
+  const typeFacts = facts.filter((fact) => semanticPredicateMatches(fact?.predicate, ['type', 'declaredtype', 'inferredtype', 'typeof']));
+  const typedSymbols = symbols.filter((symbol) => Boolean(symbol?.declaredType ?? symbol?.inferredType ?? symbol?.typeId ?? symbol?.valueType));
+  const controlFlowRecords = [
+    ...relations.filter((relation) => semanticPredicateMatches(relation?.predicate, ['controlflow', 'cfg', 'flow'])),
+    ...facts.filter((fact) => semanticPredicateMatches(fact?.predicate, ['controlflow', 'cfg', 'flow']))
+  ];
+  return {
+    declarations: occurrences.filter((occurrence) => occurrence?.role === 'definition' || occurrence?.role === 'declaration').length,
+    references: occurrences.filter((occurrence) => {
+      const role = String(occurrence?.role ?? '').toLowerCase();
+      return role && role !== 'definition' && role !== 'declaration';
+    }).length + referenceRelations.length,
+    types: typeFacts.length + typedSymbols.length,
+    controlFlow: controlFlowRecords.length
+  };
+}
+
+function semanticPredicateMatches(value, fragments) {
+  const predicate = String(value ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '');
+  return fragments.some((fragment) => predicate.includes(fragment));
+}
+
+function observedAdapterExactness(declared = {}, nativeAstNodes = 0) {
+  if (!nativeAstNodes) return 'unknown';
+  if (declared.exactAst) return declared.exactness ?? 'exact-parser-ast';
+  return 'adapter-reported-native-ast';
+}
+
+function effectiveNativeImporterAdapterCoverage(declared, observed) {
+  const semanticCoverage = normalizeNativeImporterSemanticCoverage({
+    level: maxSemanticCoverageLevel(declared.semanticCoverage?.level, observed.semanticCoverage?.level),
+    declarations: declared.semanticCoverage?.declarations || observed.semanticCoverage?.declarations,
+    symbols: declared.semanticCoverage?.symbols || observed.semanticCoverage?.symbols,
+    references: declared.semanticCoverage?.references || observed.semanticCoverage?.references,
+    types: declared.semanticCoverage?.types || observed.semanticCoverage?.types,
+    controlFlow: declared.semanticCoverage?.controlFlow || observed.semanticCoverage?.controlFlow
+  }, {});
+  return freezeNativeImporterAdapterCoverageSnapshot({
+    exactness: effectiveAdapterExactness(declared, observed),
+    exactAst: declared.exactAst || observed.exactAst,
+    tokens: declared.tokens || observed.tokens,
+    trivia: declared.trivia || observed.trivia,
+    diagnostics: declared.diagnostics || observed.parserDiagnostics > 0,
+    sourceRanges: declared.sourceRanges || observed.sourceRanges,
+    generatedRanges: declared.generatedRanges || observed.generatedRanges,
+    semanticCoverage
+  });
+}
+
+function effectiveAdapterExactness(declared, observed) {
+  if (declared.exactAst || observed.exactAst) return declared.exactness ?? 'exact-parser-ast';
+  if (observed.nativeAstNodes > 0) return observed.exactness ?? 'adapter-reported-native-ast';
+  return declared.exactness ?? 'unknown';
+}
+
+function nativeImporterAdapterCapabilityEvidence(declared, observed, effective) {
+  const capabilityRows = [
+    adapterCoverageCapabilityRow('exactAst', declared.exactAst, observed.exactAst, effective.exactAst, observed.nativeAstNodes),
+    adapterCoverageCapabilityRow('tokens', declared.tokens, observed.tokens, effective.tokens, observed.tokenCount),
+    adapterCoverageCapabilityRow('trivia', declared.trivia, observed.trivia, effective.trivia, observed.triviaCount),
+    adapterCoverageCapabilityRow('parserDiagnostics', declared.diagnostics, observed.parserDiagnostics > 0, effective.diagnostics, observed.parserDiagnostics),
+    adapterCoverageCapabilityRow('sourceRanges', declared.sourceRanges, observed.sourceRanges, effective.sourceRanges, observed.sourceRangeNodes + observed.sourceRangeMappings),
+    adapterCoverageCapabilityRow('generatedRanges', declared.generatedRanges, observed.generatedRanges, effective.generatedRanges, observed.generatedRangeMappings),
+    adapterCoverageCapabilityRow('semanticDeclarations', declared.semanticCoverage.declarations, observed.semanticCoverage.declarations, effective.semanticCoverage.declarations, observed.semanticSymbols),
+    adapterCoverageCapabilityRow('semanticSymbols', declared.semanticCoverage.symbols, observed.semanticCoverage.symbols, effective.semanticCoverage.symbols, observed.semanticSymbols),
+    adapterCoverageCapabilityRow('references', declared.semanticCoverage.references, observed.semanticCoverage.references, effective.semanticCoverage.references, observed.semanticReferences),
+    adapterCoverageCapabilityRow('types', declared.semanticCoverage.types, observed.semanticCoverage.types, effective.semanticCoverage.types, observed.semanticTypes),
+    adapterCoverageCapabilityRow('controlFlow', declared.semanticCoverage.controlFlow, observed.semanticCoverage.controlFlow, effective.semanticCoverage.controlFlow, observed.semanticControlFlow)
+  ];
+  const reviewCapabilities = new Set(['exactAst', 'tokens', 'trivia', 'parserDiagnostics', 'sourceRanges', 'generatedRanges', 'references', 'types', 'controlFlow']);
+  return Object.freeze({
+    declared,
+    observed,
+    effective,
+    capabilities: Object.freeze(capabilityRows),
+    gaps: Object.freeze(capabilityRows.filter((row) => reviewCapabilities.has(row.capability) && !row.effective).map((row) => row.capability)),
+    declaredOnly: Object.freeze(capabilityRows.filter((row) => row.declared && !row.observed).map((row) => row.capability)),
+    observedOnly: Object.freeze(capabilityRows.filter((row) => !row.declared && row.observed).map((row) => row.capability)),
+    parserDiagnostics: Object.freeze({
+      declared: declared.diagnostics,
+      observed: observed.parserDiagnostics > 0,
+      count: observed.parserDiagnostics,
+      errors: observed.diagnosticErrors,
+      warnings: observed.diagnosticWarnings,
+      infos: observed.diagnosticInfos
+    }),
+    sourceRanges: Object.freeze({
+      declared: declared.sourceRanges,
+      observed: observed.sourceRanges,
+      nativeAstNodes: observed.nativeAstNodes,
+      sourceRangeNodes: observed.sourceRangeNodes,
+      sourceMapMappings: observed.sourceMapMappings,
+      sourceRangeMappings: observed.sourceRangeMappings,
+      generatedRangeMappings: observed.generatedRangeMappings
+    }),
+    tokensTrivia: Object.freeze({
+      tokens: Object.freeze({ declared: declared.tokens, observed: observed.tokens, count: observed.tokenCount }),
+      trivia: Object.freeze({ declared: declared.trivia, observed: observed.trivia, count: observed.triviaCount })
+    }),
+    semantic: Object.freeze({
+      level: Object.freeze({
+        declared: declared.semanticCoverage.level,
+        observed: observed.semanticCoverage.level,
+        effective: effective.semanticCoverage.level
+      }),
+      declarations: adapterCoverageCapabilityRow('semanticDeclarations', declared.semanticCoverage.declarations, observed.semanticCoverage.declarations, effective.semanticCoverage.declarations, observed.semanticSymbols),
+      symbols: adapterCoverageCapabilityRow('semanticSymbols', declared.semanticCoverage.symbols, observed.semanticCoverage.symbols, effective.semanticCoverage.symbols, observed.semanticSymbols),
+      references: adapterCoverageCapabilityRow('references', declared.semanticCoverage.references, observed.semanticCoverage.references, effective.semanticCoverage.references, observed.semanticReferences),
+      types: adapterCoverageCapabilityRow('types', declared.semanticCoverage.types, observed.semanticCoverage.types, effective.semanticCoverage.types, observed.semanticTypes),
+      controlFlow: adapterCoverageCapabilityRow('controlFlow', declared.semanticCoverage.controlFlow, observed.semanticCoverage.controlFlow, effective.semanticCoverage.controlFlow, observed.semanticControlFlow)
+    })
+  });
+}
+
+function adapterCoverageCapabilityRow(capability, declared, observed, effective, count = 0) {
+  const status = declared && observed
+    ? 'declared-and-observed'
+    : declared ? 'declared-unobserved' : observed ? 'observed-undeclared' : 'absent';
+  return Object.freeze({
+    capability,
+    declared: Boolean(declared),
+    observed: Boolean(observed),
+    effective: Boolean(effective),
+    count: Number(count ?? 0) || 0,
+    status
   });
 }
 

package/package.json

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