@shapeshift-labs/frontier-lang-compiler 0.2.8 → 0.2.10

package/README.md

@@ -50,6 +50,97 @@ console.log(summary.categories);
 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.
+
+Ask the compiler what is actually covered before sending native imports into a merge queue:
+
+```js
+import {
+  createNativeImportCoverageMatrix,
+  importNativeSource
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const imported = importNativeSource({
+  language: 'python',
+  sourcePath: 'todo.py',
+  sourceText: 'def add_todo(title):\n    return title\n'
+});
+
+const matrix = createNativeImportCoverageMatrix({ imports: [imported] });
+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
+```
+
+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
+import {
+  createNativeSourcePreservation,
+  importNativeSource
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const sourceText = '// kept\nexport function step(frame) { return frame + 1; }\n';
+const preservation = createNativeSourcePreservation({
+  language: 'javascript',
+  sourcePath: 'src/runtime.js',
+  sourceText
+});
+const imported = importNativeSource({ language: 'javascript', sourcePath: 'src/runtime.js', sourceText });
+
+console.log(preservation.summary.comments); // comments and whitespace are tracked
+console.log(imported.metadata.sourcePreservation.sourceHash);
+```
+
+When `sourceText` is present, hashes are computed from the actual text. Caller-provided hashes are recorded as declared metadata and cannot make stale text project as exact source. Use `includeTokens`, `includeTrivia`, `includeDirectives`, and `max*` options to keep preservation records compact for large files.
+
+Create a compact semantic sidecar for swarm merge admission. This is the artifact a coordinator can index instead of reading a worker directory by hand:
+
+```js
+import {
+  createSemanticImportSidecar,
+  importNativeSource
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const imported = importNativeSource({
+  language: 'typescript',
+  sourcePath: 'src/runtime.ts',
+  sourceText: `
+    export class Runtime {
+      step(frame: number) { return frame + 1; }
+    }
+  `
+});
+
+const sidecar = createSemanticImportSidecar(imported);
+
+console.log(sidecar.summary.emptySemanticIndex); // false when symbols were found
+console.log(sidecar.ownershipRegions[0].key); // source#src/runtime.ts#class#Runtime
+console.log(sidecar.patchHints[0].supportedOperations); // source-region patch operations
+```
+
+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:
+
+```js
+import {
+  importNativeSource,
+  projectNativeImportToSource
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const sourceText = 'export function step(frame) { return frame + 1; }\n';
+const imported = importNativeSource({
+  language: 'javascript',
+  sourcePath: 'src/runtime.js',
+  sourceText
+});
+
+const projection = projectNativeImportToSource(imported);
+
+console.log(projection.mode); // "preserved-source"
+console.log(projection.readiness.readiness); // "ready"
+```
+
 Use injected parser adapters when a real language parser is available but should not become a compiler runtime dependency:
 
 ```js
@@ -79,6 +170,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.semanticCoverage.level);
+console.log(project.metadata.sourcePreservationSummary.total);
 ```
 
 The built-in adapter factories are dependency-light wrappers for caller-owned parsers or ASTs:
@@ -88,6 +182,8 @@ The built-in adapter factories are dependency-light wrappers for caller-owned pa
 - `createTypeScriptCompilerNativeImporterAdapter`
 - `createTreeSitterNativeImporterAdapter`
 
+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.
+
 ## 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

@@ -2,7 +2,11 @@ import { performance } from 'node:perf_hooks';
 import {
   compileFrontierSource,
   createEstreeNativeImporterAdapter,
+  createNativeImportCoverageMatrix,
+  createNativeSourcePreservation,
+  createSemanticImportSidecar,
   importNativeSource,
+  projectNativeImportToSource,
   runNativeImporterAdapter
 } from '../dist/index.js';
 
@@ -32,6 +36,7 @@ const compileDurationMs = performance.now() - start;
 const importStart = performance.now();
 const estreeAdapter = createEstreeNativeImporterAdapter();
 let nativeSymbols = 0;
+const nativeImportResults = [];
 for (let index = 0; index < 150; index += 1) {
   const imported = index % 2 === 0
     ? importNativeSource({
@@ -55,14 +60,50 @@ for (let index = 0; index < 150; index += 1) {
       }
     });
   nativeSymbols += imported.semanticIndex?.symbols?.length ?? 0;
+  nativeImportResults.push(imported);
 }
 const importDurationMs = performance.now() - importStart;
 
+const matrixStart = performance.now();
+const coverageMatrix = createNativeImportCoverageMatrix({ imports: nativeImportResults });
+const matrixDurationMs = performance.now() - matrixStart;
+
+const preservationStart = performance.now();
+const preservationRecords = nativeImportResults.map((imported) => imported.metadata.sourcePreservation ?? createNativeSourcePreservation({
+  language: imported.language,
+  sourcePath: imported.sourcePath,
+  sourceText: imported.metadata.sourcePreservation?.sourceText ?? ''
+}));
+const preservationDurationMs = performance.now() - preservationStart;
+const preservationTokens = preservationRecords.reduce((sum, record) => sum + record.tokens.length + record.trivia.length, 0);
+
+const sidecarStart = performance.now();
+const semanticSidecars = nativeImportResults.map((imported) => createSemanticImportSidecar(imported));
+const sidecarDurationMs = performance.now() - sidecarStart;
+const sidecarOwnershipRegions = semanticSidecars.reduce((sum, sidecar) => sum + sidecar.ownershipRegions.length, 0);
+
+const projectionStart = performance.now();
+const nativeProjections = nativeImportResults.map((imported) => projectNativeImportToSource(imported));
+const projectionDurationMs = performance.now() - projectionStart;
+const projectionBytes = nativeProjections.reduce((sum, projection) => sum + projection.sourceText.length, 0);
+
 console.log(JSON.stringify({
   compiles: 250,
   bytes,
   compileDurationMs: Number(compileDurationMs.toFixed(2)),
   nativeImports: 150,
   nativeSymbols,
-  nativeImportDurationMs: Number(importDurationMs.toFixed(2))
+  nativeImportDurationMs: Number(importDurationMs.toFixed(2)),
+  coverageMatrixLanguages: coverageMatrix.summary.languages,
+  coverageMatrixImports: coverageMatrix.summary.imports,
+  coverageMatrixDurationMs: Number(matrixDurationMs.toFixed(2)),
+  sourcePreservationRecords: preservationRecords.length,
+  sourcePreservationTokens: preservationTokens,
+  sourcePreservationDurationMs: Number(preservationDurationMs.toFixed(2)),
+  semanticSidecars: semanticSidecars.length,
+  sidecarOwnershipRegions,
+  sidecarDurationMs: Number(sidecarDurationMs.toFixed(2)),
+  nativeProjections: nativeProjections.length,
+  projectionBytes,
+  projectionDurationMs: Number(projectionDurationMs.toFixed(2))
 }));

package/dist/index.d.ts

@@ -79,27 +79,42 @@ export type NativeImportTaxonomyKind =
   | 'opaqueBodies'
   | 'macroExpansion'
   | 'preprocessor'
+  | 'conditionalCompilation'
   | 'metaprogramming'
+  | 'reflection'
   | 'generatedCode'
+  | 'overloadTypeInference'
   | 'sourcePreservation'
+  | 'commentsTrivia'
   | 'parserDiagnostics'
   | 'unsupportedSyntax'
   | 'partialSemanticIndex'
   | 'sourceMapApproximation'
+  | 'targetProjectionLoss'
   | string;
 
 export type NativeImportKnownLossKind =
   | 'declarationOnlyCoverage'
   | 'opaqueNative'
   | 'macroExpansion'
+  | 'macroHygiene'
   | 'preprocessor'
+  | 'conditionalCompilation'
   | 'metaprogramming'
+  | 'reflection'
+  | 'dynamicRuntime'
+  | 'dynamicDispatch'
   | 'generatedCode'
+  | 'overloadResolution'
+  | 'typeInference'
   | 'sourcePreservation'
+  | 'commentsTrivia'
   | 'parserDiagnostic'
   | 'unsupportedSyntax'
+  | 'unsupportedSemantic'
   | 'partialSemanticIndex'
   | 'sourceMapApproximation'
+  | 'targetProjectionLoss'
   | string;
 
 export interface NativeImportLossSummaryOptions {
@@ -135,6 +150,315 @@ export interface NativeImportReadinessClassification {
   readonly summary: NativeImportLossSummary;
 }
 
+export interface NativeImportLanguageProfile {
+  readonly language: FrontierSourceLanguage;
+  readonly aliases: readonly string[];
+  readonly extensions: readonly string[];
+  readonly supportsLightweightScan: boolean;
+  readonly parserAdapters: readonly string[];
+  readonly projectionTargets: readonly FrontierCompileTarget[];
+  readonly knownLossKinds: readonly NativeImportKnownLossKind[];
+  readonly defaultReadiness: SemanticMergeReadiness;
+  readonly notes: 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 knownLossKinds: readonly NativeImportKnownLossKind[];
+  readonly defaultReadiness: SemanticMergeReadiness;
+  readonly notes: readonly string[];
+  readonly imports: {
+    readonly total: number;
+    readonly parsers: readonly string[];
+    readonly readiness: SemanticMergeReadiness;
+    readonly readinessReasons: readonly string[];
+    readonly symbols: number;
+    readonly sourceMaps: number;
+    readonly sourceMapMappings: number;
+    readonly losses: number;
+    readonly lossKinds: Readonly<Record<string, number>>;
+    readonly lossCategories: readonly NativeImportTaxonomyKind[];
+  };
+}
+
+export interface NativeImportCoverageMatrix {
+  readonly kind: 'frontier.lang.nativeImportCoverageMatrix';
+  readonly version: 1;
+  readonly generatedAt: number;
+  readonly languages: readonly NativeImportCoverageLanguage[];
+  readonly summary: {
+    readonly languages: number;
+    readonly lightweightScanners: number;
+    readonly parserAdapterSlots: number;
+    readonly imports: number;
+    readonly symbols: number;
+    readonly sourceMaps: number;
+    readonly sourceMapMappings: number;
+    readonly losses: number;
+    readonly byReadiness: Readonly<Record<string, number>>;
+    readonly lossKinds: Readonly<Record<string, number>>;
+  };
+  readonly metadata: {
+    readonly compileTargets: readonly FrontierCompileTarget[];
+    readonly note: string;
+  };
+}
+
+export interface NativeImportCoverageMatrixOptions {
+  readonly languages?: readonly NativeImportLanguageProfile[];
+  readonly imports?: readonly NativeSourceImportResult[];
+  readonly adapters?: readonly NativeImporterAdapter[];
+  readonly generatedAt?: number;
+}
+
+export type NativeSourceTokenKind =
+  | 'identifier'
+  | 'keyword'
+  | 'number'
+  | 'string'
+  | 'operator'
+  | 'punctuation'
+  | 'comment'
+  | 'whitespace'
+  | 'newline'
+  | 'directive'
+  | 'unknown'
+  | string;
+
+export interface NativeSourcePreservedToken {
+  readonly id: string;
+  readonly kind: NativeSourceTokenKind;
+  readonly text?: string;
+  readonly textHash: string;
+  readonly span: SourceSpan;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface NativeSourcePreservedDirective {
+  readonly id: string;
+  readonly kind: string;
+  readonly text?: string;
+  readonly textHash: string;
+  readonly span: SourceSpan;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface NativeSourcePreservation {
+  readonly kind: 'frontier.lang.nativeSourcePreservation';
+  readonly version: 1;
+  readonly id: string;
+  readonly language: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash: string;
+  readonly sourceBytes: number;
+  readonly lineCount: number;
+  readonly newline: 'lf' | 'crlf' | 'mixed' | 'none';
+  readonly encoding: string;
+  readonly sourceText?: string;
+  readonly tokens: readonly NativeSourcePreservedToken[];
+  readonly trivia: readonly NativeSourcePreservedToken[];
+  readonly directives: readonly NativeSourcePreservedDirective[];
+  readonly summary: {
+    readonly tokens: number;
+    readonly trivia: number;
+    readonly directives: number;
+    readonly comments: number;
+    readonly whitespace: number;
+    readonly exactSourceAvailable: boolean;
+    readonly truncated: boolean;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface CreateNativeSourcePreservationOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourceText: string;
+  readonly encoding?: string;
+  readonly includeSourceText?: boolean;
+  readonly includeTokens?: boolean;
+  readonly includeTrivia?: boolean;
+  readonly includeDirectives?: boolean;
+  readonly maxTokens?: number;
+  readonly maxTrivia?: number;
+  readonly maxDirectives?: number;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface SemanticImportOwnershipRegion {
+  readonly id: string;
+  readonly key: string;
+  readonly granularity: 'symbol' | string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly symbolId?: string;
+  readonly symbolName?: string;
+  readonly symbolKind?: string;
+  readonly nativeAstNodeId?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly precision?: 'exact' | 'declaration' | 'line' | 'estimated' | 'unknown' | string;
+  readonly mergePolicy?: string;
+}
+
+export interface SemanticImportSidecarSymbol {
+  readonly id: string;
+  readonly name?: string;
+  readonly kind?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly nativeAstNodeId?: string;
+  readonly semanticOccurrenceId?: string;
+  readonly sourceMapMappingId?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly signatureHash?: string;
+  readonly ownershipRegionId: string;
+  readonly ownershipKey: string;
+  readonly readiness: SemanticMergeReadiness;
+}
+
+export interface SemanticImportPatchHint {
+  readonly id: string;
+  readonly kind: 'source-region-patch' | string;
+  readonly ownershipRegionId: string;
+  readonly ownershipKey: string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly readiness: SemanticMergeReadiness;
+  readonly precision?: string;
+  readonly supportedOperations: readonly string[];
+  readonly projection: {
+    readonly sourceLanguage?: FrontierSourceLanguage | string;
+    readonly targetPath?: string;
+    readonly requiresSourceMap: boolean;
+  };
+}
+
+export interface SemanticImportSidecarImportEntry {
+  readonly id: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly parser?: string;
+  readonly nativeSourceId?: string;
+  readonly nativeAstId?: string;
+  readonly semanticIndexId?: string;
+  readonly universalAstId?: string;
+  readonly symbolCount: number;
+  readonly sourceMapCount: number;
+  readonly sourceMapMappingCount: number;
+  readonly readiness: SemanticMergeReadiness;
+  readonly emptySemanticIndex: boolean;
+}
+
+export interface SemanticImportSidecar {
+  readonly kind: 'frontier.lang.semanticImportSidecar';
+  readonly version: 1;
+  readonly id: string;
+  readonly generatedAt: number;
+  readonly language?: FrontierSourceLanguage | 'mixed' | string;
+  readonly projectRoot?: string;
+  readonly imports: readonly SemanticImportSidecarImportEntry[];
+  readonly symbols: readonly SemanticImportSidecarSymbol[];
+  readonly ownershipRegions: readonly SemanticImportOwnershipRegion[];
+  readonly sourceMaps: {
+    readonly total: number;
+    readonly mappings: number;
+    readonly ids: readonly string[];
+  };
+  readonly patchHints: readonly SemanticImportPatchHint[];
+  readonly mergeCandidates: readonly {
+    readonly id?: string;
+    readonly readiness?: SemanticMergeReadiness;
+    readonly reasons: readonly string[];
+    readonly risk?: string;
+    readonly operationCount: number;
+  }[];
+  readonly losses: {
+    readonly total: number;
+    readonly byKind: Readonly<Record<string, number>>;
+    readonly bySeverity: Readonly<Record<string, number>>;
+    readonly categories: readonly NativeImportTaxonomyKind[];
+    readonly blockingLossIds: readonly string[];
+    readonly reviewLossIds: readonly string[];
+  };
+  readonly evidence: {
+    readonly total: number;
+    readonly failed: readonly string[];
+    readonly ids: readonly string[];
+  };
+  readonly summary: {
+    readonly imports: number;
+    readonly symbols: number;
+    readonly ownershipRegions: number;
+    readonly sourceMapMappings: number;
+    readonly readiness: SemanticMergeReadiness;
+    readonly emptySemanticIndex: boolean;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface SemanticImportSidecarOptions {
+  readonly id?: string;
+  readonly generatedAt?: number;
+  readonly regionPrefix?: string;
+  readonly targetPath?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export type NativeImporterAdapterExactness =
+  | 'exact-parser-ast'
+  | 'parser-tree'
+  | 'adapter-reported-native-ast'
+  | 'loss-aware-native-ast'
+  | 'unknown'
+  | string;
+
+export interface NativeImporterAdapterSemanticCoverage {
+  readonly level: 'native-ast' | 'declaration-index' | 'semantic-index' | string;
+  readonly declarations: boolean;
+  readonly symbols: boolean;
+  readonly references: boolean;
+  readonly types: boolean;
+  readonly controlFlow: boolean;
+}
+
+export interface NativeImporterAdapterCoverageObserved {
+  readonly diagnostics: number;
+  readonly losses: number;
+  readonly nativeAstNodes: number;
+  readonly semanticSymbols: number;
+  readonly sourceMapMappings: number;
+  readonly sourceRanges: boolean;
+  readonly generatedRanges: boolean;
+}
+
+export interface NativeImporterAdapterCoverageSummary {
+  readonly exactness: NativeImporterAdapterExactness;
+  readonly exactAst: boolean;
+  readonly tokens: boolean;
+  readonly trivia: boolean;
+  readonly diagnostics: boolean;
+  readonly sourceRanges: boolean;
+  readonly generatedRanges: boolean;
+  readonly semanticCoverage: NativeImporterAdapterSemanticCoverage;
+  readonly notes: readonly string[];
+  readonly observed?: NativeImporterAdapterCoverageObserved;
+}
+
+export type NativeImporterAdapterCoverageInput =
+  Omit<Partial<NativeImporterAdapterCoverageSummary>, 'semanticCoverage' | 'observed'> & {
+    readonly semanticCoverage?: Partial<NativeImporterAdapterSemanticCoverage>;
+    readonly observed?: Partial<NativeImporterAdapterCoverageObserved>;
+  };
+
 export interface NativeImporterAdapterDiagnostic {
   readonly id?: string;
   readonly severity?: 'info' | 'warning' | 'error';
@@ -175,6 +499,7 @@ export interface ImportNativeSourceOptions {
   readonly losses?: readonly NativeAstLossRecord[];
   readonly evidence?: readonly EvidenceRecord[];
   readonly evidenceId?: string;
+  readonly sourcePreservation?: NativeSourcePreservation;
   readonly patch?: SemanticPatchBundle;
   readonly patchId?: string;
   readonly author?: string;
@@ -218,6 +543,7 @@ export interface NativeImporterAdapter {
   readonly parser: string;
   readonly version?: string;
   readonly capabilities?: readonly string[];
+  readonly coverage?: NativeImporterAdapterCoverageInput;
   readonly supportedExtensions?: readonly string[];
   readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
   readonly parse: (input: NativeImporterAdapterParseInput) => NativeImporterAdapterParseResult | Promise<NativeImporterAdapterParseResult>;
@@ -229,6 +555,7 @@ export interface JavaScriptNativeImporterAdapterOptions {
   readonly parser?: string;
   readonly version?: string;
   readonly capabilities?: readonly string[];
+  readonly coverage?: NativeImporterAdapterCoverageInput;
   readonly supportedExtensions?: readonly string[];
   readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
   readonly ast?: unknown;
@@ -245,6 +572,7 @@ export interface TypeScriptCompilerNativeImporterAdapterOptions {
   readonly parser?: string;
   readonly version?: string;
   readonly capabilities?: readonly string[];
+  readonly coverage?: NativeImporterAdapterCoverageInput;
   readonly supportedExtensions?: readonly string[];
   readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
   readonly typescript?: unknown;
@@ -264,6 +592,7 @@ export interface TreeSitterNativeImporterAdapterOptions {
   readonly parserName?: string;
   readonly version?: string;
   readonly capabilities?: readonly string[];
+  readonly coverage?: NativeImporterAdapterCoverageInput;
   readonly supportedExtensions?: readonly string[];
   readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
   readonly parserInstance?: { readonly parse: (sourceText: string) => unknown };
@@ -279,6 +608,7 @@ export interface NativeImporterAdapterSummary {
   readonly parser: string;
   readonly version?: string;
   readonly capabilities: readonly string[];
+  readonly coverage: NativeImporterAdapterCoverageSummary;
   readonly supportedExtensions: readonly string[];
   readonly diagnostics: readonly NativeImporterAdapterDiagnostic[];
 }
@@ -343,10 +673,62 @@ export interface NativeProjectImportResult {
   readonly metadata?: Record<string, unknown>;
 }
 
+export type NativeSourceProjectionMode = 'preserved-source' | 'native-source-stubs';
+
+export interface ProjectNativeImportToSourceOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly expectedSourceHash?: string;
+  readonly sourceText?: string;
+  readonly preservedSourceText?: string;
+  readonly exactSourceText?: string;
+  readonly sourceHash?: string;
+  readonly verifySourceHash?: boolean;
+  readonly preferPreservedSource?: boolean;
+  readonly stubBanner?: string | false;
+  readonly evidenceId?: string;
+  readonly parser?: string;
+  readonly semanticStatus?: string;
+  readonly nativeSource?: NativeSourceNode;
+  readonly nativeAst?: NativeAstRecord;
+  readonly semanticIndex?: SemanticIndexRecord;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface NativeSourceProjectionDeclaration {
+  readonly name: string;
+  readonly kind: string;
+  readonly symbolId?: string;
+  readonly nativeAstNodeId?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly ownershipRegionId?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface NativeSourceProjectionResult {
+  readonly kind: 'frontier.lang.nativeSourceProjection';
+  readonly version: 1;
+  readonly id: string;
+  readonly language: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly mode: NativeSourceProjectionMode;
+  readonly sourceText: string;
+  readonly outputHash: string;
+  readonly declarations: readonly NativeSourceProjectionDeclaration[];
+  readonly losses: readonly NativeAstLossRecord[];
+  readonly lossSummary: NativeImportLossSummary;
+  readonly readiness: NativeImportReadinessClassification;
+  readonly evidence: readonly EvidenceRecord[];
+  readonly metadata: Record<string, unknown>;
+}
+
 export declare const FrontierCompileTargets: readonly FrontierCompileTarget[];
 export declare const NativeImportTaxonomyKinds: readonly NativeImportTaxonomyKind[];
 export declare const NativeImportLossKinds: readonly NativeImportKnownLossKind[];
 export declare const NativeImportReadinessBySeverity: Readonly<Record<NativeImportLossSummary['highestSeverity'], SemanticMergeReadiness>>;
+export declare const NativeImportLanguageProfiles: readonly NativeImportLanguageProfile[];
 export declare function normalizeCompileTarget(target?: string): FrontierCompileTarget;
 export declare function compileFrontierSource(source: string, options?: FrontierCompileOptions): FrontierCompileResult;
 export declare function compileFrontierDocument(document: FrontierLangDocument, options?: FrontierCompileOptions): FrontierCompileResult;
@@ -355,11 +737,15 @@ export declare function renderTargetAst(ast: FrontierTargetAst, target?: Frontie
 export declare function resolveCapabilityAdapters(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: { readonly platform?: string }): readonly CapabilityResolution[];
 export declare function summarizeNativeImportLosses(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportLossSummary;
 export declare function classifyNativeImportReadiness(losses?: readonly NativeAstLossRecord[], options?: NativeImportLossSummaryOptions): NativeImportReadinessClassification;
+export declare function createNativeImportCoverageMatrix(options?: NativeImportCoverageMatrixOptions): NativeImportCoverageMatrix;
+export declare function createNativeSourcePreservation(options: CreateNativeSourcePreservationOptions): NativeSourcePreservation;
+export declare function createSemanticImportSidecar(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: SemanticImportSidecarOptions): SemanticImportSidecar;
 export declare function createEstreeNativeImporterAdapter(options?: JavaScriptNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createBabelNativeImporterAdapter(options?: JavaScriptNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createTypeScriptCompilerNativeImporterAdapter(options?: TypeScriptCompilerNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function createTreeSitterNativeImporterAdapter(options?: TreeSitterNativeImporterAdapterOptions): NativeImporterAdapter;
 export declare function runNativeImporterAdapter(adapter: NativeImporterAdapter, input: RunNativeImporterAdapterOptions): Promise<NativeImporterAdapterImportResult>;
+export declare function projectNativeImportToSource(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: ProjectNativeImportToSourceOptions): NativeSourceProjectionResult;
 export declare function importNativeSource(input: ImportNativeSourceOptions): NativeSourceImportResult;
 export declare function importNativeProject(input: ImportNativeProjectOptions): Promise<NativeProjectImportResult>;
 export declare function createUniversalAstFromDocument(document: FrontierLangDocument, input?: {