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

package/README.md

@@ -129,6 +129,7 @@ import {
   createNativeParserAstFormatMatrix,
   createProjectionTargetLossMatrix,
   createUniversalCapabilityMatrix,
+  createUniversalConversionArtifacts,
   createUniversalConversionPlan,
   queryUniversalConversionPlan,
   importNativeSource
@@ -178,6 +179,10 @@ const pythonToRust = queryUniversalConversionPlan(conversionPlan, {
 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:
@@ -192,6 +197,8 @@ The projection target matrix separates five runtime/API classes:
 
 `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,7 @@ import {
   createSemanticImportSidecar,
   createSemanticSlice,
   createSemanticSliceAdmissionRecord,
+  createUniversalConversionArtifacts,
   createUniversalConversionPlan,
   projectNativeImportToSource,
   summarizeNativeImportFeatureEvidence,
@@ -54,6 +55,9 @@ export function measureNativeTransformations(nativeImportResults) {
     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, {
@@ -88,6 +92,10 @@ export function measureNativeTransformations(nativeImportResults) {
     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

@@ -60,6 +60,10 @@ console.log(JSON.stringify({
   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,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 { 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';
@@ -88,7 +89,12 @@ 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

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/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-artifacts.js';
 export * from './declarations/universal-conversion-plan.js';
 export * from './declarations/universal-dialects.js';
 export * from './declarations/language-adapter-package-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 { 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';

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)));
+}

package/dist/universal-conversion-artifacts.js

@@ -0,0 +1,287 @@
+import { idFragment, uniqueStrings } from './native-import-utils.js';
+import { createUniversalConversionPlan } from './universal-conversion-plan.js';
+import { artifactIndex } from './universal-conversion-artifact-query.js';
+import { createSemanticHistoryRecord } from './internal/index-impl/semanticHistoryRecords.js';
+import { createSemanticPatchBundleRecord } from './internal/index-impl/semanticPatchBundleRecords.js';
+
+export { queryUniversalConversionArtifacts } from './universal-conversion-artifact-query.js';
+
+export function createUniversalConversionArtifacts(input = {}, options = {}) {
+  const generatedAt = options.generatedAt ?? input.generatedAt ?? Date.now();
+  const plan = input?.kind === 'frontier.lang.universalConversionPlan'
+    ? input
+    : input?.target && input?.sourceLanguage
+      ? undefined
+      : createUniversalConversionPlan(input);
+  const routes = selectRoutes(plan?.routes ?? (input?.target && input?.sourceLanguage ? [input] : []), options);
+  const routeArtifacts = routes.map((route) => createRouteArtifact(route, {
+    generatedAt,
+    planId: options.planId ?? plan?.id ?? route.mergeRefs?.planId,
+    metadata: options.metadata
+  }));
+  const historyRecords = routeArtifacts.map((artifact) => artifact.history);
+  const patchBundleRecords = routeArtifacts.map((artifact) => artifact.patchBundle);
+  const index = artifactIndex(routeArtifacts);
+  return {
+    kind: 'frontier.lang.universalConversionArtifacts',
+    version: 1,
+    schema: 'frontier.lang.universalConversionArtifacts.v1',
+    id: options.id ?? `universal_conversion_artifacts_${idFragment(index.routeIds.join('_') || plan?.id || 'routes')}`,
+    planId: plan?.id ?? options.planId,
+    generatedAt,
+    routeArtifacts,
+    historyRecords,
+    patchBundleRecords,
+    index,
+    summary: {
+      routes: routeArtifacts.length,
+      histories: historyRecords.length,
+      patchBundles: patchBundleRecords.length,
+      reviewRequired: routeArtifacts.filter((artifact) => artifact.reviewRequired).length,
+      blocked: routeArtifacts.filter((artifact) => artifact.admissionStatus === 'blocked').length,
+      autoMergeClaims: 0,
+      semanticEquivalenceClaims: 0
+    },
+    metadata: {
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      note: 'Materialized conversion artifacts are merge-review records. They preserve provenance and admission state but do not prove target semantic equivalence.',
+      ...options.metadata
+    }
+  };
+}
+
+function createRouteArtifact(route, options) {
+  const refs = route.mergeRefs ?? {};
+  const planId = options.planId ?? refs.planId;
+  const sources = normalizeSources(refs.sources, route);
+  const regions = routeRegions(route, refs, sources);
+  const sourceMapLinks = routeSourceMapLinks(route, refs, sources, regions);
+  const admissionStatus = routeAdmissionStatus(route);
+  const reasonCodes = routeReasonCodes(route);
+  const historyId = refs.historyIds?.[0] ?? `history_${route.id}`;
+  const patchBundleId = refs.patchBundleIds?.[0] ?? `semantic_patch_bundle_${route.id}`;
+  const history = createSemanticHistoryRecord({
+    id: historyId,
+    createdAt: options.generatedAt,
+    language: route.sourceLanguage,
+    sourcePath: sources[0]?.sourcePath,
+    sources,
+    ownershipRegions: regions,
+    semanticCandidates: routeSemanticCandidates(route, refs),
+    evidenceIds: refs.evidenceIds,
+    proofIds: refs.proofIds,
+    replayLinks: refs.replayLinks,
+    admission: {
+      status: admissionStatus,
+      readiness: route.readiness,
+      reasonCodes,
+      evidenceIds: refs.evidenceIds,
+      metadata: routeAdmissionMetadata(route, planId)
+    },
+    metadata: routeRecordMetadata(route, planId, options.metadata)
+  }, { id: historyId, createdAt: options.generatedAt });
+  const patchBundle = createSemanticPatchBundleRecord({
+    id: patchBundleId,
+    language: route.sourceLanguage,
+    sourcePath: sources[0]?.sourcePath,
+    sources,
+    changedRegions: regions,
+    sourceMapLinks,
+    evidenceIds: refs.evidenceIds,
+    proofIds: refs.proofIds,
+    historyIds: [history.id],
+    readiness: route.readiness,
+    conflictKeys: refs.conflictKeys,
+    admission: {
+      status: admissionStatus,
+      readiness: route.readiness,
+      reviewRequired: true,
+      reasonCodes,
+      conflictKeys: refs.conflictKeys,
+      evidenceIds: refs.evidenceIds,
+      metadata: routeAdmissionMetadata(route, planId)
+    },
+    metadata: routeRecordMetadata(route, planId, options.metadata)
+  }, { id: patchBundleId, createdAt: options.generatedAt });
+  const materialization = {
+    status: 'materialized',
+    plannedHistoryIds: refs.historyIds ?? [],
+    materializedHistoryIds: [history.id],
+    patchBundleIds: [patchBundle.id],
+    sourceMapLinkIds: patchBundle.index.sourceMapLinkIds,
+    evidenceIds: history.evidenceIds,
+    proofIds: history.proofIds,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false
+  };
+  return {
+    kind: 'frontier.lang.universalConversionRouteArtifact',
+    version: 1,
+    schema: 'frontier.lang.universalConversionRouteArtifact.v1',
+    routeId: route.id,
+    planId,
+    sourceLanguage: route.sourceLanguage,
+    target: route.target,
+    mode: route.mode,
+    routeAction: route.routeAction,
+    priority: route.priority,
+    readiness: route.readiness,
+    admissionAction: route.admissionAction,
+    admissionStatus,
+    reviewRequired: true,
+    history,
+    patchBundle,
+    materialization,
+    mergeScore: route.mergeScore,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    metadata: { ...routeRecordMetadata(route, planId, options.metadata), materialization }
+  };
+}
+
+function selectRoutes(routes, options) {
+  const selected = (routes ?? []).filter((route) => {
+    if (options.routeId && route.id !== options.routeId) return false;
+    if (options.sourceLanguage && route.sourceLanguage !== options.sourceLanguage) return false;
+    if (options.target && route.target !== options.target) return false;
+    if (options.mode && route.mode !== options.mode) return false;
+    if (options.readiness && route.readiness !== options.readiness) return false;
+    if (options.admissionAction && route.admissionAction !== options.admissionAction) return false;
+    return true;
+  });
+  return Number.isFinite(options.maxRoutes) ? selected.slice(0, Math.max(0, Number(options.maxRoutes))) : selected;
+}
+
+function normalizeSources(sources, route) {
+  return (sources?.length ? sources : [{}]).map((source, index) => ({
+    id: source.sourceId ?? source.id ?? `route_source_${idFragment(route.id)}_${index + 1}`,
+    importId: source.importId,
+    language: route.sourceLanguage,
+    sourcePath: source.sourcePath,
+    sourceHash: source.sourceHash,
+    baseHash: source.baseHash,
+    targetHash: source.targetHash,
+    metadata: {
+      routeId: route.id,
+      target: route.target,
+      mode: route.mode
+    }
+  }));
+}
+
+function routeRegions(route, refs, sources) {
+  const source = sources[0] ?? {};
+  const keys = refs.semanticOwnershipKeys?.length
+    ? refs.semanticOwnershipKeys
+    : [`conversion#${route.sourceLanguage ?? 'source'}#${route.target ?? 'target'}#${route.id}`];
+  return uniqueStrings(keys).map((key, index) => ({
+    id: `route_region_${idFragment(route.id)}_${index + 1}`,
+    key,
+    conflictKey: refs.conflictKeys?.[index] ?? refs.conflictKeys?.[0] ?? key,
+    changeKind: 'conversion-route',
+    regionKind: route.mode,
+    granularity: 'conversion-route',
+    precision: route.mode === 'preserve-source' ? 'exact-source' : 'semantic-route',
+    language: route.sourceLanguage,
+    sourcePath: source.sourcePath,
+    sourceHash: source.sourceHash,
+    sourceMapIds: refs.sourceMapIds,
+    sourceMapMappingIds: refs.sourceMapMappingIds,
+    admission: {
+      readiness: route.readiness,
+      action: route.admissionAction,
+      conflictKeys: refs.conflictKeys
+    },
+    metadata: {
+      routeId: route.id,
+      target: route.target,
+      mode: route.mode,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  }));
+}
+
+function routeSourceMapLinks(route, refs, sources, regions) {
+  const source = sources[0] ?? {};
+  const max = Math.max(refs.sourceMapIds?.length ?? 0, refs.sourceMapMappingIds?.length ?? 0);
+  return Array.from({ length: max }, (_, index) => ({
+    id: refs.sourceMapLinkIds?.[index] ?? `route_source_map_link_${idFragment(route.id)}_${index + 1}`,
+    sourceMapId: refs.sourceMapIds?.[index] ?? refs.sourceMapIds?.[0],
+    sourceMapMappingId: refs.sourceMapMappingIds?.[index],
+    sourcePath: source.sourcePath,
+    sourceHash: source.sourceHash,
+    targetPath: `${route.target}:${source.sourcePath ?? route.id}`,
+    precision: route.mode === 'preserve-source' ? 'exact-source' : 'semantic-route',
+    regionKey: regions[index % Math.max(1, regions.length)]?.key,
+    regionKind: route.mode
+  }));
+}
+
+function routeSemanticCandidates(route, refs) {
+  const ids = refs.mergeCandidateIds?.length ? refs.mergeCandidateIds : [`candidate_${route.id}`];
+  return uniqueStrings(ids).map((id) => ({
+    id,
+    sourcePath: refs.sources?.[0]?.sourcePath,
+    baseHash: refs.sources?.[0]?.baseHash,
+    targetHash: refs.sources?.[0]?.targetHash,
+    readiness: route.readiness,
+    conflictKeys: refs.conflictKeys ?? [],
+    ownershipKeys: refs.semanticOwnershipKeys ?? [],
+    evidenceIds: refs.evidenceIds ?? [],
+    proofIds: refs.proofIds ?? [],
+    replayIds: (refs.replayLinks ?? []).map((link) => link?.id).filter(Boolean),
+    metadata: {
+      routeId: route.id,
+      target: route.target,
+      mode: route.mode,
+      risk: route.mergeScore?.risk
+    }
+  }));
+}
+
+function routeAdmissionStatus(route) {
+  if (route.readiness === 'blocked' || route.admissionAction === 'reject') return 'blocked';
+  if (route.readiness === 'ready' && route.missingEvidence?.length === 0) return 'queued';
+  return 'needs-review';
+}
+
+function routeReasonCodes(route) {
+  return uniqueStrings([
+    `mode:${route.mode}`,
+    `action:${route.routeAction}`,
+    ...(route.missingEvidence ?? []).map((item) => `missing:${item}`),
+    ...(route.blockers ?? []).map((item) => `blocker:${item}`),
+    ...(route.review ?? []).map((item) => `review:${item}`)
+  ]);
+}
+
+function routeAdmissionMetadata(route, planId) {
+  return {
+    planId,
+    routeId: route.id,
+    routeAction: route.routeAction,
+    admissionAction: route.admissionAction,
+    priority: route.priority,
+    mergeScore: route.mergeScore,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false
+  };
+}
+
+function routeRecordMetadata(route, planId, metadata) {
+  return {
+    planId,
+    routeId: route.id,
+    target: route.target,
+    mode: route.mode,
+    routeAction: route.routeAction,
+    missingEvidence: route.missingEvidence ?? [],
+    blockers: route.blockers ?? [],
+    review: route.review ?? [],
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    ...metadata
+  };
+}

package/package.json

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