@shapeshift-labs/frontier-lang-compiler 0.2.47 → 0.2.49

package/README.md

@@ -129,6 +129,8 @@ import {
   createNativeParserAstFormatMatrix,
   createProjectionTargetLossMatrix,
   createUniversalCapabilityMatrix,
+  createUniversalConversionPlan,
+  queryUniversalConversionPlan,
   importNativeSource
 } from '@shapeshift-labs/frontier-lang-compiler';
 
@@ -162,6 +164,20 @@ const pythonUniversal = universalMatrix.languages.find((entry) => entry.language
 
 console.log(pythonUniversal.readiness); // combined import/parser/projection readiness
 console.log(pythonUniversal.blockers); // missing evidence/adapters that prevent merge admission
+
+const conversionPlan = createUniversalConversionPlan({
+  imports: [imported],
+  targets: ['python', 'rust'],
+  requiredFeatures: ['syntax', 'semantic', 'sourcePreservation']
+});
+const pythonToRust = queryUniversalConversionPlan(conversionPlan, {
+  sourceLanguage: 'python',
+  target: 'rust'
+}).bestRoute;
+
+console.log(pythonToRust.mode); // "semantic-index-only", "target-adapter", "stub-only", etc.
+console.log(pythonToRust.missingEvidence); // adapter/proof/source-map gaps for swarm workers
+console.log(pythonToRust.mergeScore.value); // sortable merge-review score, not a proof
 ```
 
 The projection target matrix separates five runtime/API classes:
@@ -174,6 +190,8 @@ The projection target matrix separates five runtime/API classes:
 
 `createUniversalCapabilityMatrix` composes the import coverage, parser AST format, parser feature, and projection target matrices into a single language row per source language. It is the coordinator-facing view for universal-language work: it shows imports, symbols, source-map mappings, parser feature readiness, projection targets, missing adapters, unsupported target features, blockers, and review reasons without claiming lossless conversion where evidence is absent.
 
+`createUniversalConversionPlan` turns that capability evidence into coordinator tasks: preserve exact source, run a target adapter, emit stubs, attach semantic-index evidence, or block the route until missing parser/adapter/proof evidence exists. Every route carries `autoMergeClaim: false`, `semanticEquivalenceClaim: false`, missing evidence, task hints, and a `frontier.lang.semanticMergeScore.v1` score for swarm merge admission.
+
 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
@@ -333,6 +351,7 @@ Extract a surgical semantic slice when a worker only needs one symbol, region, n
 
 ```js
 import {
+  createSemanticSliceAdmissionRecord,
   createSemanticSlice,
   importNativeSource,
   testSemanticSlice,
@@ -362,11 +381,16 @@ const gate = testSemanticSlice(slice, {
 });
 
 console.log(gate.status); // "passed", "needs-review", or "failed"
+const admission = createSemanticSliceAdmissionRecord(slice, { testResult: gate });
+console.log(admission.mergeScore.value); // sortable 0-100 semantic merge score
+console.log(admission.autoMergeClaim); // always false
 console.log(writeSemanticSliceJson(slice)); // stable JSON for worker inputs
 ```
 
 A semantic slice is the small unit a swarm can hand to a worker instead of copying a full repository. It carries the selected symbols, ownership regions, native nodes, relations, occurrences, source-map links, source spans, source excerpts, source hashes, focused verification commands, fixture hints, and merge-admission metadata. It does not claim the patch is correct; it makes the context and conflicts machine-readable so admission scoring can combine changed ownership, focused test status, stale/source-hash checks, evidence, and semantic risk in one sortable record.
 
+Slice admission records add a compact `frontier.lang.semanticMergeScore.v1` score with semantic-selection, source-freshness, ownership-isolation, verification-evidence, and review-risk components. They are built for coordinator queues and dashboards: sort likely useful slices first, reject stale or empty slices early, and keep correctness proof separate from merge metadata.
+
 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

package/bench/native-transform-suite.mjs

@@ -4,6 +4,8 @@ import {
   createNativeSourcePreservation,
   createSemanticImportSidecar,
   createSemanticSlice,
+  createSemanticSliceAdmissionRecord,
+  createUniversalConversionPlan,
   projectNativeImportToSource,
   summarizeNativeImportFeatureEvidence,
   testSemanticSlice
@@ -40,6 +42,18 @@ export function measureNativeTransformations(nativeImportResults) {
   const semanticSliceGates = semanticSlices.map((slice) => testSemanticSlice(slice, { requireSourceMapLinks: false }));
   const sliceGateDurationMs = performance.now() - sliceGateStart;
   const sliceGateFailures = semanticSliceGates.filter((gate) => gate.status === 'failed').length;
+  const sliceAdmissionStart = performance.now();
+  const semanticSliceAdmissions = semanticSlices.map((slice, index) => createSemanticSliceAdmissionRecord(slice, {
+    testResult: semanticSliceGates[index]
+  }));
+  const sliceAdmissionDurationMs = performance.now() - sliceAdmissionStart;
+
+  const conversionPlanStart = performance.now();
+  const conversionPlan = createUniversalConversionPlan({
+    imports: nativeImportResults.slice(0, 100),
+    targets: ['javascript', 'rust', 'python']
+  });
+  const conversionPlanDurationMs = performance.now() - conversionPlanStart;
 
   const featureEvidenceStart = performance.now();
   const featureEvidenceSummaries = nativeImportResults.map((imported) => summarizeNativeImportFeatureEvidence(imported.losses, {
@@ -65,9 +79,15 @@ export function measureNativeTransformations(nativeImportResults) {
     semanticSlices: semanticSlices.length,
     sliceDurationMs,
     sliceGateDurationMs,
+    sliceAdmissionDurationMs,
     sliceSourceMapLinks,
     sliceConflictKeys,
     sliceGateFailures,
+    sliceAdmissions: semanticSliceAdmissions.length,
+    sliceAdmissionRejected: semanticSliceAdmissions.filter((admission) => admission.action === 'reject').length,
+    conversionPlanRoutes: conversionPlan.routes.length,
+    conversionPlanBlocked: conversionPlan.summary.blockedRoutes,
+    conversionPlanDurationMs,
     featureEvidencePolicyMatches,
     featureEvidenceDurationMs,
     nativeProjections: nativeProjections.length,

package/bench/smoke.mjs

@@ -51,9 +51,15 @@ console.log(JSON.stringify({
   semanticSlices: transformMetrics.semanticSlices,
   sliceDurationMs: Number(transformMetrics.sliceDurationMs.toFixed(2)),
   sliceGateDurationMs: Number(transformMetrics.sliceGateDurationMs.toFixed(2)),
+  sliceAdmissionDurationMs: Number(transformMetrics.sliceAdmissionDurationMs.toFixed(2)),
   sliceSourceMapLinks: transformMetrics.sliceSourceMapLinks,
   sliceConflictKeys: transformMetrics.sliceConflictKeys,
   sliceGateFailures: transformMetrics.sliceGateFailures,
+  sliceAdmissions: transformMetrics.sliceAdmissions,
+  sliceAdmissionRejected: transformMetrics.sliceAdmissionRejected,
+  conversionPlanRoutes: transformMetrics.conversionPlanRoutes,
+  conversionPlanBlocked: transformMetrics.conversionPlanBlocked,
+  conversionPlanDurationMs: Number(transformMetrics.conversionPlanDurationMs.toFixed(2)),
   featureEvidencePolicyMatches: transformMetrics.featureEvidencePolicyMatches,
   featureEvidenceDurationMs: Number(transformMetrics.featureEvidenceDurationMs.toFixed(2)),
   nativeProjections: transformMetrics.nativeProjections,

package/dist/declarations/runtime.d.ts

@@ -37,12 +37,14 @@ import type { NativeParserFeatureCategory, NativeParserFeatureCoverageStatus, Na
 import type { NativeImportCoverageLanguage, NativeImportCoverageMatrix, NativeImportCoverageMatrixOptions } from './native-import-coverage.js';
 import type { ProjectionTargetLossClass, ProjectionSourceProjectionCoverage, ProjectionTargetCoverageEntry, ProjectionTargetLanguageCoverage, ProjectionTargetLossMatrix, ProjectionTargetLossMatrixOptions } from './projection-coverage.js';
 import type { UniversalCapabilityLanguageRow, UniversalCapabilityMatrix, UniversalCapabilityMatrixOptions } from './universal-capability.js';
+import type { UniversalConversionPlan, UniversalConversionPlanOptions, UniversalConversionPlanQuery, UniversalConversionPlanQueryResult } from './universal-conversion-plan.js';
 import type { UniversalDialectRegistry, UniversalDialectRegistryInput, UniversalDialectRecordInput, UniversalExternRecordInput } from './universal-dialects.js';
 import type { NativeImportContractSource, NativeImportSourcePreservationRecordSummary, NativeImportSourcePreservationContract, NativeImportAdapterCoverageRecordSummary, NativeImportAdapterCoverageContract, NativeImportRegionSummary, NativeImportSourceMapSummary, NativeImportReadinessContract, NativeImportResultContract, NativeImportResultContractOptions } from './native-import-contracts.js';
 import type { NativeSourceTokenKind, NativeSourcePreservedToken, NativeSourcePreservedDirective, NativeSourcePreservation, CreateNativeSourcePreservationOptions } from './source-preservation.js';
 import type { SemanticImportOwnershipRegion, SemanticImportSidecarSymbol, SemanticImportRegionTaxonomySummary, SemanticImportPatchHint, SemanticImportSidecarImportEntry, SemanticImportSidecarSourcePreservationRecord, SemanticImportSidecarUniversalAstLayerSummary, SemanticImportSidecarProofSpecSummary, SemanticImportSidecarParadigmSemanticsSummary, SemanticImportSidecar, SemanticImportSidecarOptions } from './semantic-sidecar.js';
 import type { NativeSourceChangeKind, NativeSourceChangeProjectionEndpoint, NativeSourceChangeProjectionSourceMapLink, NativeSourceChangeProjectionMetadata, NativeSourceChangeProjectionSummary, NativeSourceChangeSymbol, NativeSourceChangeRegion, NativeSourceChangeSummary, DiffNativeSourceImportsOptions, DiffNativeSourcesOptions, NativeSourceChangeSet } from './native-diff.js';
 import type { SemanticSliceInput, CreateSemanticSliceOptions, SemanticSliceSourceMapLink, SemanticSliceSourceFile, SemanticSliceExpectedAssertion, SemanticSlice, TestSemanticSliceOptions, SemanticSliceTestAssertion, SemanticSliceTestResult } from './semantic-slice.js';
+import type { CreateSemanticSliceAdmissionRecordOptions, SemanticSliceAdmissionRecord } from './semantic-slice-admission.js';
 import type { NativeImporterAdapterExactness, NativeImporterAdapterSemanticCoverage, NativeImporterAdapterCoverageSnapshot, NativeImporterAdapterCoverageObserved, NativeImporterAdapterCoverageCapabilityRow, NativeImporterAdapterCoverageCapabilityEvidence, NativeImporterAdapterCoverageSummary, NativeImporterAdapterCoverageInput } from './adapter-coverage.js';
 import type { NativeImporterAdapterDiagnostic, ImportNativeSourceOptions, NativeSourceImportResult, ExternalSemanticIndexFormat, ImportExternalSemanticIndexOptions, ExternalSemanticIndexImportSummary, ExternalSemanticIndexImportResult, NativeImporterAdapterParseInput, NativeImporterAdapterParseResult, NativeImporterAdapter, NativeImporterAdapterSummary, RunNativeImporterAdapterOptions, NativeImporterAdapterImportResult } from './import-adapter-core.js';
 import type { JavaScriptNativeImporterAdapterOptions, TypeScriptCompilerNativeImporterAdapterOptions, PythonAstNativeImporterAdapterOptions, RustSynNativeImporterAdapterOptions, ClangAstNativeImporterAdapterOptions, GoAstNativeImporterAdapterOptions } from './import-adapter-options-native.js';
@@ -86,6 +88,11 @@ export declare function createNativeParserFeatureMatrix(options?: NativeParserFe
 export declare function queryNativeParserFeatureMatrix(matrixOrOptions?: NativeParserFeatureMatrix | NativeParserFeatureMatrixOptions, query?: NativeParserFeatureMatrixQuery): NativeParserFeatureMatrixQueryResult;
 export declare function createProjectionTargetLossMatrix(options?: ProjectionTargetLossMatrixOptions): ProjectionTargetLossMatrix;
 export declare function createUniversalCapabilityMatrix(options?: UniversalCapabilityMatrixOptions): UniversalCapabilityMatrix;
+export declare function createUniversalConversionPlan(options?: UniversalConversionPlanOptions): UniversalConversionPlan;
+export declare function queryUniversalConversionPlan(
+  planOrOptions?: UniversalConversionPlan | UniversalConversionPlanOptions,
+  query?: UniversalConversionPlanQuery
+): UniversalConversionPlanQueryResult;
 export declare function createNativeSourcePreservation(options: CreateNativeSourcePreservationOptions): NativeSourcePreservation;
 export declare function createSemanticImportSidecar(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: SemanticImportSidecarOptions): SemanticImportSidecar;
 export declare function createNativeImportResultContract(importResult: NativeSourceImportResult | NativeProjectImportResult, options?: NativeImportResultContractOptions): NativeImportResultContract;
@@ -109,6 +116,7 @@ export declare function importNativeSource(input: ImportNativeSourceOptions): Na
 export declare function diffNativeSources(input: DiffNativeSourcesOptions): NativeSourceChangeSet;
 export declare function diffNativeSourceImports(input: DiffNativeSourceImportsOptions): NativeSourceChangeSet;
 export declare function createSemanticSlice(input: SemanticSliceInput, options?: CreateSemanticSliceOptions): SemanticSlice;
+export declare function createSemanticSliceAdmissionRecord(slice: SemanticSlice, options?: CreateSemanticSliceAdmissionRecordOptions): SemanticSliceAdmissionRecord;
 export declare function testSemanticSlice(slice: SemanticSlice, options?: TestSemanticSliceOptions): SemanticSliceTestResult;
 export declare function readSemanticSliceJson(source: string): SemanticSlice;
 export declare function writeSemanticSliceJson(slice: SemanticSlice): string;

package/dist/declarations/semantic-slice-admission.d.ts

@@ -0,0 +1,82 @@
+import type { EvidenceRecord, SemanticMergeReadiness } from '@shapeshift-labs/frontier-lang-kernel';
+import type { SemanticSlice, SemanticSliceTestResult, TestSemanticSliceOptions } from './semantic-slice.js';
+
+export type SemanticSliceAdmissionAction = 'admit' | 'prioritize' | 'reject';
+export type SemanticSliceAdmissionPriority = 'low' | 'normal' | 'high' | 'blocker';
+export type SemanticSliceAdmissionRisk = 'low' | 'medium' | 'high' | 'unknown';
+export type SemanticSliceAdmissionScoreComponentKey =
+  | 'semanticSelection'
+  | 'sourceFreshness'
+  | 'ownershipIsolation'
+  | 'verificationEvidence'
+  | 'reviewRisk';
+export type SemanticSliceAdmissionScoreComponentStatus = 'strong' | 'partial' | 'weak' | 'blocked';
+
+export interface SemanticSliceAdmissionScoreComponent {
+  readonly key: SemanticSliceAdmissionScoreComponentKey;
+  readonly score: number;
+  readonly weight: number;
+  readonly weightedScore: number;
+  readonly status: SemanticSliceAdmissionScoreComponentStatus;
+  readonly reasons: readonly string[];
+  readonly signals: Record<string, unknown>;
+}
+
+export interface SemanticSliceAdmissionMergeScore {
+  readonly schema: 'frontier.lang.semanticMergeScore.v1';
+  readonly version: 1;
+  readonly value: number;
+  readonly uncappedValue: number;
+  readonly sortKey: number;
+  readonly higherIsBetter: true;
+  readonly readiness: SemanticMergeReadiness;
+  readonly risk: SemanticSliceAdmissionRisk;
+  readonly action: SemanticSliceAdmissionAction;
+  readonly components: Readonly<Record<SemanticSliceAdmissionScoreComponentKey, SemanticSliceAdmissionScoreComponent>>;
+  readonly penalties: readonly string[];
+}
+
+export interface SemanticSliceAdmissionRecord {
+  readonly kind: 'frontier.lang.semanticSliceAdmission';
+  readonly version: 1;
+  readonly id: string;
+  readonly generatedAt: number;
+  readonly sliceId?: string;
+  readonly importId?: string;
+  readonly sourcePath?: string;
+  readonly action: SemanticSliceAdmissionAction;
+  readonly priority: SemanticSliceAdmissionPriority;
+  readonly readiness: SemanticMergeReadiness;
+  readonly risk: SemanticSliceAdmissionRisk;
+  readonly autoMergeClaim: false;
+  readonly reviewRequired: boolean;
+  readonly mergeScore: SemanticSliceAdmissionMergeScore;
+  readonly counts: {
+    readonly symbols: number;
+    readonly ownershipRegions: number;
+    readonly nativeNodes: number;
+    readonly sourceMapLinks: number;
+    readonly sourceFiles: number;
+    readonly focusedCommands: number;
+    readonly fixtureHints: number;
+    readonly assertions: number;
+    readonly failedAssertions: number;
+    readonly warningAssertions: number;
+  };
+  readonly conflictKeys: readonly string[];
+  readonly ownershipKeys: readonly string[];
+  readonly sourceHashes: SemanticSlice['mergeAdmission']['sourceHashes'];
+  readonly testResult?: SemanticSliceTestResult;
+  readonly reasons: readonly string[];
+  readonly metadata: Record<string, unknown>;
+}
+
+export interface CreateSemanticSliceAdmissionRecordOptions extends TestSemanticSliceOptions {
+  readonly testResult?: SemanticSliceTestResult;
+  readonly evidence?: readonly EvidenceRecord[];
+}
+
+export declare function createSemanticSliceAdmissionRecord(
+  slice: SemanticSlice,
+  options?: CreateSemanticSliceAdmissionRecordOptions
+): SemanticSliceAdmissionRecord;

package/dist/declarations/universal-conversion-plan.d.ts

@@ -0,0 +1,203 @@
+import type {
+  EvidenceRecord,
+  FrontierSourceLanguage,
+  SemanticMergeReadiness
+} from '@shapeshift-labs/frontier-lang-kernel';
+import type { FrontierCompileTarget } from './compile.js';
+import type { NativeImportKnownLossKind } from './native-import-losses.js';
+import type { NativeParserFeatureCategory } from './native-parser-features.js';
+import type { ProjectionSourceProjectionCoverage, ProjectionTargetCoverageEntry } from './projection-coverage.js';
+import type { ProjectionReadinessTargetCell } from './projection-readiness.js';
+import type { UniversalCapabilityMatrix, UniversalCapabilityMatrixOptions } from './universal-capability.js';
+
+export type UniversalConversionRouteMode =
+  | 'preserve-source'
+  | 'target-adapter'
+  | 'stub-only'
+  | 'semantic-index-only'
+  | 'blocked';
+
+export type UniversalConversionRouteAction =
+  | 'preserve-source'
+  | 'run-target-adapter'
+  | 'attach-adapter-evidence'
+  | 'emit-stub'
+  | 'add-target-adapter'
+  | 'blocked';
+
+export type UniversalConversionAdmissionAction = 'admit' | 'prioritize' | 'reject';
+export type UniversalConversionPriority = 'low' | 'normal' | 'high' | 'blocker';
+export type UniversalConversionRisk = 'low' | 'medium' | 'high';
+
+export type UniversalConversionScoreComponentKey =
+  | 'importEvidence'
+  | 'parserEvidence'
+  | 'semanticIndex'
+  | 'projectionPath'
+  | 'proofEvidence';
+
+export interface UniversalConversionScoreComponent {
+  readonly key: UniversalConversionScoreComponentKey;
+  readonly score: number;
+  readonly weight: number;
+  readonly weightedScore: number;
+  readonly status: 'strong' | 'partial' | 'weak' | 'blocked';
+  readonly reasons: readonly string[];
+  readonly signals: Record<string, unknown>;
+}
+
+export interface UniversalConversionMergeScore {
+  readonly schema: 'frontier.lang.semanticMergeScore.v1';
+  readonly version: 1;
+  readonly value: number;
+  readonly uncappedValue: number;
+  readonly sortKey: number;
+  readonly higherIsBetter: true;
+  readonly readiness: SemanticMergeReadiness;
+  readonly risk: UniversalConversionRisk;
+  readonly action: UniversalConversionAdmissionAction;
+  readonly components: Readonly<Record<UniversalConversionScoreComponentKey, UniversalConversionScoreComponent>>;
+  readonly penalties: readonly string[];
+}
+
+export interface UniversalConversionRouteEvidence {
+  readonly imports: number;
+  readonly importReadiness: SemanticMergeReadiness;
+  readonly symbols: number;
+  readonly sourceMaps: number;
+  readonly sourceMapMappings: number;
+  readonly losses: number;
+  readonly parserRows: number;
+  readonly mergeReadyParsers: number;
+  readonly exactSourceImports: number;
+  readonly declarationImports: number;
+  readonly targetSupported: boolean;
+  readonly targetAdapter?: string;
+  readonly targetLossKinds: readonly NativeImportKnownLossKind[];
+}
+
+export interface UniversalConversionRouteMergeRefs {
+  readonly planId: string;
+  readonly routeId: string;
+  readonly historyIds: readonly string[];
+  readonly patchBundleIds: readonly string[];
+  readonly patchIds: readonly string[];
+  readonly mergeCandidateIds: readonly string[];
+  readonly replayLinks: readonly unknown[];
+  readonly evidenceIds: readonly string[];
+  readonly proofIds: readonly string[];
+  readonly sources: readonly {
+    readonly sourceId?: string;
+    readonly importId?: string;
+    readonly sourcePath?: string;
+    readonly sourceHash?: string;
+    readonly baseHash?: string;
+    readonly targetHash?: string;
+  }[];
+  readonly semanticOwnershipKeys: readonly string[];
+  readonly conflictKeys: readonly string[];
+  readonly sourceMapIds: readonly string[];
+  readonly sourceMapMappingIds: readonly string[];
+  readonly sourceMapLinkIds: readonly string[];
+  readonly readiness: SemanticMergeReadiness;
+  readonly admissionStatus: UniversalConversionAdmissionAction;
+  readonly metadata: Record<string, unknown>;
+}
+
+export interface UniversalConversionRoute {
+  readonly id: string;
+  readonly sourceLanguage: FrontierSourceLanguage | string;
+  readonly languageIds: readonly string[];
+  readonly target: FrontierCompileTarget | string;
+  readonly mode: UniversalConversionRouteMode;
+  readonly routeAction: UniversalConversionRouteAction;
+  readonly admissionAction: UniversalConversionAdmissionAction;
+  readonly priority: UniversalConversionPriority;
+  readonly readiness: SemanticMergeReadiness;
+  readonly lossClass: string;
+  readonly adapter?: string;
+  readonly adapterKind?: string;
+  readonly sourceProjection?: {
+    readonly exactSource: ProjectionSourceProjectionCoverage;
+    readonly stubs: ProjectionSourceProjectionCoverage;
+  };
+  readonly projectionReadiness?: ProjectionReadinessTargetCell;
+  readonly evidence: UniversalConversionRouteEvidence;
+  readonly missingEvidence: readonly string[];
+  readonly blockers: readonly string[];
+  readonly review: readonly string[];
+  readonly tasks: readonly string[];
+  readonly mergeScore: UniversalConversionMergeScore;
+  readonly mergeRefs: UniversalConversionRouteMergeRefs;
+  readonly autoMergeClaim: false;
+  readonly semanticEquivalenceClaim: false;
+  readonly metadata: Record<string, unknown>;
+}
+
+export interface UniversalConversionPlan {
+  readonly kind: 'frontier.lang.universalConversionPlan';
+  readonly version: 1;
+  readonly id: string;
+  readonly generatedAt: number;
+  readonly routes: readonly UniversalConversionRoute[];
+  readonly summary: {
+    readonly routes: number;
+    readonly byMode: Readonly<Record<UniversalConversionRouteMode, number>>;
+    readonly byReadiness: Readonly<Record<SemanticMergeReadiness, number>>;
+    readonly byAdmissionAction: Readonly<Record<UniversalConversionAdmissionAction, number>>;
+    readonly readyRoutes: number;
+    readonly reviewRoutes: number;
+    readonly blockedRoutes: number;
+    readonly preserveSourceRoutes: number;
+    readonly targetAdapterRoutes: number;
+    readonly stubOnlyRoutes: number;
+    readonly semanticIndexOnlyRoutes: number;
+    readonly missingEvidence: number;
+    readonly blockers: number;
+    readonly reviewReasons: number;
+    readonly autoMergeClaims: 0;
+    readonly semanticEquivalenceClaims: 0;
+  };
+  readonly matrices: {
+    readonly universalCapability: UniversalCapabilityMatrix;
+    readonly projectionReadiness?: UniversalCapabilityMatrix['matrices']['projectionReadiness'];
+    readonly projectionTargets?: UniversalCapabilityMatrix['matrices']['projectionTargets'];
+  };
+  readonly metadata: {
+    readonly compileTargets: readonly (FrontierCompileTarget | string)[];
+    readonly requiredFeatures: readonly NativeParserFeatureCategory[];
+    readonly autoMergeClaim: false;
+    readonly semanticEquivalenceClaim: false;
+    readonly note: string;
+  };
+}
+
+export interface UniversalConversionPlanOptions extends UniversalCapabilityMatrixOptions {
+  readonly id?: string;
+  readonly universalCapabilityMatrix?: UniversalCapabilityMatrix;
+  readonly evidence?: readonly EvidenceRecord[];
+}
+
+export interface UniversalConversionPlanQuery {
+  readonly sourceLanguage?: FrontierSourceLanguage | string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly target?: FrontierCompileTarget | string;
+  readonly mode?: UniversalConversionRouteMode;
+  readonly readiness?: SemanticMergeReadiness;
+  readonly admissionAction?: UniversalConversionAdmissionAction;
+}
+
+export interface UniversalConversionPlanQueryResult {
+  readonly kind: 'frontier.lang.universalConversionPlanQuery';
+  readonly version: 1;
+  readonly found: boolean;
+  readonly routes: readonly UniversalConversionRoute[];
+  readonly bestRoute?: UniversalConversionRoute;
+  readonly reasons: readonly string[];
+}
+
+export declare function createUniversalConversionPlan(options?: UniversalConversionPlanOptions): UniversalConversionPlan;
+export declare function queryUniversalConversionPlan(
+  planOrOptions?: UniversalConversionPlan | UniversalConversionPlanOptions,
+  query?: UniversalConversionPlanQuery
+): UniversalConversionPlanQueryResult;

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './declarations/native-import-coverage.js';
 export * from './declarations/projection-coverage.js';
 export * from './declarations/projection-readiness.js';
 export * from './declarations/universal-capability.js';
+export * from './declarations/universal-conversion-plan.js';
 export * from './declarations/universal-dialects.js';
 export * from './declarations/language-adapter-package-contracts.js';
 export * from './declarations/native-import-contracts.js';
@@ -17,6 +18,7 @@ export * from './declarations/semantic-patch-bundle.js';
 export * from './declarations/semantic-sidecar.js';
 export * from './declarations/native-diff.js';
 export * from './declarations/semantic-slice.js';
+export * from './declarations/semantic-slice-admission.js';
 export * from './declarations/adapter-coverage.js';
 export * from './declarations/import-adapter-core.js';
 export * from './declarations/import-adapter-options-native.js';

package/dist/index.js

@@ -23,11 +23,13 @@ export { createPythonAstNativeImporterAdapter } from './internal/index-impl/crea
 export { createRustSynNativeImporterAdapter } from './internal/index-impl/createRustSynNativeImporterAdapter.js';
 export { createSemanticImportSidecar } from './internal/index-impl/createSemanticImportSidecar.js';
 export { createSemanticSlice } from './internal/index-impl/createSemanticSlice.js';
+export { createSemanticSliceAdmissionRecord } from './internal/index-impl/createSemanticSliceAdmissionRecord.js';
 export { createSwiftSyntaxNativeImporterAdapter } from './internal/index-impl/createSwiftSyntaxNativeImporterAdapter.js';
 export { createTreeSitterNativeImporterAdapter } from './internal/index-impl/createTreeSitterNativeImporterAdapter.js';
 export { createTypeScriptCompilerNativeImporterAdapter } from './internal/index-impl/createTypeScriptCompilerNativeImporterAdapter.js';
 export { createUniversalAstFromDocument } from './internal/index-impl/createUniversalAstFromDocument.js';
 export { createUniversalCapabilityMatrix } from './internal/index-impl/createUniversalCapabilityMatrix.js';
+export { createUniversalConversionPlan } from './internal/index-impl/createUniversalConversionPlan.js';
 export { attachUniversalDialectRegistry, createUniversalDialectRecord, createUniversalDialectRegistry, createUniversalExternRecord, summarizeUniversalDialectRegistry, UniversalDialectConstructKinds, UniversalDialectProjectionDispositions } from './universal-dialect-registry.js';
 export { diffNativeSourceImports } from './internal/index-impl/diffNativeSourceImports.js';
 export { diffNativeSources } from './internal/index-impl/diffNativeSources.js';
@@ -61,6 +63,7 @@ export { queryNativeParserFeatureMatrix } from './internal/index-impl/queryNativ
 export { queryProjectionReadinessMatrix } from './internal/index-impl/queryProjectionReadinessMatrix.js';
 export { createSemanticPatchBundleRecord, querySemanticPatchBundleRecords, SemanticPatchBundleAdmissionStatuses } from './internal/index-impl/semanticPatchBundleRecords.js';
 export { querySemanticMergeConflictClasses, SemanticMergeConflictClasses, semanticMergeConflictRiskScore, sortSemanticMergeCandidatesByConflictRisk, summarizeSemanticMergeConflicts } from './internal/index-impl/semanticMergeConflicts.js';
+export { queryUniversalConversionPlan } from './internal/index-impl/queryUniversalConversionPlan.js';
 export { createSemanticHistoryRecord, querySemanticHistoryRecordOverlaps, SemanticHistoryAdmissionStatuses, SemanticHistoryConflictReasons, SemanticHistoryOverlapKinds, SemanticHistoryReviewerStatuses, semanticHistoryRecordsConflict, semanticHistoryRecordsOverlap } from './internal/index-impl/semanticHistoryRecords.js';
 export { readSemanticSliceJson } from './internal/index-impl/readSemanticSliceJson.js';
 export { readUniversalAstJson } from './internal/index-impl/readUniversalAstJson.js';

package/dist/internal/index-impl/createSemanticSliceAdmissionRecord.js

@@ -0,0 +1,180 @@
+import{idFragment,maxSemanticMergeReadiness,uniqueStrings}from'../../native-import-utils.js';
+import{testSemanticSlice}from'./testSemanticSlice.js';
+
+const readinessScore=Object.freeze({ready:100,'ready-with-losses':78,'needs-review':48,blocked:0});
+const readinessRank=Object.freeze({ready:3,'ready-with-losses':2,'needs-review':1,blocked:0});
+const actionRank=Object.freeze({admit:2,prioritize:1,reject:0});
+const riskRank=Object.freeze({low:3,medium:2,unknown:1,high:0});
+
+export function createSemanticSliceAdmissionRecord(slice,options={}){
+  const testResult=options.testResult??(options.currentSources?testSemanticSlice(slice,options):undefined);
+  const readiness=worstReadiness(slice?.mergeAdmission?.readiness??slice?.summary?.readiness??'needs-review',testResult?.readiness??'ready');
+  const components={
+    semanticSelection:semanticSelectionScore(slice),
+    sourceFreshness:sourceFreshnessScore(slice,testResult),
+    ownershipIsolation:ownershipIsolationScore(slice),
+    verificationEvidence:verificationEvidenceScore(slice,testResult,options),
+    reviewRisk:reviewRiskScore(slice,readiness,testResult)
+  };
+  const value=mergeScoreValue(components,readiness);
+  const action=admissionAction(slice,readiness,components,testResult);
+  const risk=admissionRisk(readiness,components,testResult);
+  return{
+    kind:'frontier.lang.semanticSliceAdmission',
+    version:1,
+    id:options.id??`semantic_slice_admission_${idFragment(slice?.id??'slice')}`,
+    generatedAt:options.generatedAt??Date.now(),
+    sliceId:slice?.id,
+    importId:slice?.importId,
+    sourcePath:slice?.sourcePath,
+    action,
+    priority:admissionPriority(action,risk,readiness),
+    readiness,
+    risk,
+    autoMergeClaim:false,
+    reviewRequired:action!=='admit'||readiness!=='ready',
+    mergeScore:{
+      schema:'frontier.lang.semanticMergeScore.v1',
+      version:1,
+      value,
+      uncappedValue:value,
+      sortKey:mergeScoreSortKey(value,action,risk,readiness),
+      higherIsBetter:true,
+      readiness,
+      risk,
+      action,
+      components,
+      penalties:uniqueStrings(Object.values(components).flatMap((component)=>component.score<100?component.reasons:[]))
+    },
+    counts:{
+      symbols:slice?.summary?.symbols??slice?.symbols?.length??0,
+      ownershipRegions:slice?.summary?.ownershipRegions??slice?.ownershipRegions?.length??0,
+      nativeNodes:slice?.summary?.nativeNodes??slice?.nativeNodes?.length??0,
+      sourceMapLinks:slice?.summary?.sourceMapLinks??slice?.sourceMapLinks?.length??0,
+      sourceFiles:slice?.summary?.sourceFiles??slice?.sourceFiles?.length??0,
+      focusedCommands:slice?.verification?.focusedCommands?.length??0,
+      fixtureHints:slice?.verification?.fixtureHints?.length??0,
+      assertions:testResult?.summary?.assertions??0,
+      failedAssertions:testResult?.summary?.failed??0,
+      warningAssertions:testResult?.summary?.warnings??0
+    },
+    conflictKeys:uniqueStrings(slice?.mergeAdmission?.conflictKeys??[]),
+    ownershipKeys:uniqueStrings(slice?.mergeAdmission?.ownershipKeys??[]),
+    sourceHashes:slice?.mergeAdmission?.sourceHashes??[],
+    testResult,
+    reasons:uniqueStrings([
+      ...(slice?.mergeAdmission?.reasons??[]),
+      ...Object.values(components).flatMap((component)=>component.reasons)
+    ]),
+    metadata:{
+      note:'Semantic slice admission is sortable merge-review evidence for isolated worker inputs; it is not a correctness proof and never grants auto-merge by itself.',
+      ...(options.metadata??{})
+    }
+  };
+}
+
+function semanticSelectionScore(slice){
+  const symbols=slice?.summary?.symbols??slice?.symbols?.length??0;
+  const regions=slice?.summary?.ownershipRegions??slice?.ownershipRegions?.length??0;
+  const nativeNodes=slice?.summary?.nativeNodes??slice?.nativeNodes?.length??0;
+  const links=slice?.summary?.sourceMapLinks??slice?.sourceMapLinks?.length??0;
+  const unresolved=slice?.summary?.unresolvedEntryRefs??slice?.unresolvedEntryRefs?.length??0;
+  const selected=symbols+regions+nativeNodes;
+  let score=selected>0?70:0;
+  if(symbols>0)score+=12;
+  if(regions>0)score+=10;
+  if(links>0)score+=8;
+  score=Math.max(0,Math.min(100,score-unresolved*25));
+  return scoreComponent('semanticSelection',score,[
+    ...(selected===0?['Slice selected no symbols, ownership regions, or native nodes.']:[]),
+    ...(unresolved?[`${unresolved} semantic slice entry ref(s) did not resolve.`]:[])
+  ],{symbols,ownershipRegions:regions,nativeNodes,sourceMapLinks:links,unresolvedEntryRefs:unresolved});
+}
+
+function sourceFreshnessScore(slice,testResult){
+  const sourceHashes=slice?.mergeAdmission?.sourceHashes??[];
+  const checks=(testResult?.assertions??[]).filter((assertion)=>String(assertion.id??'').startsWith('sourceHash:'));
+  const failed=checks.filter((assertion)=>assertion.status==='failed').length;
+  const warnings=checks.filter((assertion)=>assertion.status==='warning').length;
+  const passed=checks.filter((assertion)=>assertion.status==='passed').length;
+  const score=failed?0:checks.length?Math.max(20,Math.round((passed*100+warnings*55)/checks.length)):sourceHashes.length?55:35;
+  return scoreComponent('sourceFreshness',score,[
+    ...(failed?[`${failed} source hash check(s) failed.`]:[]),
+    ...(!checks.length&&sourceHashes.length?['Slice has source hashes but no current source check was run.']:[]),
+    ...(!sourceHashes.length?['Slice has no source hashes for stale-check admission.']:[])
+  ],{sourceHashes:sourceHashes.length,checks:checks.length,passed,warnings,failed});
+}
+
+function ownershipIsolationScore(slice){
+  const conflictKeys=slice?.mergeAdmission?.conflictKeys?.length??0;
+  const ownershipKeys=slice?.mergeAdmission?.ownershipKeys?.length??0;
+  const reviewRequired=slice?.mergeAdmission?.reviewRequired===true;
+  const score=conflictKeys?Math.max(45,100-Math.max(0,conflictKeys-1)*8-(reviewRequired?16:0)):15;
+  return scoreComponent('ownershipIsolation',score,[
+    ...(!conflictKeys?['Slice exposes no conflict keys for ownership isolation.']:[]),
+    ...(reviewRequired?['Slice merge admission already requires review.']:[])
+  ],{conflictKeys,ownershipKeys,reviewRequired});
+}
+
+function verificationEvidenceScore(slice,testResult,options){
+  const focused=slice?.verification?.focusedCommands?.length??0;
+  const fixtures=slice?.verification?.fixtureHints?.length??0;
+  const evidence=[...(options.evidence??[]),...(slice?.evidence??[])];
+  const failed=(testResult?.summary?.failed??0)+evidence.filter((record)=>record?.status==='failed').length;
+  const warnings=testResult?.summary?.warnings??0;
+  let score=focused||fixtures||evidence.length?72:45;
+  score+=Math.min(18,focused*8+fixtures*4+evidence.length*3);
+  score-=failed*35+warnings*8;
+  return scoreComponent('verificationEvidence',Math.max(0,Math.min(100,score)),[
+    ...(!focused?['Slice has no focused verification command.']:[]),
+    ...(failed?[`${failed} failed assertion or evidence record(s).`]:[])
+  ],{focusedCommands:focused,fixtureHints:fixtures,evidenceRecords:evidence.length,failed,warnings});
+}
+
+function reviewRiskScore(slice,readiness,testResult){
+  const losses=slice?.summary?.losses??slice?.losses?.length??0;
+  const failed=testResult?.summary?.failed??0;
+  const base=readinessScore[readiness]??48;
+  const score=Math.max(0,Math.min(100,base-losses*4-failed*25));
+  return scoreComponent('reviewRisk',score,[
+    ...(readiness!=='ready'?[`Slice readiness is ${readiness}.`]:[]),
+    ...(losses?[`Slice carries ${losses} native import loss record(s).`]:[])
+  ],{readiness,losses,failedAssertions:failed});
+}
+
+function scoreComponent(key,score,reasons,signals){
+  const rounded=Math.round(Math.max(0,Math.min(100,score)));
+  return{key,score:rounded,weight:20,weightedScore:rounded*20/100,status:rounded>=85?'strong':rounded>=60?'partial':rounded>0?'weak':'blocked',reasons,signals};
+}
+
+function mergeScoreValue(components,readiness){
+  const values=Object.values(components);
+  const score=values.reduce((sum,component)=>sum+component.weightedScore,0)/values.reduce((sum,component)=>sum+component.weight,0)*100;
+  return Math.round(Math.max(0,Math.min(readiness==='blocked'?35:100,score)));
+}
+
+function admissionAction(slice,readiness,components,testResult){
+  if(readiness==='blocked'||(testResult?.summary?.failed??0)>0||components.semanticSelection.score===0||components.sourceFreshness.score===0)return'reject';
+  if(readiness!=='ready'||slice?.mergeAdmission?.reviewRequired||Object.values(components).some((component)=>component.score<70))return'prioritize';
+  return'admit';
+}
+
+function admissionRisk(readiness,components,testResult){
+  if(readiness==='blocked'||(testResult?.summary?.failed??0)>0)return'high';
+  if(readiness==='needs-review'||Object.values(components).some((component)=>component.score<60))return'medium';
+  return'low';
+}
+
+function admissionPriority(action,risk,readiness){
+  if(action==='reject')return'blocker';
+  if(readiness==='needs-review'||risk==='medium')return'high';
+  return action==='prioritize'?'normal':'low';
+}
+
+function mergeScoreSortKey(value,action,risk,readiness){
+  return value+(actionRank[action]??0)*1000+(riskRank[risk]??0)*100+(readinessRank[readiness]??0)*10;
+}
+
+function worstReadiness(...values){
+  return values.reduce((current,value)=>maxSemanticMergeReadiness(current,value??'ready'),'ready');
+}

package/dist/internal/index-impl/createUniversalConversionPlan.js

@@ -0,0 +1,5 @@
+import{createUniversalConversionPlan as createUniversalConversionPlanImpl}from'../../universal-conversion-plan.js';
+import{coverageMatrixContext}from'./coverageMatrixContext.js';
+export function createUniversalConversionPlan(input = {}) {
+  return createUniversalConversionPlanImpl(input, coverageMatrixContext());
+}

package/dist/internal/index-impl/queryUniversalConversionPlan.js

@@ -0,0 +1,5 @@
+import{queryUniversalConversionPlan as queryUniversalConversionPlanImpl}from'../../universal-conversion-plan.js';
+import{coverageMatrixContext}from'./coverageMatrixContext.js';
+export function queryUniversalConversionPlan(planOrInput = {}, query = {}) {
+  return queryUniversalConversionPlanImpl(planOrInput, query, coverageMatrixContext());
+}

package/dist/universal-conversion-plan-merge-refs.js

@@ -0,0 +1,125 @@
+import {
+  idFragment,
+  normalizeNativeLanguageId,
+  uniqueStrings
+} from './native-import-utils.js';
+
+export function importsForConversionLanguage(imports, language) {
+  const ids = new Set([language?.language, ...(language?.aliases ?? [])].map(normalizeNativeLanguageId).filter(Boolean));
+  return (imports ?? []).filter((imported) => ids.has(normalizeNativeLanguageId(imported?.language ?? imported?.nativeAst?.language)));
+}
+
+export function conversionMergeRefs(input) {
+  const routeImports = input.imports ?? [];
+  const routeId = input.routeId;
+  const sourceMaps = routeImports.flatMap(sourceMapsForImport);
+  return {
+    planId: input.planId,
+    routeId,
+    historyIds: [`history_${routeId}`],
+    patchBundleIds: [],
+    patchIds: [],
+    mergeCandidateIds: uniqueStrings(routeImports.flatMap(mergeCandidateIds)),
+    replayLinks: routeImports.flatMap((imported) => imported?.replayLinks ?? imported?.universalAst?.replayLinks ?? []),
+    evidenceIds: uniqueStrings(routeImports.flatMap((imported) => evidenceRecords(imported).map((record) => record.id))),
+    proofIds: uniqueStrings(routeImports.flatMap(proofIdsForImport)),
+    sources: routeImports.map(conversionSourceRef),
+    semanticOwnershipKeys: uniqueStrings(routeImports.flatMap(semanticOwnershipKeysForImport)),
+    conflictKeys: uniqueStrings(routeImports.flatMap(conflictKeysForImport)),
+    sourceMapIds: uniqueStrings(sourceMaps.map((sourceMap) => sourceMap?.id)),
+    sourceMapMappingIds: uniqueStrings(sourceMaps.flatMap((sourceMap) => (sourceMap?.mappings ?? []).map((mapping) => mapping.id))),
+    sourceMapLinkIds: [],
+    readiness: input.readiness,
+    admissionStatus: input.admissionStatus,
+    metadata: {
+      plannedHistoryId: true,
+      note: 'Merge refs are compact route provenance for semantic history and patch-bundle builders; planned IDs are not proof records until materialized.'
+    }
+  };
+}
+
+function conversionSourceRef(imported) {
+  return {
+    sourceId: imported?.nativeSource?.id ?? imported?.id,
+    importId: imported?.id,
+    sourcePath: imported?.sourcePath ?? imported?.nativeSource?.sourcePath,
+    sourceHash: imported?.sourceHash
+      ?? imported?.nativeSource?.sourceHash
+      ?? imported?.metadata?.sourcePreservation?.sourceHash,
+    baseHash: imported?.baseHash ?? imported?.metadata?.baseHash,
+    targetHash: imported?.targetHash ?? imported?.metadata?.targetHash
+  };
+}
+
+function evidenceRecords(imported) {
+  return [
+    ...(imported?.evidence ?? []),
+    ...(imported?.universalAst?.evidence ?? []),
+    ...(imported?.patch?.evidence ?? [])
+  ].filter((record) => record?.id);
+}
+
+function proofIdsForImport(imported) {
+  return [
+    ...(imported?.proofIds ?? []),
+    ...evidenceRecords(imported).filter((record) => record?.kind === 'proof' || record?.type === 'proof').map((record) => record.id)
+  ];
+}
+
+function mergeCandidateIds(imported) {
+  return (imported?.mergeCandidates ?? []).map((candidate) => candidate.id);
+}
+
+function sourceMapsForImport(imported) {
+  return [
+    ...(imported?.sourceMaps ?? []),
+    ...(imported?.universalAst?.sourceMaps ?? [])
+  ];
+}
+
+function semanticOwnershipKeysForImport(imported) {
+  return uniqueStrings([
+    ...ownershipKeysFromCandidates(imported),
+    ...ownershipKeysFromSourceMaps(imported),
+    ...ownershipKeysFromSymbols(imported)
+  ]);
+}
+
+function conflictKeysForImport(imported) {
+  return uniqueStrings([
+    ...conflictKeysFromCandidates(imported),
+    ...ownershipKeysFromSourceMaps(imported)
+  ]);
+}
+
+function ownershipKeysFromCandidates(imported) {
+  return uniqueStrings((imported?.mergeCandidates ?? []).flatMap((candidate) => [
+    ...(candidate?.ownershipKeys ?? []),
+    ...(candidate?.semanticOwnershipKeys ?? []),
+    ...(candidate?.changedRegions ?? []).map((region) => region?.key)
+  ]));
+}
+
+function conflictKeysFromCandidates(imported) {
+  return uniqueStrings((imported?.mergeCandidates ?? []).flatMap((candidate) => [
+    ...(candidate?.conflictKeys ?? []),
+    ...(candidate?.changedRegions ?? []).flatMap((region) => [region?.conflictKey, ...(region?.admission?.conflictKeys ?? [])])
+  ]));
+}
+
+function ownershipKeysFromSourceMaps(imported) {
+  return uniqueStrings(sourceMapsForImport(imported).flatMap((sourceMap) => (sourceMap?.mappings ?? []).flatMap((mapping) => [
+    mapping?.ownershipRegionKey,
+    mapping?.ownershipRegionId,
+    mapping?.ownershipRegionKind ? `${mapping.sourceSpan?.path ?? imported?.sourcePath ?? 'source'}#${mapping.ownershipRegionKind}` : undefined
+  ])));
+}
+
+function ownershipKeysFromSymbols(imported) {
+  const symbols = imported?.semanticIndex?.symbols ?? imported?.universalAst?.semanticIndex?.symbols ?? [];
+  return uniqueStrings(symbols.flatMap((symbol) => [
+    symbol?.metadata?.ownershipRegionKey,
+    symbol?.metadata?.ownershipRegionId,
+    symbol?.metadata?.ownershipRegionKind ? `${symbol.language ?? imported?.language ?? 'source'}#${idFragment(symbol.name)}#${symbol.metadata.ownershipRegionKind}` : undefined
+  ]));
+}

