@shapeshift-labs/frontier-lang-compiler 0.2.17 → 0.2.19

package/README.md

@@ -147,6 +147,51 @@ console.log(sidecar.ownershipRegions[0].key); // source#src/runtime.ts#class#Run
 console.log(sidecar.patchHints[0].supportedOperations); // source-region patch operations
 ```
 
+Compare before/after native source imports from a worker patch and emit a semantic change set for admission scoring:
+
+```js
+import { diffNativeSources } from '@shapeshift-labs/frontier-lang-compiler';
+
+const changeSet = diffNativeSources({
+  language: 'javascript',
+  sourcePath: 'src/runtime.js',
+  beforeSourceText: 'export function step(frame) { return frame + 1; }\n',
+  afterSourceText: 'export function step(frame) { return frame + 2; }\n'
+});
+
+console.log(changeSet.changedSymbols[0]?.changeKind); // "modified"
+console.log(changeSet.changedRegions[0]?.conflictKey); // semantic ownership key
+console.log(changeSet.mergeCandidate.readiness); // merge-admission classification
+```
+
+Use `diffNativeSourceImports` when the worker or runner already produced `importNativeSource` results. Body-only edits that the lightweight scanner cannot anchor to a symbol are still reported as file-level changed regions instead of being silently treated as safe.
+
+Compile native source imports through the same reader/IR/writer facade that swarms use for sidecar evidence. Same-language targets preserve exact source when hashes match; cross-language targets emit declaration stubs until a real adapter provides stronger evidence:
+
+```js
+import { compileNativeSource } from '@shapeshift-labs/frontier-lang-compiler';
+
+const compiledJs = compileNativeSource({
+  language: 'javascript',
+  sourcePath: 'src/runtime.js',
+  sourceText: 'export function step(frame) { return frame + 1; }\n'
+});
+
+console.log(compiledJs.outputMode); // "preserved-source"
+console.log(compiledJs.readiness.readiness); // scanner imports can still be "needs-review"
+
+const rustCandidate = compileNativeSource(compiledJs.importResult, {
+  target: 'rust',
+  emitOnBlocked: true
+});
+
+console.log(rustCandidate.outputMode); // "target-stubs"
+console.log(rustCandidate.targetCoverage.lossClass); // "missingAdapter" without a JS-to-Rust adapter
+console.log(rustCandidate.ok); // true only because emitOnBlocked requested code anyway
+```
+
+`compileNativeSource` returns the import result, projection, target loss matrix cell, combined losses, readiness, evidence, and output hash. Admission queues should treat `ok` as "code was emitted", not as merge approval; `readiness` and `targetCoverage` carry the merge signal.
+
 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

package/bench/smoke.mjs

@@ -1,5 +1,6 @@
 import { performance } from 'node:perf_hooks';
 import {
+  compileNativeSource,
   compileFrontierSource,
   createEstreeNativeImporterAdapter,
   createNativeImportCoverageMatrix,
@@ -92,6 +93,15 @@ const nativeProjections = nativeImportResults.map((imported) => projectNativeImp
 const projectionDurationMs = performance.now() - projectionStart;
 const projectionBytes = nativeProjections.reduce((sum, projection) => sum + projection.sourceText.length, 0);
 
+const nativeCompileStart = performance.now();
+const nativeCompiles = nativeImportResults.map((imported, index) => compileNativeSource(imported, {
+  target: index % 2 === 0 ? 'javascript' : 'rust',
+  emitOnBlocked: true
+}));
+const nativeCompileDurationMs = performance.now() - nativeCompileStart;
+const nativeCompileBytes = nativeCompiles.reduce((sum, result) => sum + result.output.length, 0);
+const nativeCompileBlocked = nativeCompiles.filter((result) => result.readiness.readiness === 'blocked').length;
+
 console.log(JSON.stringify({
   compiles: 250,
   bytes,
@@ -118,5 +128,9 @@ console.log(JSON.stringify({
   sidecarDurationMs: Number(sidecarDurationMs.toFixed(2)),
   nativeProjections: nativeProjections.length,
   projectionBytes,
-  projectionDurationMs: Number(projectionDurationMs.toFixed(2))
+  projectionDurationMs: Number(projectionDurationMs.toFixed(2)),
+  nativeCompiles: nativeCompiles.length,
+  nativeCompileBytes,
+  nativeCompileBlocked,
+  nativeCompileDurationMs: Number(nativeCompileDurationMs.toFixed(2))
 }));

package/dist/index.d.ts

@@ -730,6 +730,100 @@ export interface SemanticImportSidecarOptions {
   readonly metadata?: Record<string, unknown>;
 }
 
+export type NativeSourceChangeKind = 'added' | 'removed' | 'modified' | 'unchanged';
+
+export interface NativeSourceChangeSymbol {
+  readonly changeKind: NativeSourceChangeKind;
+  readonly key: string;
+  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 beforeSignatureHash?: string;
+  readonly afterSignatureHash?: string;
+  readonly beforeSpanHash?: string;
+  readonly afterSpanHash?: string;
+  readonly beforeOwnershipKey?: string;
+  readonly afterOwnershipKey?: string;
+  readonly ownershipRegionId?: string;
+  readonly ownershipKey?: string;
+  readonly ownershipRegionKind?: NativeImportRegionTaxonomyKind;
+  readonly conflictKey: string;
+  readonly readiness: SemanticMergeReadiness;
+}
+
+export interface NativeSourceChangeRegion extends SemanticImportOwnershipRegion {
+  readonly changeKind: NativeSourceChangeKind;
+  readonly conflictKey: string;
+}
+
+export interface NativeSourceChangeSummary {
+  readonly sourceChanged: boolean;
+  readonly symbols: number;
+  readonly regions: number;
+  readonly addedSymbols: number;
+  readonly removedSymbols: number;
+  readonly modifiedSymbols: number;
+  readonly byRegionKind: Readonly<Record<string, number>>;
+  readonly byChangeKind: Readonly<Record<string, number>>;
+}
+
+export interface DiffNativeSourceImportsOptions {
+  readonly id?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly parser?: string;
+  readonly before?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly after?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly beforeSourceHash?: string;
+  readonly afterSourceHash?: string;
+  readonly generatedAt?: number;
+  readonly regionPrefix?: string;
+  readonly evidenceId?: string;
+  readonly evidenceStatus?: EvidenceRecord['status'];
+  readonly patchId?: string;
+  readonly mergeCandidateId?: string;
+  readonly author?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface DiffNativeSourcesOptions extends Omit<DiffNativeSourceImportsOptions, 'before' | 'after'> {
+  readonly before?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly after?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly beforeSourceText?: string;
+  readonly afterSourceText?: string;
+  readonly beforeMetadata?: Record<string, unknown>;
+  readonly afterMetadata?: Record<string, unknown>;
+}
+
+export interface NativeSourceChangeSet {
+  readonly kind: 'frontier.lang.nativeSourceChangeSet';
+  readonly version: 1;
+  readonly id: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly before?: NativeSourceImportResult;
+  readonly after?: NativeSourceImportResult;
+  readonly beforeHash?: string;
+  readonly afterHash?: string;
+  readonly changedSymbols: readonly NativeSourceChangeSymbol[];
+  readonly changedRegions: readonly NativeSourceChangeRegion[];
+  readonly patch: SemanticPatchBundle;
+  readonly mergeCandidate: SemanticMergeCandidateRecord;
+  readonly evidence: readonly EvidenceRecord[];
+  readonly readiness: SemanticMergeReadiness;
+  readonly reasons: readonly string[];
+  readonly sourceMaps: readonly SourceMapRecord[];
+  readonly semanticIndex?: SemanticIndexRecord;
+  readonly losses: readonly NativeAstLossRecord[];
+  readonly summary: NativeSourceChangeSummary;
+  readonly metadata?: Record<string, unknown>;
+}
+
 export type NativeImporterAdapterExactness =
   | 'exact-parser-ast'
   | 'parser-tree'
@@ -1127,6 +1221,43 @@ export interface NativeSourceProjectionResult {
   readonly metadata: Record<string, unknown>;
 }
 
+export type NativeSourceCompileOutputMode = NativeSourceProjectionMode | 'target-stubs';
+
+export interface CompileNativeSourceOptions extends ProjectNativeImportToSourceOptions {
+  readonly target?: FrontierCompileTarget | string;
+  readonly adapters?: readonly NativeImporterAdapter[];
+  readonly languages?: readonly NativeImportLanguageProfile[];
+  readonly generatedAt?: number;
+  readonly emitOnBlocked?: boolean;
+  readonly projectionId?: string;
+  readonly projectionEvidenceId?: string;
+  readonly compileEvidenceId?: string;
+  readonly evidence?: readonly EvidenceRecord[];
+  readonly losses?: readonly NativeAstLossRecord[];
+}
+
+export interface NativeSourceCompileResult {
+  readonly kind: 'frontier.lang.nativeSourceCompileResult';
+  readonly version: 1;
+  readonly id: string;
+  readonly ok: boolean;
+  readonly target: FrontierCompileTarget | string;
+  readonly language: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly output: string;
+  readonly outputHash: string;
+  readonly outputMode: NativeSourceCompileOutputMode;
+  readonly importResult: NativeSourceImportResult;
+  readonly projection: NativeSourceProjectionResult;
+  readonly targetCoverage: ProjectionTargetCoverageEntry;
+  readonly projectionMatrix: ProjectionTargetLossMatrix;
+  readonly losses: readonly NativeAstLossRecord[];
+  readonly lossSummary: NativeImportLossSummary;
+  readonly readiness: NativeImportReadinessClassification;
+  readonly evidence: readonly EvidenceRecord[];
+  readonly metadata: Record<string, unknown>;
+}
+
 export type NativeImportRoundtripReadinessStatus =
   | 'exact'
   | 'preserved-source'
@@ -1192,6 +1323,7 @@ export declare const NativeImportLanguageProfiles: readonly NativeImportLanguage
 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 compileNativeSource(input: ImportNativeSourceOptions | NativeSourceImportResult, options?: CompileNativeSourceOptions): NativeSourceCompileResult;
 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 renderTargetAstWithSourceMap(ast: FrontierTargetAst, target?: FrontierCompileOptions['target'], options?: FrontierCompileEmitOptions): FrontierTargetSourceMapResult;
@@ -1212,6 +1344,8 @@ export declare function createTreeSitterNativeImporterAdapter(options?: TreeSitt
 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 diffNativeSources(input: DiffNativeSourcesOptions): NativeSourceChangeSet;
+export declare function diffNativeSourceImports(input: DiffNativeSourceImportsOptions): NativeSourceChangeSet;
 export declare function importNativeProject(input: ImportNativeProjectOptions): Promise<NativeProjectImportResult>;
 export declare function createUniversalAstFromDocument(document: FrontierLangDocument, input?: {
   readonly id?: string;

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   createNativeAstRecord,
   createPatch,
   createSemanticIndexRecord,
+  createSemanticMergeCandidateRecord,
   createSourceMapRecord,
   createUniversalAstEnvelope,
   hashDocumentBase,
@@ -252,6 +253,116 @@ export function compileFrontierDocument(document, options = {}) {
   };
 }
 
+export function compileNativeSource(input, options = {}) {
+  const importResult = isNativeSourceImportResult(input) ? input : importNativeSource(input);
+  const sourceLanguage = nativeCompileSourceLanguage(importResult, input);
+  const target = nativeCompileTarget(input, importResult, options);
+  const sourceTarget = nativeLanguageCompileTarget(sourceLanguage);
+  const sameSourceTarget = sourceTarget === target;
+  const idPart = idFragment(options.id ?? importResult.id ?? importResult.sourcePath ?? sourceLanguage ?? target);
+  const id = options.id ?? `native_source_compile_${idPart}_${idFragment(target)}`;
+  const projection = projectNativeImportToSource(importResult, {
+    ...options,
+    id: options.projectionId ?? `${id}_projection`,
+    language: sameSourceTarget ? sourceLanguage : target,
+    preferPreservedSource: sameSourceTarget ? options.preferPreservedSource : false,
+    evidenceId: options.projectionEvidenceId ?? options.evidenceId,
+    metadata: {
+      sourceLanguage,
+      target,
+      nativeCompileResultId: id,
+      ...options.metadata
+    }
+  });
+  const projectionMatrix = createProjectionTargetLossMatrix({
+    imports: [importResult],
+    adapters: options.adapters,
+    languages: options.languages,
+    targets: [target],
+    generatedAt: options.generatedAt
+  });
+  const targetCoverage = nativeSourceCompileTargetCoverage(projectionMatrix, sourceLanguage, target);
+  const targetLosses = nativeSourceCompileTargetLosses({
+    importResult,
+    projection,
+    targetCoverage,
+    sourceLanguage,
+    target,
+    idPart
+  });
+  const outputMode = sameSourceTarget ? projection.mode : 'target-stubs';
+  const compileEvidence = nativeSourceCompileEvidence({
+    id: options.compileEvidenceId ?? `evidence_${idPart}_${idFragment(target)}_native_source_compile`,
+    importResult,
+    projection,
+    targetCoverage,
+    targetLosses,
+    sourceLanguage,
+    target,
+    outputMode
+  });
+  const evidence = uniqueByEvidenceId([
+    ...(importResult.evidence ?? []),
+    ...(projection.evidence ?? []),
+    compileEvidence,
+    ...(options.evidence ?? [])
+  ]);
+  const losses = uniqueByLossId([
+    ...(importResult.losses ?? []),
+    ...(projection.losses ?? []),
+    ...targetLosses,
+    ...(options.losses ?? [])
+  ]);
+  const lossSummary = summarizeNativeImportLosses(losses, {
+    evidence,
+    parser: importResult.nativeAst?.parser ?? importResult.nativeSource?.parser ?? options.parser,
+    scanKind: 'native-source-compile',
+    semanticStatus: importResult.metadata?.semanticStatus ?? options.semanticStatus
+  });
+  const readiness = classifyNativeImportReadiness(losses, {
+    evidence,
+    parser: importResult.nativeAst?.parser ?? importResult.nativeSource?.parser ?? options.parser,
+    scanKind: 'native-source-compile',
+    semanticStatus: importResult.metadata?.semanticStatus ?? options.semanticStatus
+  });
+  return {
+    kind: 'frontier.lang.nativeSourceCompileResult',
+    version: 1,
+    id,
+    ok: readiness.readiness !== 'blocked' || options.emitOnBlocked === true,
+    target,
+    language: sourceLanguage,
+    sourcePath: importResult.sourcePath ?? importResult.nativeSource?.sourcePath,
+    output: projection.sourceText,
+    outputHash: projection.outputHash,
+    outputMode,
+    importResult,
+    projection,
+    targetCoverage,
+    projectionMatrix,
+    losses,
+    lossSummary,
+    readiness,
+    evidence,
+    metadata: {
+      nativeImportId: importResult.id,
+      nativeSourceId: importResult.nativeSource?.id,
+      nativeAstId: importResult.nativeAst?.id ?? importResult.nativeSource?.ast?.id,
+      semanticIndexId: importResult.semanticIndex?.id ?? importResult.universalAst?.semanticIndex?.id,
+      universalAstId: importResult.universalAst?.id,
+      projectionId: projection.id,
+      projectionMode: projection.mode,
+      outputMode,
+      sourceTarget,
+      sameSourceTarget,
+      targetLossClass: targetCoverage.lossClass,
+      targetReadiness: targetCoverage.readiness,
+      targetSupported: targetCoverage.supported,
+      ...options.metadata
+    }
+  };
+}
+
 export function projectFrontierAst(document, target = 'typescript', options = {}) {
   const normalized = normalizeCompileTarget(target);
   const projector = projectors[normalized];
@@ -1416,6 +1527,410 @@ export function importNativeSource(input) {
   };
 }
 
+export function diffNativeSources(input) {
+  const language = input.language ?? input.before?.language ?? input.after?.language;
+  if (!language) throw new Error('diffNativeSources requires a language');
+  const sourcePath = input.sourcePath ?? input.before?.sourcePath ?? input.after?.sourcePath;
+  return diffNativeSourceImports({
+    ...input,
+    before: input.before ?? (input.beforeSourceText === undefined ? undefined : {
+      language,
+      sourcePath,
+      sourceText: input.beforeSourceText,
+      sourceHash: input.beforeSourceHash,
+      parser: input.parser,
+      metadata: input.beforeMetadata
+    }),
+    after: input.after ?? (input.afterSourceText === undefined ? undefined : {
+      language,
+      sourcePath,
+      sourceText: input.afterSourceText,
+      sourceHash: input.afterSourceHash,
+      parser: input.parser,
+      metadata: input.afterMetadata
+    })
+  });
+}
+
+export function diffNativeSourceImports(input) {
+  const before = normalizeNativeDiffImport(input.before, input, 'before');
+  const after = normalizeNativeDiffImport(input.after, input, 'after');
+  if (!before && !after) throw new Error('diffNativeSourceImports requires before or after native source input');
+  const language = input.language ?? after?.language ?? before?.language;
+  const sourcePath = input.sourcePath ?? after?.sourcePath ?? before?.sourcePath;
+  const beforeHash = before?.nativeSource?.sourceHash ?? before?.nativeAst?.sourceHash ?? before?.sourceHash;
+  const afterHash = after?.nativeSource?.sourceHash ?? after?.nativeAst?.sourceHash ?? after?.sourceHash;
+  const idPart = idFragment(input.id ?? sourcePath ?? language ?? 'native_source_change');
+  const beforeSidecar = before ? createSemanticImportSidecar(before, { id: `sidecar_before_${idPart}`, generatedAt: input.generatedAt, regionPrefix: input.regionPrefix }) : undefined;
+  const afterSidecar = after ? createSemanticImportSidecar(after, { id: `sidecar_after_${idPart}`, generatedAt: input.generatedAt, regionPrefix: input.regionPrefix }) : undefined;
+  const beforeSymbols = mapDiffSymbols(before, beforeSidecar);
+  const afterSymbols = mapDiffSymbols(after, afterSidecar);
+  const changedSymbols = diffNativeSymbols(beforeSymbols, afterSymbols);
+  let changedRegions = diffNativeOwnershipRegions(beforeSidecar, afterSidecar, changedSymbols);
+  const sourceChanged = Boolean(beforeHash && afterHash && beforeHash !== afterHash);
+  if (sourceChanged && changedSymbols.length === 0 && changedRegions.length === 0) {
+    changedRegions = [fileLevelNativeChangeRegion({ language, sourcePath, beforeHash, afterHash, before, after })];
+  }
+  const evidence = [{
+    id: input.evidenceId ?? `evidence_${idPart}_native_source_diff`,
+    kind: 'import',
+    status: input.evidenceStatus ?? 'passed',
+    path: sourcePath,
+    summary: `Compared ${language ?? 'native'} source imports: ${changedSymbols.length} changed symbol(s), ${changedRegions.length} changed region(s).`,
+    metadata: {
+      beforeImportId: before?.id,
+      afterImportId: after?.id,
+      beforeHash,
+      afterHash,
+      sourceChanged,
+      addedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'added').length,
+      removedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'removed').length,
+      modifiedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'modified').length
+    }
+  }];
+  const readiness = maxSemanticMergeReadiness(
+    maxSemanticMergeReadiness(nativeImportReadiness(before), nativeImportReadiness(after)),
+    sourceChanged && changedSymbols.length === 0 ? 'needs-review' : 'ready'
+  );
+  const reasons = nativeSourceChangeReasons({ before, after, beforeHash, afterHash, changedSymbols, changedRegions, readiness });
+  const conflictKeys = uniqueStrings([
+    ...changedSymbols.map((symbol) => symbol.conflictKey),
+    ...changedRegions.map((region) => region.conflictKey ?? region.key ?? region.id),
+    ...(sourcePath ? [`source:${sourcePath}`] : [])
+  ]);
+  const touches = changedRegions.map((region) => ({ id: region.id, access: 'write' }));
+  const operations = [
+    ...(after?.nativeSource ? [{ op: 'upsertNode', node: after.nativeSource, touches: touches.length ? touches : [{ id: after.nativeSource.id, access: 'evidence' }] }] : []),
+    ...(!after && before?.nativeSource ? [{ op: 'removeNode', id: before.nativeSource.id, touches: touches.length ? touches : [{ id: before.nativeSource.id, access: 'evidence' }] }] : []),
+    { op: 'addEvidence', evidence: evidence[0], touches }
+  ];
+  const patch = createPatch({
+    id: input.patchId ?? `patch_${idPart}_native_source_diff`,
+    baseHash: beforeHash,
+    targetHash: afterHash,
+    author: input.author ?? '@shapeshift-labs/frontier-lang-compiler/diffNativeSourceImports',
+    risk: readiness === 'blocked' ? 'high' : readiness === 'needs-review' ? 'medium' : 'low',
+    operations,
+    evidence,
+    metadata: {
+      sourceLanguage: language,
+      sourcePath,
+      beforeImportId: before?.id,
+      afterImportId: after?.id,
+      beforeHash,
+      afterHash,
+      changedSymbols: changedSymbols.length,
+      changedRegions: changedRegions.length
+    }
+  });
+  const mergeCandidate = createSemanticMergeCandidateRecord({
+    id: input.mergeCandidateId ?? `merge_candidate_${idPart}_native_source_diff`,
+    importResultId: after?.id ?? before?.id,
+    patchId: patch.id,
+    language,
+    sourcePath,
+    baseHash: beforeHash,
+    targetHash: afterHash,
+    touchedSymbols: changedSymbols.map(nativeChangeTouchedSymbol),
+    touchedSemanticNodes: [],
+    nativeSpans: nativeChangeSpans(changedSymbols, changedRegions, { language, sourcePath }),
+    conflictKeys,
+    readiness,
+    reasons,
+    evidence,
+    metadata: {
+      kind: 'native-source-change-set',
+      beforeImportId: before?.id,
+      afterImportId: after?.id,
+      sourceChanged,
+      changeSummary: nativeSourceChangeSummary(changedSymbols, changedRegions, sourceChanged)
+    }
+  });
+  return {
+    kind: 'frontier.lang.nativeSourceChangeSet',
+    version: 1,
+    id: input.id ?? `native_source_change_${idPart}`,
+    language,
+    sourcePath,
+    before,
+    after,
+    beforeHash,
+    afterHash,
+    changedSymbols,
+    changedRegions,
+    patch,
+    mergeCandidate,
+    evidence,
+    readiness,
+    reasons,
+    sourceMaps: uniqueRecordsById([...(before?.sourceMaps ?? []), ...(after?.sourceMaps ?? [])]),
+    semanticIndex: after?.semanticIndex ?? before?.semanticIndex,
+    losses: uniqueByLossId([...(before?.losses ?? []), ...(after?.losses ?? [])]),
+    summary: nativeSourceChangeSummary(changedSymbols, changedRegions, sourceChanged),
+    metadata: {
+      beforeSidecarId: beforeSidecar?.id,
+      afterSidecarId: afterSidecar?.id,
+      beforeImportContract: before?.metadata?.importResultContract,
+      afterImportContract: after?.metadata?.importResultContract,
+      ...input.metadata
+    }
+  };
+}
+
+function normalizeNativeDiffImport(value, input, side) {
+  if (!value) return undefined;
+  if (value.kind === 'frontier.lang.importResult' && value.nativeSource) return value;
+  return importNativeSource({
+    ...value,
+    language: value.language ?? input.language,
+    sourcePath: value.sourcePath ?? input.sourcePath,
+    parser: value.parser ?? input.parser,
+    metadata: {
+      ...(value.metadata ?? {}),
+      nativeSourceDiffSide: side
+    }
+  });
+}
+
+function mapDiffSymbols(imported, sidecar) {
+  const symbolsById = new Map((imported?.semanticIndex?.symbols ?? []).map((symbol) => [symbol.id, symbol]));
+  const mappingsBySymbolId = new Map((imported?.sourceMaps ?? [])
+    .flatMap((sourceMap) => sourceMap.mappings ?? [])
+    .filter((mapping) => mapping.semanticSymbolId)
+    .map((mapping) => [mapping.semanticSymbolId, mapping]));
+  const sourceText = nativeImportSourceText(imported);
+  const entries = sidecar?.symbols?.length
+    ? sidecar.symbols
+    : (imported?.semanticIndex?.symbols ?? []).map((symbol) => ({ id: symbol.id, name: symbol.name, kind: symbol.kind, sourceSpan: symbol.definitionSpan }));
+  const result = new Map();
+  for (const entry of entries) {
+    const symbol = symbolsById.get(entry.id) ?? {};
+    const mapping = mappingsBySymbolId.get(entry.id);
+    const sourceSpan = entry.sourceSpan ?? mapping?.sourceSpan ?? symbol.definitionSpan;
+    const key = nativeDiffSymbolKey(entry, imported);
+    result.set(key, {
+      key,
+      id: entry.id,
+      name: entry.name ?? symbol.name,
+      kind: entry.kind ?? symbol.kind,
+      language: entry.language ?? symbol.language ?? imported?.language,
+      nativeAstNodeId: entry.nativeAstNodeId ?? symbol.nativeAstNodeId ?? mapping?.nativeAstNodeId,
+      semanticOccurrenceId: entry.semanticOccurrenceId ?? mapping?.semanticOccurrenceId,
+      sourceMapMappingId: entry.sourceMapMappingId ?? mapping?.id,
+      sourceSpan,
+      signatureHash: entry.signatureHash ?? symbol.signatureHash,
+      ownershipRegionId: entry.ownershipRegionId ?? symbol.metadata?.ownershipRegionId ?? mapping?.ownershipRegionId,
+      ownershipKey: entry.ownershipKey ?? symbol.metadata?.ownershipRegionKey ?? mapping?.ownershipRegionKey,
+      ownershipRegionKind: entry.ownershipRegionKind ?? symbol.metadata?.ownershipRegionKind ?? mapping?.ownershipRegionKind,
+      spanHash: hashNativeSpanText(sourceText, sourceSpan),
+      sourcePath: sourceSpan?.path ?? imported?.sourcePath,
+      sourceHash: imported?.nativeSource?.sourceHash ?? imported?.nativeAst?.sourceHash,
+      readiness: entry.readiness ?? imported?.metadata?.semanticMergeReadiness ?? imported?.mergeCandidates?.[0]?.readiness ?? 'needs-review'
+    });
+  }
+  return result;
+}
+
+function diffNativeSymbols(beforeSymbols, afterSymbols) {
+  const keys = uniqueStrings([...beforeSymbols.keys(), ...afterSymbols.keys()]).sort();
+  const changed = [];
+  for (const key of keys) {
+    const before = beforeSymbols.get(key);
+    const after = afterSymbols.get(key);
+    const changeKind = !before ? 'added' : !after ? 'removed' : nativeDiffSymbolChanged(before, after) ? 'modified' : 'unchanged';
+    if (changeKind === 'unchanged') continue;
+    const current = after ?? before;
+    changed.push({
+      changeKind,
+      key,
+      id: current.id,
+      name: current.name,
+      kind: current.kind,
+      language: current.language,
+      nativeAstNodeId: current.nativeAstNodeId,
+      semanticOccurrenceId: current.semanticOccurrenceId,
+      sourceMapMappingId: current.sourceMapMappingId,
+      sourceSpan: current.sourceSpan,
+      beforeSignatureHash: before?.signatureHash,
+      afterSignatureHash: after?.signatureHash,
+      beforeSpanHash: before?.spanHash,
+      afterSpanHash: after?.spanHash,
+      beforeOwnershipKey: before?.ownershipKey,
+      afterOwnershipKey: after?.ownershipKey,
+      ownershipRegionId: current.ownershipRegionId,
+      ownershipKey: current.ownershipKey,
+      ownershipRegionKind: current.ownershipRegionKind,
+      conflictKey: current.ownershipKey ? `region:${current.ownershipKey}` : `symbol:${current.id ?? key}`,
+      readiness: maxSemanticMergeReadiness(before?.readiness ?? 'ready', after?.readiness ?? 'ready')
+    });
+  }
+  return changed;
+}
+
+function nativeDiffSymbolChanged(before, after) {
+  if ((before.signatureHash ?? '') !== (after.signatureHash ?? '')) return true;
+  if ((before.spanHash ?? '') !== (after.spanHash ?? '')) return true;
+  if ((before.ownershipKey ?? '') !== (after.ownershipKey ?? '')) return true;
+  if ((before.nativeAstNodeId ?? '') !== (after.nativeAstNodeId ?? '')) return true;
+  return false;
+}
+
+function diffNativeOwnershipRegions(beforeSidecar, afterSidecar, changedSymbols) {
+  const changedRegionIds = new Set(changedSymbols.map((symbol) => symbol.ownershipRegionId).filter(Boolean));
+  const changedRegionKeys = new Set([
+    ...changedSymbols.map((symbol) => symbol.beforeOwnershipKey).filter(Boolean),
+    ...changedSymbols.map((symbol) => symbol.afterOwnershipKey).filter(Boolean)
+  ]);
+  const regions = uniqueRecordsById([...(beforeSidecar?.ownershipRegions ?? []), ...(afterSidecar?.ownershipRegions ?? [])])
+    .filter((region) => changedRegionIds.has(region.id) || changedRegionKeys.has(region.key));
+  return regions.map((region) => ({
+    ...region,
+    changeKind: changedSymbols.some((symbol) => symbol.changeKind === 'added' && symbol.afterOwnershipKey === region.key)
+      ? 'added'
+      : changedSymbols.some((symbol) => symbol.changeKind === 'removed' && symbol.beforeOwnershipKey === region.key)
+        ? 'removed'
+        : 'modified',
+    conflictKey: region.key ? `region:${region.key}` : `region:${region.id}`
+  }));
+}
+
+function fileLevelNativeChangeRegion(input) {
+  const sourcePath = input.sourcePath ?? input.after?.sourcePath ?? input.before?.sourcePath;
+  const key = ['source', sourcePath ?? `${input.language}:memory`, 'file'].join('#');
+  return {
+    id: `region_${idFragment(key)}`,
+    key,
+    changeKind: 'modified',
+    regionKind: 'body',
+    granularity: 'file',
+    language: input.language,
+    sourcePath,
+    sourceHash: input.afterHash ?? input.beforeHash,
+    precision: 'unknown',
+    mergePolicy: 'file-level-review-required',
+    conflictKey: `region:${key}`,
+    metadata: {
+      reason: 'source-hash-changed-without-symbol-diff',
+      beforeHash: input.beforeHash,
+      afterHash: input.afterHash
+    }
+  };
+}
+
+function nativeImportReadiness(imported) {
+  return imported?.metadata?.semanticMergeReadiness
+    ?? imported?.metadata?.nativeImportLossSummary?.semanticMergeReadiness
+    ?? imported?.mergeCandidates?.[0]?.readiness
+    ?? 'ready';
+}
+
+function nativeSourceChangeReasons(input) {
+  if (!input.before) return ['Native source was added.'];
+  if (!input.after) return ['Native source was removed.'];
+  if (input.changedSymbols.length) {
+    return [`Native source changed ${input.changedSymbols.length} symbol(s) across ${input.changedRegions.length} ownership region(s).`];
+  }
+  if (input.beforeHash && input.afterHash && input.beforeHash !== input.afterHash) {
+    return ['Native source hash changed without declaration-level symbol changes; file-level review is required.'];
+  }
+  return ['Native source imports are semantically unchanged at available scanner precision.'];
+}
+
+function nativeChangeTouchedSymbol(symbol) {
+  return {
+    id: symbol.id ?? symbol.key,
+    name: symbol.name,
+    kind: symbol.kind,
+    nativeAstNodeId: symbol.nativeAstNodeId,
+    span: symbol.sourceSpan,
+    conflictKey: symbol.conflictKey,
+    metadata: {
+      changeKind: symbol.changeKind,
+      beforeSignatureHash: symbol.beforeSignatureHash,
+      afterSignatureHash: symbol.afterSignatureHash,
+      beforeSpanHash: symbol.beforeSpanHash,
+      afterSpanHash: symbol.afterSpanHash,
+      ownershipRegionId: symbol.ownershipRegionId,
+      ownershipRegionKind: symbol.ownershipRegionKind
+    }
+  };
+}
+
+function nativeChangeSpans(changedSymbols, changedRegions, input) {
+  const symbolSpans = changedSymbols
+    .filter((symbol) => symbol.sourceSpan)
+    .map((symbol) => ({
+      id: `native_span_${idFragment(symbol.id ?? symbol.key)}`,
+      sourceId: symbol.sourceSpan?.sourceId,
+      path: symbol.sourceSpan?.path ?? input.sourcePath,
+      language: symbol.language ?? input.language,
+      nativeAstNodeId: symbol.nativeAstNodeId,
+      symbolId: symbol.id,
+      span: symbol.sourceSpan,
+      conflictKey: symbol.conflictKey,
+      metadata: { changeKind: symbol.changeKind }
+    }));
+  const regionSpans = changedRegions
+    .filter((region) => region.sourceSpan || region.sourcePath)
+    .map((region) => ({
+      id: `native_span_${idFragment(region.id)}`,
+      path: region.sourceSpan?.path ?? region.sourcePath ?? input.sourcePath,
+      language: region.language ?? input.language,
+      nativeAstNodeId: region.nativeAstNodeId,
+      symbolId: region.symbolId,
+      span: region.sourceSpan,
+      conflictKey: region.conflictKey ?? `region:${region.key ?? region.id}`,
+      metadata: { changeKind: region.changeKind, regionKind: region.regionKind, granularity: region.granularity }
+    }));
+  return uniqueRecordsById([...symbolSpans, ...regionSpans]);
+}
+
+function nativeSourceChangeSummary(changedSymbols, changedRegions, sourceChanged) {
+  return {
+    sourceChanged,
+    symbols: changedSymbols.length,
+    regions: changedRegions.length,
+    addedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'added').length,
+    removedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'removed').length,
+    modifiedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'modified').length,
+    byRegionKind: countBy(changedRegions.map((region) => region.regionKind ?? 'unknown')),
+    byChangeKind: countBy([...changedSymbols.map((symbol) => symbol.changeKind), ...changedRegions.map((region) => region.changeKind)])
+  };
+}
+
+function nativeDiffSymbolKey(symbol, imported) {
+  return [
+    symbol.language ?? imported?.language,
+    symbol.kind ?? 'symbol',
+    symbol.name ?? symbol.id
+  ].map((part) => String(part ?? '').trim()).join(':');
+}
+
+function nativeImportSourceText(imported) {
+  return imported?.metadata?.sourcePreservation?.sourceText
+    ?? imported?.nativeSource?.metadata?.sourcePreservation?.sourceText
+    ?? imported?.nativeAst?.metadata?.sourcePreservation?.sourceText
+    ?? imported?.universalAst?.metadata?.sourcePreservation?.sourceText;
+}
+
+function hashNativeSpanText(sourceText, span) {
+  const text = sourceTextForSpan(sourceText, span);
+  return text === undefined ? undefined : hashSemanticValue(text);
+}
+
+function sourceTextForSpan(sourceText, span) {
+  if (typeof sourceText !== 'string' || !span) return undefined;
+  if (typeof span.start === 'number' && typeof span.end === 'number' && span.end >= span.start) {
+    return sourceText.slice(span.start, span.end);
+  }
+  if (typeof span.startLine === 'number') {
+    const lines = sourceText.split(/\r?\n/);
+    const endLine = typeof span.endLine === 'number' && span.endLine >= span.startLine ? span.endLine : span.startLine;
+    return lines.slice(span.startLine - 1, endLine).join('\n');
+  }
+  return undefined;
+}
+
 function createLightweightNativeImport(input) {
   const parser = input.parser ?? `${input.language}.lightweight-declaration-scan`;
   const rootId = 'native_root';
@@ -3670,6 +4185,159 @@ function nativeLanguageCompileTarget(language, aliases = []) {
   return undefined;
 }
 
+function isNativeSourceImportResult(input) {
+  return Boolean(input && typeof input === 'object' && input.kind === 'frontier.lang.importResult' && input.nativeSource && input.universalAst);
+}
+
+function nativeCompileSourceLanguage(importResult, input) {
+  return normalizeNativeLanguageId(
+    importResult.language
+      ?? importResult.nativeSource?.language
+      ?? importResult.nativeAst?.language
+      ?? importResult.nativeSource?.ast?.language
+      ?? input?.language
+  ) || String(importResult.language ?? input?.language ?? 'source');
+}
+
+function nativeCompileTarget(input, importResult, options) {
+  const targetInput = options.target
+    ?? compileTargetLanguage(input?.target)
+    ?? compileTargetLanguage(importResult.nativeSource?.target)
+    ?? nativeLanguageCompileTarget(nativeCompileSourceLanguage(importResult, input))
+    ?? 'typescript';
+  return normalizeProjectionMatrixTargets([targetInput])[0] ?? String(targetInput ?? 'typescript').toLowerCase();
+}
+
+function compileTargetLanguage(target) {
+  if (!target) return undefined;
+  if (typeof target === 'string') return target;
+  return target.language ?? target.emitLanguage ?? target.target ?? target.name;
+}
+
+function nativeSourceCompileTargetCoverage(matrix, language, target) {
+  const sourceLanguage = normalizeNativeLanguageId(language);
+  const entry = (matrix.languages ?? []).find((candidate) => {
+    const ids = [candidate.language, ...(candidate.aliases ?? [])].map(normalizeNativeLanguageId);
+    return ids.includes(sourceLanguage);
+  });
+  const coverage = entry?.targets?.find((candidate) => candidate.target === target);
+  if (coverage) return coverage;
+  return {
+    target,
+    lossClass: 'missingAdapter',
+    supported: false,
+    readiness: 'blocked',
+    lossKinds: ['targetProjectionLoss'],
+    categories: ['targetProjectionLoss'],
+    reason: `No native-to-${target} projection coverage is available for ${language}.`,
+    adapter: undefined,
+    notes: ['Inject a source-language parser and target projection adapter before treating this cross-language output as merge-ready.']
+  };
+}
+
+function nativeSourceCompileTargetLosses(input) {
+  const { importResult, projection, targetCoverage, sourceLanguage, target, idPart } = input;
+  if (!targetCoverage || targetCoverage.lossClass === 'exactSourceProjection') return [];
+  if (targetCoverage.lossClass === 'missingAdapter') {
+    return [nativeSourceCompileTargetLoss({
+      id: `loss_${idPart}_${idFragment(target)}_missing_projection_adapter`,
+      severity: 'error',
+      message: targetCoverage.reason,
+      importResult,
+      projection,
+      targetCoverage,
+      sourceLanguage,
+      target
+    })];
+  }
+  if (targetCoverage.lossClass === 'unsupportedTargetFeatures') {
+    return [nativeSourceCompileTargetLoss({
+      id: `loss_${idPart}_${idFragment(target)}_unsupported_target_features`,
+      severity: 'warning',
+      message: targetCoverage.reason,
+      importResult,
+      projection,
+      targetCoverage,
+      sourceLanguage,
+      target
+    })];
+  }
+  if (targetCoverage.lossClass === 'nativeSourceStubs') {
+    return [nativeSourceCompileTargetLoss({
+      id: `loss_${idPart}_${idFragment(target)}_target_stubs`,
+      severity: 'warning',
+      message: targetCoverage.reason,
+      importResult,
+      projection,
+      targetCoverage,
+      sourceLanguage,
+      target
+    })];
+  }
+  return [];
+}
+
+function nativeSourceCompileTargetLoss(input) {
+  const rootSpan = input.importResult.nativeAst?.nodes?.[input.importResult.nativeAst?.rootId]?.span
+    ?? input.importResult.nativeSource?.ast?.nodes?.[input.importResult.nativeSource?.ast?.rootId]?.span;
+  return {
+    id: input.id,
+    severity: input.severity,
+    phase: 'emit',
+    sourceFormat: input.sourceLanguage,
+    kind: 'targetProjectionLoss',
+    message: input.message,
+    span: rootSpan ?? {
+      sourceId: input.importResult.nativeSource?.sourceHash ?? input.importResult.sourceHash,
+      path: input.importResult.sourcePath ?? input.importResult.nativeSource?.sourcePath,
+      startLine: 1,
+      startColumn: 1
+    },
+    metadata: {
+      target: input.target,
+      sourceLanguage: input.sourceLanguage,
+      projectionId: input.projection.id,
+      projectionMode: input.projection.mode,
+      targetLossClass: input.targetCoverage.lossClass,
+      targetReadiness: input.targetCoverage.readiness,
+      targetSupported: input.targetCoverage.supported,
+      targetAdapter: input.targetCoverage.adapter,
+      targetLossKinds: input.targetCoverage.lossKinds,
+      lossCategory: 'targetProjectionLoss',
+      semanticMergeAdmission: semanticMergeAdmissionForSeverity(input.severity)
+    }
+  };
+}
+
+function nativeSourceCompileEvidence(input) {
+  const failed = input.targetLosses.some((loss) => loss.severity === 'error')
+    || input.projection.evidence?.some((record) => record.status === 'failed')
+    || input.targetCoverage.readiness === 'blocked';
+  return {
+    id: input.id,
+    kind: 'projection',
+    status: failed ? 'failed' : 'passed',
+    path: input.importResult.sourcePath ?? input.importResult.nativeSource?.sourcePath,
+    summary: failed
+      ? `Compiled ${input.sourceLanguage} native source to ${input.target} with blocked projection evidence.`
+      : `Compiled ${input.sourceLanguage} native source to ${input.target} as ${input.outputMode}.`,
+    metadata: {
+      importId: input.importResult.id,
+      projectionId: input.projection.id,
+      sourceLanguage: input.sourceLanguage,
+      target: input.target,
+      outputHash: input.projection.outputHash,
+      outputMode: input.outputMode,
+      projectionMode: input.projection.mode,
+      targetLossClass: input.targetCoverage.lossClass,
+      targetReadiness: input.targetCoverage.readiness,
+      targetSupported: input.targetCoverage.supported,
+      targetReason: input.targetCoverage.reason,
+      targetLossIds: input.targetLosses.map((loss) => loss.id)
+    }
+  };
+}
+
 function nativeProjectionTargetsForLanguage(language, aliases = []) {
   const target = nativeLanguageCompileTarget(language, aliases);
   return target ? [target] : [];

package/package.json

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