@shapeshift-labs/frontier-lang-compiler 0.2.7 → 0.2.9

package/README.md

@@ -38,6 +38,123 @@ console.log(imported.nativeSource.ast.rootId);
 console.log(imported.patch.operations.length);
 ```
 
+Native imports include source maps, semantic merge candidates, and a loss summary for admission queues and dashboards. Informational losses produce `ready-with-losses`, warning losses produce `needs-review`, and error losses or failed import evidence produce `blocked`:
+
+```js
+import { classifyNativeImportReadiness, summarizeNativeImportLosses } from '@shapeshift-labs/frontier-lang-compiler';
+
+const summary = summarizeNativeImportLosses(imported.losses, { evidence: imported.evidence });
+const readiness = classifyNativeImportReadiness(imported.losses, { evidence: imported.evidence });
+
+console.log(summary.categories);
+console.log(readiness.readiness);
+```
+
+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
+```
+
+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 only when the 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, { sourceText });
+
+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
+import {
+  createBabelNativeImporterAdapter,
+  importNativeProject,
+  runNativeImporterAdapter
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const babelAdapter = createBabelNativeImporterAdapter({
+  parserModule: await import('@babel/parser')
+});
+
+const imported = await runNativeImporterAdapter(babelAdapter, {
+  sourcePath: 'src/todo.ts',
+  sourceText
+});
+
+const project = await importNativeProject({
+  projectRoot: 'src',
+  adapters: [babelAdapter],
+  sources: [
+    { language: 'typescript', adapter: babelAdapter.id, sourcePath: 'src/todo.ts', sourceText },
+    { language: 'python', sourcePath: 'tools/todo.py', sourceText: pythonSource }
+  ]
+});
+
+console.log(imported.universalAst.sourceMaps.length);
+console.log(project.semanticIndex.symbols.length);
+```
+
+The built-in adapter factories are dependency-light wrappers for caller-owned parsers or ASTs:
+
+- `createEstreeNativeImporterAdapter`
+- `createBabelNativeImporterAdapter`
+- `createTypeScriptCompilerNativeImporterAdapter`
+- `createTreeSitterNativeImporterAdapter`
+
 ## 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

@@ -1,5 +1,13 @@
 import { performance } from 'node:perf_hooks';
-import { compileFrontierSource } from '../dist/index.js';
+import {
+  compileFrontierSource,
+  createEstreeNativeImporterAdapter,
+  createNativeImportCoverageMatrix,
+  createSemanticImportSidecar,
+  importNativeSource,
+  projectNativeImportToSource,
+  runNativeImporterAdapter
+} from '../dist/index.js';
 
 const source = `
 module Bench @id("mod_bench")
@@ -22,4 +30,67 @@ let bytes = 0;
 for (let index = 0; index < 250; index += 1) {
   bytes += compileFrontierSource(source, { target: targets[index % targets.length] }).output.length;
 }
-console.log(JSON.stringify({ compiles: 250, bytes, durationMs: Number((performance.now() - start).toFixed(2)) }));
+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({
+      language: 'javascript',
+      sourcePath: `src/bench-${index}.js`,
+      sourceText: `export function bench${index}() { return ${index}; }\n`
+    })
+    : await runNativeImporterAdapter(estreeAdapter, {
+      sourcePath: `src/bench-${index}.js`,
+      sourceText: `export function bench${index}() { return ${index}; }\n`,
+      adapterOptions: {
+        ast: {
+          type: 'Program',
+          loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 42 } },
+          body: [{
+            type: 'FunctionDeclaration',
+            id: { type: 'Identifier', name: `bench${index}` },
+            loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 42 } }
+          }]
+        }
+      }
+    });
+  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 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)),
+  coverageMatrixLanguages: coverageMatrix.summary.languages,
+  coverageMatrixImports: coverageMatrix.summary.imports,
+  coverageMatrixDurationMs: Number(matrixDurationMs.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

@@ -11,6 +11,8 @@ import type {
   NativeAstNode,
   NativeAstRecord,
   NativeSourceNode,
+  SemanticMergeCandidateRecord,
+  SemanticMergeReadiness,
   SemanticIndexRecord,
   SemanticNode,
   SemanticPatchBundle,
@@ -71,6 +73,255 @@ export interface CapabilityResolution {
   readonly reason?: string;
 }
 
+export type NativeImportTaxonomyKind =
+  | 'exactAstImport'
+  | 'declarationsOnly'
+  | 'opaqueBodies'
+  | 'macroExpansion'
+  | 'preprocessor'
+  | 'metaprogramming'
+  | 'generatedCode'
+  | 'sourcePreservation'
+  | 'parserDiagnostics'
+  | 'unsupportedSyntax'
+  | 'partialSemanticIndex'
+  | 'sourceMapApproximation'
+  | string;
+
+export type NativeImportKnownLossKind =
+  | 'declarationOnlyCoverage'
+  | 'opaqueNative'
+  | 'macroExpansion'
+  | 'preprocessor'
+  | 'metaprogramming'
+  | 'generatedCode'
+  | 'sourcePreservation'
+  | 'parserDiagnostic'
+  | 'unsupportedSyntax'
+  | 'partialSemanticIndex'
+  | 'sourceMapApproximation'
+  | string;
+
+export interface NativeImportLossSummaryOptions {
+  readonly exactAst?: boolean;
+  readonly evidence?: readonly EvidenceRecord[];
+  readonly parser?: string;
+  readonly scanKind?: string;
+  readonly semanticStatus?: string;
+}
+
+export interface NativeImportLossSummary {
+  readonly total: number;
+  readonly hasLosses: boolean;
+  readonly exactAst: boolean;
+  readonly highestSeverity: 'none' | NativeAstLossRecord['severity'];
+  readonly semanticMergeReadiness: SemanticMergeReadiness;
+  readonly readinessReasons: readonly string[];
+  readonly categories: readonly NativeImportTaxonomyKind[];
+  readonly bySeverity: Readonly<Record<NativeAstLossRecord['severity'], number>>;
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly blockingLossIds: readonly string[];
+  readonly reviewLossIds: readonly string[];
+  readonly informationalLossIds: readonly string[];
+  readonly failedEvidenceIds: readonly string[];
+  readonly parser?: string;
+  readonly scanKind?: string;
+  readonly semanticStatus?: string;
+}
+
+export interface NativeImportReadinessClassification {
+  readonly readiness: SemanticMergeReadiness;
+  readonly reasons: readonly string[];
+  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 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 interface NativeImporterAdapterDiagnostic {
   readonly id?: string;
   readonly severity?: 'info' | 'warning' | 'error';
@@ -115,6 +366,8 @@ export interface ImportNativeSourceOptions {
   readonly patchId?: string;
   readonly author?: string;
   readonly target?: CompileTarget;
+  readonly targetPath?: string;
+  readonly targetHash?: string;
   readonly semanticIndex?: SemanticIndexRecord;
   readonly sourceMapId?: string;
   readonly sourceMaps?: readonly SourceMapRecord[];
@@ -157,6 +410,56 @@ export interface NativeImporterAdapter {
   readonly parse: (input: NativeImporterAdapterParseInput) => NativeImporterAdapterParseResult | Promise<NativeImporterAdapterParseResult>;
 }
 
+export interface JavaScriptNativeImporterAdapterOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage;
+  readonly parser?: string;
+  readonly version?: string;
+  readonly capabilities?: readonly string[];
+  readonly supportedExtensions?: readonly string[];
+  readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
+  readonly ast?: unknown;
+  readonly parse?: (sourceText: string, options: Record<string, unknown>) => unknown;
+  readonly parserModule?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly babelParser?: { readonly parse: (sourceText: string, options: Record<string, unknown>) => unknown };
+  readonly parserOptions?: Record<string, unknown> | ((input: NativeImporterAdapterParseInput) => Record<string, unknown>);
+  readonly maxNodes?: number;
+}
+
+export interface TypeScriptCompilerNativeImporterAdapterOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage;
+  readonly parser?: string;
+  readonly version?: string;
+  readonly capabilities?: readonly string[];
+  readonly supportedExtensions?: readonly string[];
+  readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
+  readonly typescript?: unknown;
+  readonly ts?: unknown;
+  readonly sourceFile?: unknown;
+  readonly createSourceFile?: (input: NativeImporterAdapterParseInput, typescript?: unknown) => unknown;
+  readonly scriptTarget?: unknown;
+  readonly scriptKind?: unknown;
+  readonly maxNodes?: number;
+  readonly includeTokens?: boolean;
+}
+
+export interface TreeSitterNativeImporterAdapterOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage;
+  readonly parser?: string | { readonly parse?: (sourceText: string) => unknown };
+  readonly parserName?: string;
+  readonly version?: string;
+  readonly capabilities?: readonly string[];
+  readonly supportedExtensions?: readonly string[];
+  readonly diagnostics?: readonly NativeImporterAdapterDiagnostic[];
+  readonly parserInstance?: { readonly parse: (sourceText: string) => unknown };
+  readonly treeSitterParser?: { readonly parse: (sourceText: string) => unknown };
+  readonly parse?: (input: NativeImporterAdapterParseInput) => unknown;
+  readonly tree?: unknown;
+  readonly maxNodes?: number;
+}
+
 export interface NativeImporterAdapterSummary {
   readonly id: string;
   readonly language: FrontierSourceLanguage;
@@ -181,15 +484,126 @@ export type NativeImporterAdapterImportResult = NativeSourceImportResult & {
   readonly diagnostics: readonly NativeImporterAdapterDiagnostic[];
 };
 
+export interface NativeProjectSourceInput extends ImportNativeSourceOptions {
+  readonly adapter?: NativeImporterAdapter | string;
+  readonly adapterOptions?: Record<string, unknown>;
+  readonly adapterMetadata?: Record<string, unknown>;
+}
+
+export interface ImportNativeProjectOptions {
+  readonly id?: string;
+  readonly name?: string;
+  readonly language?: FrontierSourceLanguage | 'mixed';
+  readonly projectRoot?: string;
+  readonly documentId?: string;
+  readonly documentName?: string;
+  readonly documentMetadata?: Record<string, unknown>;
+  readonly universalAstId?: string;
+  readonly universalAstMetadata?: Record<string, unknown>;
+  readonly semanticIndexId?: string;
+  readonly patchId?: string;
+  readonly author?: string;
+  readonly metadata?: Record<string, unknown>;
+  readonly adapterOptions?: Record<string, unknown>;
+  readonly adapterMetadata?: Record<string, unknown>;
+  readonly adapters?: readonly NativeImporterAdapter[];
+  readonly adapterResolver?: (source: NativeProjectSourceInput, adapters: readonly NativeImporterAdapter[]) => NativeImporterAdapter | undefined;
+  readonly sources: readonly NativeProjectSourceInput[];
+}
+
+export interface NativeProjectImportResult {
+  readonly kind: 'frontier.lang.projectImportResult';
+  readonly version: 1;
+  readonly id: string;
+  readonly language: FrontierSourceLanguage | 'mixed';
+  readonly projectRoot?: string;
+  readonly imports: readonly NativeSourceImportResult[];
+  readonly document: FrontierLangDocument;
+  readonly patch: SemanticPatchBundle;
+  readonly nativeSources: readonly NativeSourceNode[];
+  readonly semanticIndex?: SemanticIndexRecord;
+  readonly universalAst: FrontierUniversalAstEnvelope;
+  readonly sourceMaps: readonly SourceMapRecord[];
+  readonly losses: readonly NativeAstLossRecord[];
+  readonly evidence: readonly EvidenceRecord[];
+  readonly mergeCandidates: readonly SemanticMergeCandidateRecord[];
+  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;
 export declare function projectFrontierAst(document: FrontierLangDocument, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetAst;
 export declare function renderTargetAst(ast: FrontierTargetAst, target?: FrontierCompileOptions['target']): string;
 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 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?: {
   readonly id?: string;
   readonly semanticIndex?: SemanticIndexRecord;