package/dist/universal-conversion-plan-scoring.js

@@ -0,0 +1,134 @@
+import { uniqueStrings } from './native-import-utils.js';
+
+const readinessScore = Object.freeze({ ready: 100, 'ready-with-losses': 76, 'needs-review': 48, blocked: 0 });
+const readinessRank = Object.freeze({ ready: 3, 'ready-with-losses': 2, 'needs-review': 1, blocked: 0 });
+const actionRank = Object.freeze({ admit: 2, prioritize: 1, reject: 0 });
+const modeRank = Object.freeze({
+  'preserve-source': 5,
+  'target-adapter': 4,
+  'stub-only': 3,
+  'semantic-index-only': 2,
+  blocked: 0
+});
+const componentWeights = Object.freeze({
+  importEvidence: 22,
+  parserEvidence: 18,
+  semanticIndex: 18,
+  projectionPath: 24,
+  proofEvidence: 18
+});
+
+export function conversionScoreComponents(language, targetCell, readiness, mode, evidence) {
+  return {
+    importEvidence: scoreComponent('importEvidence', readinessScore[language.imports.readiness] ?? 48, [
+      ...(language.imports.total ? [] : ['No source import evidence.']),
+      ...(language.imports.readiness === 'ready' ? [] : [`Import readiness is ${language.imports.readiness}.`])
+    ], { imports: language.imports.total, losses: language.imports.losses }),
+    parserEvidence: scoreComponent('parserEvidence', parserScore(language), [
+      ...(language.parser.rows ? [] : ['No parser feature row matched this language.']),
+      ...(language.parser.blockingFeatures ?? []).map((feature) => `Parser feature is blocked: ${feature}.`)
+    ], { rows: language.parser.rows, mergeReadyParsers: language.parser.mergeReadyParsers.length }),
+    semanticIndex: scoreComponent('semanticIndex', semanticIndexScore(language), [
+      ...(language.imports.symbols ? [] : ['No semantic symbols were imported.']),
+      ...(language.imports.sourceMapMappings ? [] : ['No source-map mappings were imported.'])
+    ], { symbols: language.imports.symbols, sourceMapMappings: language.imports.sourceMapMappings }),
+    projectionPath: scoreComponent('projectionPath', projectionPathScore(targetCell, mode, readiness), projectionPathReasons(targetCell, mode), {
+      mode,
+      lossClass: targetCell?.lossClass,
+      adapter: targetCell?.adapter,
+      readiness
+    }),
+    proofEvidence: scoreComponent('proofEvidence', proofEvidenceScore(evidence), proofEvidenceReasons(evidence), {
+      records: evidence.length,
+      passed: evidence.filter((record) => passedEvidence(record)).length,
+      failed: evidence.filter((record) => record?.status === 'failed').length
+    })
+  };
+}
+
+export function conversionMergeScore(input) {
+  const weighted = Object.values(input.components).reduce((sum, component) => sum + component.weightedScore, 0);
+  const weight = Object.values(input.components).reduce((sum, component) => sum + component.weight, 0);
+  const uncappedValue = Math.round(weight ? weighted * 100 / weight : 0);
+  const action = input.blockers.length || input.readiness === 'blocked' || input.mode === 'blocked' ? 'reject'
+    : input.readiness === 'ready' && input.mode !== 'stub-only' && input.mode !== 'semantic-index-only' ? 'admit'
+      : 'prioritize';
+  const value = action === 'reject' ? Math.min(35, uncappedValue) : uncappedValue;
+  return {
+    schema: 'frontier.lang.semanticMergeScore.v1',
+    version: 1,
+    value,
+    uncappedValue,
+    sortKey: value + (actionRank[action] ?? 0) * 1000 + (modeRank[input.mode] ?? 0) * 100 + (readinessRank[input.readiness] ?? 0) * 10,
+    higherIsBetter: true,
+    readiness: input.readiness,
+    risk: input.readiness === 'blocked' ? 'high' : input.readiness === 'needs-review' ? 'medium' : 'low',
+    action,
+    components: input.components,
+    penalties: uniqueStrings([
+      ...(action === 'reject' ? ['Conversion route is rejected until blockers are resolved.'] : []),
+      ...Object.values(input.components).flatMap((component) => component.score < 100 ? component.reasons : [])
+    ])
+  };
+}
+
+function parserScore(language) {
+  if (!language.parser.rows) return 0;
+  return Math.min(100, (readinessScore[language.parser.readiness] ?? 48) + Math.min(16, language.parser.mergeReadyParsers.length * 8));
+}
+
+function semanticIndexScore(language) {
+  const symbols = language.imports.symbols ?? 0;
+  const mappings = language.imports.sourceMapMappings ?? 0;
+  if (!symbols) return 0;
+  return Math.min(100, 62 + Math.min(22, symbols * 3) + Math.min(16, mappings * 2));
+}
+
+function projectionPathScore(targetCell, mode, readiness) {
+  if (mode === 'blocked') return 0;
+  if (mode === 'preserve-source') return 92;
+  if (mode === 'target-adapter') return Math.min(92, (readinessScore[readiness] ?? 48) + (targetCell?.adapter ? 12 : 0));
+  if (mode === 'stub-only') return 44;
+  if (mode === 'semantic-index-only') return 30;
+  return 10;
+}
+
+function proofEvidenceScore(evidence) {
+  if (!evidence.length) return 45;
+  const passed = evidence.filter((record) => passedEvidence(record)).length;
+  const failed = evidence.filter((record) => record?.status === 'failed').length;
+  return Math.max(0, Math.min(100, 55 + passed * 12 - failed * 35));
+}
+
+function projectionPathReasons(targetCell, mode) {
+  return uniqueStrings([
+    ...(targetCell?.reason ? [targetCell.reason] : []),
+    ...(mode === 'blocked' ? ['Projection path is blocked.'] : []),
+    ...(mode === 'semantic-index-only' ? ['Semantic index can guide review, but code emission needs a target adapter.'] : [])
+  ]);
+}
+
+function proofEvidenceReasons(evidence) {
+  return uniqueStrings([
+    ...(!evidence.length ? ['No proof, oracle, test, or replay evidence was attached to this conversion route.'] : []),
+    ...(evidence.filter((record) => record?.status === 'failed').length ? ['At least one attached evidence record failed.'] : [])
+  ]);
+}
+
+function scoreComponent(key, score, reasons, signals) {
+  const normalized = Math.max(0, Math.min(100, Math.round(score)));
+  const weight = componentWeights[key];
+  return {
+    key,
+    score: normalized,
+    weight,
+    weightedScore: normalized * weight / 100,
+    status: normalized >= 80 ? 'strong' : normalized >= 50 ? 'partial' : normalized > 0 ? 'weak' : 'blocked',
+    reasons: uniqueStrings(reasons),
+    signals
+  };
+}
+
+function passedEvidence(record) {
+  return record?.status === 'passed' || record?.status === 'ok' || record?.status === 'success';
+}

