@shapeshift-labs/frontier-lang-compiler 0.2.48 → 0.2.50

package/README.md

@@ -129,6 +129,9 @@ import {
   createNativeParserAstFormatMatrix,
   createProjectionTargetLossMatrix,
   createUniversalCapabilityMatrix,
+  createUniversalConversionArtifacts,
+  createUniversalConversionPlan,
+  queryUniversalConversionPlan,
   importNativeSource
 } from '@shapeshift-labs/frontier-lang-compiler';
 
@@ -162,6 +165,24 @@ 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
+
+const conversionArtifacts = createUniversalConversionArtifacts(conversionPlan);
+console.log(conversionArtifacts.historyRecords[0].kind); // "frontier.lang.semanticHistoryRecord"
+console.log(conversionArtifacts.patchBundleRecords[0].admission.autoMergeClaim); // false
 ```
 
 The projection target matrix separates five runtime/API classes:
@@ -174,6 +195,10 @@ 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.
+
+`createUniversalConversionArtifacts` materializes those route refs into compact `SemanticHistoryRecord` and `SemanticPatchBundleRecord` artifacts that swarm collectors can index by route, history ID, patch-bundle ID, source path, ownership key, conflict key, evidence, proof, readiness, and admission status. It is still review evidence, not target-code proof: blocked and semantic-index-only routes stay blocked/needs-review, and every artifact keeps `autoMergeClaim: false` plus `semanticEquivalenceClaim: false`.
+
 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,8 @@ import {
   createSemanticImportSidecar,
   createSemanticSlice,
   createSemanticSliceAdmissionRecord,
+  createUniversalConversionArtifacts,
+  createUniversalConversionPlan,
   projectNativeImportToSource,
   summarizeNativeImportFeatureEvidence,
   testSemanticSlice
@@ -47,6 +49,16 @@ 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 conversionArtifactsStart = performance.now();
+  const conversionArtifacts = createUniversalConversionArtifacts(conversionPlan);
+  const conversionArtifactsDurationMs = performance.now() - conversionArtifactsStart;
+
   const featureEvidenceStart = performance.now();
   const featureEvidenceSummaries = nativeImportResults.map((imported) => summarizeNativeImportFeatureEvidence(imported.losses, {
     evidence: imported.evidence
@@ -77,6 +89,13 @@ 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,
+    conversionArtifacts: conversionArtifacts.summary.routes,
+    conversionArtifactHistories: conversionArtifacts.summary.histories,
+    conversionArtifactPatchBundles: conversionArtifacts.summary.patchBundles,
+    conversionArtifactsDurationMs,
     featureEvidencePolicyMatches,
     featureEvidenceDurationMs,
     nativeProjections: nativeProjections.length,

package/bench/smoke.mjs

@@ -57,6 +57,13 @@ 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)),
+  conversionArtifacts: transformMetrics.conversionArtifacts,
+  conversionArtifactHistories: transformMetrics.conversionArtifactHistories,
+  conversionArtifactPatchBundles: transformMetrics.conversionArtifactPatchBundles,
+  conversionArtifactsDurationMs: Number(transformMetrics.conversionArtifactsDurationMs.toFixed(2)),
   featureEvidencePolicyMatches: transformMetrics.featureEvidencePolicyMatches,
   featureEvidenceDurationMs: Number(transformMetrics.featureEvidenceDurationMs.toFixed(2)),
   nativeProjections: transformMetrics.nativeProjections,

package/dist/declarations/runtime.d.ts

@@ -37,6 +37,8 @@ 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 { CreateUniversalConversionArtifactsInput, CreateUniversalConversionArtifactsOptions, UniversalConversionArtifactQuery, UniversalConversionArtifacts, UniversalConversionRouteArtifact } from './universal-conversion-artifacts.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 +89,16 @@ 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 createUniversalConversionArtifacts(input?: CreateUniversalConversionArtifactsInput, options?: CreateUniversalConversionArtifactsOptions): UniversalConversionArtifacts;
+export declare function createUniversalConversionPlan(options?: UniversalConversionPlanOptions): UniversalConversionPlan;
+export declare function queryUniversalConversionArtifacts(
+  records: UniversalConversionArtifacts | UniversalConversionRouteArtifact | readonly (UniversalConversionArtifacts | UniversalConversionRouteArtifact)[],
+  query?: UniversalConversionArtifactQuery
+): readonly UniversalConversionRouteArtifact[];
+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-artifacts.d.ts

@@ -0,0 +1,148 @@
+import type {
+  FrontierSourceLanguage,
+  SemanticMergeReadiness
+} from '@shapeshift-labs/frontier-lang-kernel';
+import type { FrontierCompileTarget } from './compile.js';
+import type { SemanticHistoryRecord } from './semantic-history.js';
+import type { SemanticPatchBundleRecord } from './semantic-patch-bundle.js';
+import type {
+  UniversalConversionAdmissionAction,
+  UniversalConversionPlan,
+  UniversalConversionPlanOptions,
+  UniversalConversionPriority,
+  UniversalConversionRoute,
+  UniversalConversionRouteAction,
+  UniversalConversionRouteMode,
+  UniversalConversionMergeScore
+} from './universal-conversion-plan.js';
+
+export type UniversalConversionArtifactAdmissionStatus = 'queued' | 'needs-review' | 'blocked' | string;
+export type UniversalConversionArtifactMaterializationStatus = 'materialized' | 'planned-only' | 'missing' | 'failed' | string;
+
+export interface UniversalConversionArtifactMaterialization {
+  readonly status: UniversalConversionArtifactMaterializationStatus;
+  readonly plannedHistoryIds: readonly string[];
+  readonly materializedHistoryIds: readonly string[];
+  readonly patchBundleIds: readonly string[];
+  readonly sourceMapLinkIds: readonly string[];
+  readonly evidenceIds: readonly string[];
+  readonly proofIds: readonly string[];
+  readonly autoMergeClaim: false;
+  readonly semanticEquivalenceClaim: false;
+}
+
+export interface UniversalConversionRouteArtifact {
+  readonly kind: 'frontier.lang.universalConversionRouteArtifact';
+  readonly version: 1;
+  readonly schema: 'frontier.lang.universalConversionRouteArtifact.v1';
+  readonly routeId: string;
+  readonly planId?: string;
+  readonly sourceLanguage?: FrontierSourceLanguage | string;
+  readonly target?: FrontierCompileTarget | string;
+  readonly mode: UniversalConversionRouteMode;
+  readonly routeAction: UniversalConversionRouteAction;
+  readonly priority: UniversalConversionPriority;
+  readonly readiness: SemanticMergeReadiness | string;
+  readonly admissionAction: UniversalConversionAdmissionAction;
+  readonly admissionStatus: UniversalConversionArtifactAdmissionStatus;
+  readonly reviewRequired: true;
+  readonly history: SemanticHistoryRecord;
+  readonly patchBundle: SemanticPatchBundleRecord;
+  readonly materialization: UniversalConversionArtifactMaterialization;
+  readonly mergeScore?: UniversalConversionMergeScore;
+  readonly autoMergeClaim: false;
+  readonly semanticEquivalenceClaim: false;
+  readonly metadata: Record<string, unknown>;
+}
+
+export interface UniversalConversionArtifactIndex {
+  readonly routeIds: readonly string[];
+  readonly historyIds: readonly string[];
+  readonly patchBundleIds: readonly string[];
+  readonly languages: readonly string[];
+  readonly targets: readonly string[];
+  readonly modes: readonly string[];
+  readonly readinesses: readonly string[];
+  readonly admissionStatuses: readonly string[];
+  readonly sourcePaths: readonly string[];
+  readonly sourceHashes: readonly string[];
+  readonly ownershipKeys: readonly string[];
+  readonly conflictKeys: readonly string[];
+  readonly evidenceIds: readonly string[];
+  readonly proofIds: readonly string[];
+}
+
+export interface UniversalConversionArtifacts {
+  readonly kind: 'frontier.lang.universalConversionArtifacts';
+  readonly version: 1;
+  readonly schema: 'frontier.lang.universalConversionArtifacts.v1';
+  readonly id: string;
+  readonly planId?: string;
+  readonly generatedAt: number | string;
+  readonly routeArtifacts: readonly UniversalConversionRouteArtifact[];
+  readonly historyRecords: readonly SemanticHistoryRecord[];
+  readonly patchBundleRecords: readonly SemanticPatchBundleRecord[];
+  readonly index: UniversalConversionArtifactIndex;
+  readonly summary: {
+    readonly routes: number;
+    readonly histories: number;
+    readonly patchBundles: number;
+    readonly reviewRequired: number;
+    readonly blocked: number;
+    readonly autoMergeClaims: 0;
+    readonly semanticEquivalenceClaims: 0;
+  };
+  readonly metadata: {
+    readonly autoMergeClaim: false;
+    readonly semanticEquivalenceClaim: false;
+    readonly note: string;
+  } & Record<string, unknown>;
+}
+
+export interface CreateUniversalConversionArtifactsOptions {
+  readonly id?: string;
+  readonly planId?: string;
+  readonly generatedAt?: number | string;
+  readonly routeId?: string;
+  readonly sourceLanguage?: FrontierSourceLanguage | string;
+  readonly target?: FrontierCompileTarget | string;
+  readonly mode?: UniversalConversionRouteMode;
+  readonly readiness?: SemanticMergeReadiness | string;
+  readonly admissionAction?: UniversalConversionAdmissionAction;
+  readonly maxRoutes?: number;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export type CreateUniversalConversionArtifactsInput =
+  | UniversalConversionPlan
+  | UniversalConversionRoute
+  | UniversalConversionPlanOptions;
+
+export interface UniversalConversionArtifactQuery {
+  readonly routeId?: string | readonly string[];
+  readonly historyId?: string | readonly string[];
+  readonly patchBundleId?: string | readonly string[];
+  readonly sourceLanguage?: FrontierSourceLanguage | string | readonly string[];
+  readonly target?: FrontierCompileTarget | string | readonly string[];
+  readonly mode?: UniversalConversionRouteMode | readonly string[];
+  readonly readiness?: SemanticMergeReadiness | string | readonly string[];
+  readonly admissionAction?: UniversalConversionAdmissionAction | readonly string[];
+  readonly admissionStatus?: UniversalConversionArtifactAdmissionStatus | readonly string[];
+  readonly priority?: UniversalConversionPriority | readonly string[];
+  readonly routeAction?: UniversalConversionRouteAction | readonly string[];
+  readonly sourcePath?: string | readonly string[];
+  readonly sourceHash?: string | readonly string[];
+  readonly ownershipKey?: string | readonly string[];
+  readonly conflictKey?: string | readonly string[];
+  readonly evidenceId?: string | readonly string[];
+  readonly proofId?: string | readonly string[];
+}
+
+export declare function createUniversalConversionArtifacts(
+  input?: CreateUniversalConversionArtifactsInput,
+  options?: CreateUniversalConversionArtifactsOptions
+): UniversalConversionArtifacts;
+export declare function queryUniversalConversionArtifacts(
+  records: UniversalConversionArtifacts | UniversalConversionRouteArtifact | readonly (UniversalConversionArtifacts | UniversalConversionRouteArtifact)[],
+  query?: UniversalConversionArtifactQuery
+): readonly UniversalConversionRouteArtifact[];

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,8 @@ 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-artifacts.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,8 @@ 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 { createUniversalConversionArtifacts, queryUniversalConversionArtifacts } from './universal-conversion-artifacts.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 +64,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-artifact-query.js

@@ -0,0 +1,60 @@
+import { uniqueStrings } from './native-import-utils.js';
+
+export function queryUniversalConversionArtifacts(records, query = {}) {
+  return artifactRecords(records)
+    .filter((record) => matchesArtifact(record, query))
+    .sort((left, right) => Number(right.mergeScore?.sortKey ?? 0) - Number(left.mergeScore?.sortKey ?? 0)
+      || String(left.routeId).localeCompare(String(right.routeId)));
+}
+
+export function artifactIndex(routeArtifacts) {
+  return {
+    routeIds: uniqueStrings(routeArtifacts.map((artifact) => artifact.routeId)),
+    historyIds: uniqueStrings(routeArtifacts.map((artifact) => artifact.history.id)),
+    patchBundleIds: uniqueStrings(routeArtifacts.map((artifact) => artifact.patchBundle.id)),
+    languages: uniqueStrings(routeArtifacts.map((artifact) => artifact.sourceLanguage)),
+    targets: uniqueStrings(routeArtifacts.map((artifact) => artifact.target)),
+    modes: uniqueStrings(routeArtifacts.map((artifact) => artifact.mode)),
+    readinesses: uniqueStrings(routeArtifacts.map((artifact) => artifact.readiness)),
+    admissionStatuses: uniqueStrings(routeArtifacts.map((artifact) => artifact.admissionStatus)),
+    sourcePaths: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.history.index.sourcePaths)),
+    sourceHashes: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.history.index.sourceHashes)),
+    ownershipKeys: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.history.index.ownershipKeys)),
+    conflictKeys: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.history.index.conflictKeys)),
+    evidenceIds: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.history.evidenceIds)),
+    proofIds: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.history.proofIds))
+  };
+}
+
+function artifactRecords(records) {
+  if (Array.isArray(records)) return records.flatMap(artifactRecords);
+  if (records?.kind === 'frontier.lang.universalConversionArtifacts') return records.routeArtifacts ?? [];
+  if (records?.kind === 'frontier.lang.universalConversionRouteArtifact') return [records];
+  return [];
+}
+
+function matchesArtifact(record, query) {
+  return match(query.routeId, [record.routeId])
+    && match(query.historyId, [record.history.id])
+    && match(query.patchBundleId, [record.patchBundle.id])
+    && match(query.sourceLanguage, [record.sourceLanguage])
+    && match(query.target, [record.target])
+    && match(query.mode, [record.mode])
+    && match(query.routeAction, [record.routeAction])
+    && match(query.priority, [record.priority])
+    && match(query.readiness, [record.readiness])
+    && match(query.admissionStatus, [record.admissionStatus])
+    && match(query.sourcePath, record.history.index.sourcePaths)
+    && match(query.sourceHash, record.history.index.sourceHashes)
+    && match(query.ownershipKey, record.history.index.ownershipKeys)
+    && match(query.conflictKey, record.history.index.conflictKeys)
+    && match(query.evidenceId, record.history.evidenceIds)
+    && match(query.proofId, record.history.proofIds);
+}
+
+function match(filter, values) {
+  const filters = Array.isArray(filter) ? filter : filter === undefined ? [] : [filter];
+  if (filters.length === 0) return true;
+  const valueSet = new Set((values ?? []).map(String));
+  return filters.some((item) => valueSet.has(String(item)));
+}