@shapeshift-labs/frontier-lang-compiler 0.2.48 → 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

package/bench/native-transform-suite.mjs

@@ -5,6 +5,7 @@ import {
   createSemanticImportSidecar,
   createSemanticSlice,
   createSemanticSliceAdmissionRecord,
+  createUniversalConversionPlan,
   projectNativeImportToSource,
   summarizeNativeImportFeatureEvidence,
   testSemanticSlice
@@ -47,6 +48,13 @@ export function measureNativeTransformations(nativeImportResults) {
   }));
   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, {
     evidence: imported.evidence
@@ -77,6 +85,9 @@ export function measureNativeTransformations(nativeImportResults) {
     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

@@ -57,6 +57,9 @@ console.log(JSON.stringify({
   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,6 +37,7 @@ 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';
@@ -87,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;

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';

package/dist/index.js

@@ -29,6 +29,7 @@ export { createTreeSitterNativeImporterAdapter } from './internal/index-impl/cre
 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';
@@ -62,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/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.48",
+  "version": "0.2.49",
   "description": "Compiler facade for Frontier Lang source documents and language projection adapters.",
   "type": "module",
   "main": "./dist/index.js",