package/dist/universal-conversion-plan.js

@@ -0,0 +1,279 @@
+import {
+  idFragment,
+  maxSemanticMergeReadiness,
+  normalizeNativeLanguageId,
+  uniqueStrings
+} from './native-import-utils.js';
+import {
+  nativeLanguageCompileTarget,
+  normalizeProjectionMatrixTargets
+} from './coverage-matrix-profiles.js';
+import { createUniversalCapabilityMatrix } from './universal-capability-matrix.js';
+import {
+  conversionMergeRefs,
+  importsForConversionLanguage
+} from './universal-conversion-plan-merge-refs.js';
+import {
+  conversionMergeScore,
+  conversionScoreComponents
+} from './universal-conversion-plan-scoring.js';
+
+export function createUniversalConversionPlan(input = {}, context = {}) {
+  const generatedAt = input.generatedAt ?? Date.now();
+  const id = input.id ?? conversionPlanId(input, generatedAt);
+  const matrix = input.universalCapabilityMatrix?.kind === 'frontier.lang.universalCapabilityMatrix'
+    ? input.universalCapabilityMatrix
+    : createUniversalCapabilityMatrix({ ...input, generatedAt }, context);
+  const targets = conversionTargets(input, matrix, context);
+  const evidence = input.evidence ?? [];
+  const routes = (matrix.languages ?? []).flatMap((language) => targets.map((target) => conversionRoute(language, target, {
+    evidence,
+    generatedAt,
+    imports: input.imports ?? [],
+    matrix
+  }, id)));
+  return {
+    kind: 'frontier.lang.universalConversionPlan',
+    version: 1,
+    id,
+    generatedAt,
+    routes,
+    summary: conversionPlanSummary(routes),
+    matrices: {
+      universalCapability: matrix,
+      projectionReadiness: matrix.matrices?.projectionReadiness,
+      projectionTargets: matrix.matrices?.projectionTargets
+    },
+    metadata: {
+      compileTargets: targets,
+      requiredFeatures: matrix.metadata?.requiredFeatures ?? [],
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      note: 'Conversion plans rank source-to-target routes and missing evidence for agent coordination. They do not prove semantic equivalence or grant auto-merge.'
+    }
+  };
+}
+
+export function queryUniversalConversionPlan(planOrInput = {}, query = {}, context = {}) {
+  const plan = planOrInput?.kind === 'frontier.lang.universalConversionPlan'
+    ? planOrInput
+    : createUniversalConversionPlan(planOrInput, context);
+  const sourceLanguage = normalizeNativeLanguageId(query.sourceLanguage ?? query.language);
+  const target = normalizeProjectionMatrixTargets(query.target ? [query.target] : [])[0];
+  const routes = (plan.routes ?? []).filter((route) => {
+    if (sourceLanguage && !route.languageIds.includes(sourceLanguage)) return false;
+    if (target && route.target !== target) return false;
+    if (query.mode && route.mode !== query.mode) return false;
+    if (query.readiness && route.readiness !== query.readiness) return false;
+    if (query.admissionAction && route.admissionAction !== query.admissionAction) return false;
+    return true;
+  });
+  return {
+    kind: 'frontier.lang.universalConversionPlanQuery',
+    version: 1,
+    found: routes.length > 0,
+    routes,
+    bestRoute: routes.slice().sort((a, b) => b.mergeScore.sortKey - a.mergeScore.sortKey)[0],
+    reasons: routes.length ? [] : [`No conversion route matched source=${query.sourceLanguage ?? query.language ?? '*'} target=${query.target ?? '*'}.`]
+  };
+}
+
+function conversionTargets(input, matrix, context) {
+  const explicit = normalizeProjectionMatrixTargets(input.targets ?? []);
+  if (explicit.length) return explicit;
+  const matrixTargets = normalizeProjectionMatrixTargets(matrix.metadata?.compileTargets ?? []);
+  if (matrixTargets.length) return matrixTargets;
+  return normalizeProjectionMatrixTargets(context.compileTargets ?? []);
+}
+
+function conversionRoute(language, target, input, planId) {
+  const sourceTarget = nativeLanguageCompileTarget(language.language, language.aliases) ?? normalizeNativeLanguageId(language.language);
+  const targetCell = (language.projection?.targets ?? []).find((entry) => entry.target === target);
+  const readinessCell = projectionReadinessCell(input.matrix, language, target);
+  const mode = conversionMode(language, target, sourceTarget, targetCell);
+  const blockers = conversionBlockers(language, targetCell, mode);
+  const review = conversionReviewReasons(language, targetCell, mode);
+  const readiness = blockers.length
+    ? 'blocked'
+    : maxSemanticMergeReadiness(language.readiness, targetCell?.readiness ?? readinessCell?.readiness ?? 'needs-review');
+  const components = conversionScoreComponents(language, targetCell, readiness, mode, input.evidence);
+  const mergeScore = conversionMergeScore({ readiness, mode, components, blockers, review });
+  const id = `conversion_${idFragment(language.language)}_to_${idFragment(target)}`;
+  const routeImports = importsForConversionLanguage(input.imports, language);
+  return {
+    id,
+    sourceLanguage: language.language,
+    languageIds: uniqueStrings([language.language, ...(language.aliases ?? [])].map(normalizeNativeLanguageId)),
+    target,
+    mode,
+    routeAction: conversionRouteAction(mode, targetCell, readiness),
+    admissionAction: mergeScore.action,
+    priority: conversionPriority(mergeScore.action, readiness, mode),
+    readiness,
+    lossClass: mode === 'preserve-source' ? 'exactSourceProjection' : targetCell?.lossClass ?? 'missingAdapter',
+    adapter: targetCell?.adapter,
+    adapterKind: targetCell?.adapterKind,
+    sourceProjection: language.projection?.sourceProjection,
+    projectionReadiness: readinessCell,
+    evidence: conversionEvidence(language, targetCell),
+    missingEvidence: conversionMissingEvidence(language, targetCell, mode),
+    blockers,
+    review,
+    tasks: conversionTasks(language, target, mode, blockers, review),
+    mergeScore,
+    mergeRefs: conversionMergeRefs({
+      planId,
+      routeId: id,
+      imports: routeImports,
+      readiness,
+      admissionStatus: mergeScore.action
+    }),
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    metadata: {
+      generatedAt: input.generatedAt,
+      note: 'Route readiness is merge-review evidence for a conversion attempt, not proof that emitted target code is semantically equivalent.'
+    }
+  };
+}
+
+function conversionPlanId(input, generatedAt) {
+  const languages = uniqueStrings((input.imports ?? []).map((imported) => imported?.language ?? imported?.nativeAst?.language));
+  const targets = normalizeProjectionMatrixTargets(input.targets ?? []);
+  return `universal_conversion_plan_${idFragment([...languages, 'to', ...targets, String(generatedAt)].join('_'))}`;
+}
+
+function conversionMode(language, target, sourceTarget, targetCell) {
+  const exactSourceImports = language.projection?.sourceProjection?.exactSource?.evidence?.importsWithExactSource ?? 0;
+  if (target === sourceTarget && exactSourceImports > 0) return 'preserve-source';
+  if (targetCell?.lossClass === 'targetAdapterProjection') return 'target-adapter';
+  if (targetCell?.lossClass === 'nativeSourceStubs') return 'stub-only';
+  if (targetCell?.lossClass === 'unsupportedTargetFeatures') return 'target-adapter';
+  if ((language.imports?.symbols ?? 0) > 0 && targetCell?.lossClass === 'missingAdapter') return 'semantic-index-only';
+  return 'blocked';
+}
+
+function conversionBlockers(language, targetCell, mode) {
+  return uniqueStrings([
+    ...(language.imports.total === 0 ? ['No source import exists for this language.'] : []),
+    ...(mode === 'blocked' ? ['No viable preserve, adapter, stub, or semantic-index conversion route exists.'] : []),
+    ...(targetCell?.lossClass === 'missingAdapter' && mode !== 'semantic-index-only' ? [targetCell.reason] : []),
+    ...(language.blockers ?? []).filter((reason) => !reason.includes('Missing native-to-target projection adapter'))
+  ]);
+}
+
+function conversionReviewReasons(language, targetCell, mode) {
+  return uniqueStrings([
+    ...(language.review ?? []),
+    ...(targetCell?.reason ? [targetCell.reason] : []),
+    ...(mode === 'stub-only' ? ['Route can emit declaration stubs only; executable semantics require a target adapter.'] : []),
+    ...(mode === 'semantic-index-only' ? ['Route has semantic index evidence but no target code projection adapter.'] : []),
+    ...(mode === 'target-adapter' ? ['Host target adapter evidence must be reviewed before accepting emitted target code.'] : [])
+  ]);
+}
+
+function projectionReadinessCell(matrix, language, target) {
+  const ids = uniqueStrings([language.language, ...(language.aliases ?? [])].map(normalizeNativeLanguageId));
+  return (matrix.matrices?.projectionReadiness?.languages ?? [])
+    .find((row) => ids.includes(normalizeNativeLanguageId(row.language)))
+    ?.targets?.find((entry) => entry.target === target);
+}
+
+function conversionRouteAction(mode, targetCell, readiness) {
+  if (mode === 'blocked') return 'blocked';
+  if (mode === 'preserve-source') return 'preserve-source';
+  if (mode === 'stub-only') return 'emit-stub';
+  if (mode === 'semantic-index-only') return 'add-target-adapter';
+  if (targetCell?.lossClass === 'unsupportedTargetFeatures') return 'attach-adapter-evidence';
+  return 'run-target-adapter';
+}
+
+function conversionPriority(action, readiness, mode) {
+  if (action === 'reject' || readiness === 'blocked') return 'blocker';
+  if (mode === 'semantic-index-only' || readiness === 'needs-review') return 'high';
+  if (mode === 'stub-only' || readiness === 'ready-with-losses') return 'normal';
+  return 'low';
+}
+
+function conversionEvidence(language, targetCell) {
+  return {
+    imports: language.imports.total,
+    importReadiness: language.imports.readiness,
+    symbols: language.imports.symbols,
+    sourceMaps: language.imports.sourceMaps,
+    sourceMapMappings: language.imports.sourceMapMappings,
+    losses: language.imports.losses,
+    parserRows: language.parser.rows,
+    mergeReadyParsers: language.parser.mergeReadyParsers.length,
+    exactSourceImports: language.projection?.sourceProjection?.exactSource?.evidence?.importsWithExactSource ?? 0,
+    declarationImports: language.projection?.sourceProjection?.stubs?.evidence?.importsWithDeclarations ?? 0,
+    targetSupported: targetCell?.supported === true,
+    targetAdapter: targetCell?.adapter,
+    targetLossKinds: targetCell?.lossKinds ?? []
+  };
+}
+
+function conversionMissingEvidence(language, targetCell, mode) {
+  return uniqueStrings([
+    ...(language.imports.total ? [] : ['source-import']),
+    ...(language.imports.symbols ? [] : ['semantic-index']),
+    ...(language.imports.sourceMapMappings ? [] : ['source-map']),
+    ...(language.parser.mergeReadyParsers.length ? [] : ['merge-ready-parser']),
+    ...((language.projection?.sourceProjection?.exactSource?.evidence?.importsWithExactSource ?? 0) ? [] : ['source-preservation-hash']),
+    ...(mode === 'target-adapter' && !targetCell?.adapter ? ['target-adapter-evidence'] : []),
+    ...(mode === 'semantic-index-only' || targetCell?.lossClass === 'missingAdapter' ? ['target-adapter'] : []),
+    ...(mode === 'stub-only' ? ['executable-target-semantics'] : []),
+    ['proof-or-replay-evidence']
+  ]);
+}
+
+function conversionTasks(language, target, mode, blockers, review) {
+  return uniqueStrings([
+    ...(language.imports.total ? [] : [`import ${language.language} source before planning ${target} output`]),
+    ...(language.imports.symbols ? [] : [`attach semantic index for ${language.language}`]),
+    ...(language.parser.mergeReadyParsers.length ? [] : [`provide merge-ready parser evidence for ${language.language}`]),
+    ...(mode === 'semantic-index-only' || mode === 'blocked' ? [`add ${language.language} to ${target} target adapter`] : []),
+    ...(mode === 'stub-only' ? [`replace ${target} declaration stubs with executable adapter output`] : []),
+    ...(mode === 'target-adapter' ? [`run and verify ${language.language} to ${target} target adapter`] : []),
+    ...(blockers.length || review.length ? [`collect proof, replay, or oracle evidence for ${language.language} to ${target}`] : [])
+  ]);
+}
+
+function conversionPlanSummary(routes) {
+  const summary = {
+    routes: routes.length,
+    byMode: {},
+    byReadiness: {},
+    byAdmissionAction: {},
+    readyRoutes: 0,
+    reviewRoutes: 0,
+    blockedRoutes: 0,
+    preserveSourceRoutes: 0,
+    targetAdapterRoutes: 0,
+    stubOnlyRoutes: 0,
+    semanticIndexOnlyRoutes: 0,
+    missingEvidence: 0,
+    blockers: 0,
+    reviewReasons: 0,
+    autoMergeClaims: 0,
+    semanticEquivalenceClaims: 0
+  };
+  for (const route of routes) {
+    summary.byMode[route.mode] = (summary.byMode[route.mode] ?? 0) + 1;
+    summary.byReadiness[route.readiness] = (summary.byReadiness[route.readiness] ?? 0) + 1;
+    summary.byAdmissionAction[route.admissionAction] = (summary.byAdmissionAction[route.admissionAction] ?? 0) + 1;
+    if (route.readiness === 'ready') summary.readyRoutes += 1;
+    if (route.readiness === 'needs-review' || route.readiness === 'ready-with-losses') summary.reviewRoutes += 1;
+    if (route.readiness === 'blocked') summary.blockedRoutes += 1;
+    if (route.mode === 'preserve-source') summary.preserveSourceRoutes += 1;
+    if (route.mode === 'target-adapter') summary.targetAdapterRoutes += 1;
+    if (route.mode === 'stub-only') summary.stubOnlyRoutes += 1;
+    if (route.mode === 'semantic-index-only') summary.semanticIndexOnlyRoutes += 1;
+    summary.missingEvidence += route.missingEvidence.length;
+    summary.blockers += route.blockers.length;
+    summary.reviewReasons += route.review.length;
+    if (route.autoMergeClaim) summary.autoMergeClaims += 1;
+    if (route.semanticEquivalenceClaim) summary.semanticEquivalenceClaims += 1;
+  }
+  return summary;
+}

package/package.json

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