@shapeshift-labs/frontier-lang-compiler 0.2.41 → 0.2.42

package/dist/projection-readiness-helpers.js

@@ -0,0 +1,166 @@
+import { maxSemanticMergeReadiness, normalizeNativeLanguageId, uniqueStrings } from './native-import-utils.js';
+import { NativeParserFeatureCategories } from './coverage-matrix-profiles.js';
+
+export const ProjectionReadinessStatuses = Object.freeze(['preserve', 'lower', 'shim', 'lossy', 'blocked']);
+
+const statusRank = Object.freeze({ preserve: 0, lower: 1, shim: 2, lossy: 3, blocked: 4 });
+const statusReadiness = Object.freeze({
+  preserve: 'ready',
+  lower: 'ready',
+  shim: 'needs-review',
+  lossy: 'needs-review',
+  blocked: 'blocked'
+});
+const lossKindFeatureCategories = Object.freeze({
+  declarationOnlyCoverage: ['semantic', 'type', 'controlFlow'],
+  opaqueNative: ['syntax', 'semantic', 'type', 'controlFlow'],
+  sourceMapApproximation: ['sourcePreservation'],
+  sourcePreservation: ['sourcePreservation'],
+  targetProjectionLoss: ['semantic', 'type', 'controlFlow', 'sourcePreservation'],
+  dynamicRuntime: ['semantic', 'type', 'controlFlow'],
+  dynamicDispatch: ['semantic', 'controlFlow'],
+  reflection: ['semantic', 'type'],
+  macroExpansion: ['macroMetaprogramming'],
+  macroHygiene: ['macroMetaprogramming'],
+  preprocessor: ['macroMetaprogramming'],
+  conditionalCompilation: ['macroMetaprogramming'],
+  metaprogramming: ['macroMetaprogramming'],
+  generatedCode: ['macroMetaprogramming', 'sourcePreservation'],
+  overloadResolution: ['type'],
+  typeInference: ['type'],
+  unsupportedSyntax: ['syntax'],
+  unsupportedSemantic: ['semantic']
+});
+
+export function projectionReadinessStatusForFeature(input) {
+  const lossClass = input.target.lossClass;
+  if (!input.target.supported || lossClass === 'missingAdapter' || input.target.readiness === 'blocked') return 'blocked';
+  if (lossClass === 'exactSourceProjection') return 'preserve';
+  if (lossClass === 'targetAdapterProjection') return input.lossKinds.length ? 'lossy' : input.target.readiness === 'ready' ? 'lower' : 'shim';
+  if (lossClass === 'nativeSourceStubs') return input.category === 'sourcePreservation' ? 'lossy' : 'shim';
+  if (lossClass === 'unsupportedTargetFeatures') {
+    if (input.lossKinds.length) return 'lossy';
+    return input.sameSourceTarget && input.category === 'sourcePreservation' ? 'preserve' : 'shim';
+  }
+  if (input.lossKinds.length) return 'lossy';
+  return input.sameSourceTarget ? 'preserve' : 'shim';
+}
+
+export function projectionReadinessSemanticReadiness(status, targetReadiness) {
+  if (status === 'blocked' || targetReadiness === 'blocked') return 'blocked';
+  return statusReadiness[status] ?? 'needs-review';
+}
+
+export function projectionReadinessFeatureReasons(input) {
+  if (input.status === 'blocked') {
+    return [input.target.reason ?? `No projection support is available from ${input.language.language} to ${input.target.target}.`];
+  }
+  if (input.status === 'lossy') {
+    return [`${input.language.language} -> ${input.target.target} has ${input.category} projection losses: ${input.lossKinds.join(', ')}.`];
+  }
+  if (input.status === 'preserve') {
+    return [`${input.language.language} -> ${input.target.target} preserves ${input.category} by keeping exact native source for the source-language target.`];
+  }
+  if (input.status === 'lower') {
+    return [`${input.language.language} -> ${input.target.target} lowers ${input.category} through ${input.target.adapter ?? 'declared target projection'} without disclosed category losses.`];
+  }
+  return [`${input.language.language} -> ${input.target.target} emits ${input.category} as a shim or declaration-level projection that requires review.`];
+}
+
+export function projectionReadinessFeatureNotes(status, target) {
+  return uniqueStrings([
+    ...(target.notes ?? []),
+    ...(status === 'shim' ? ['Shimmed projection is useful for planning and API compatibility, but it is not exact semantic lowering.'] : []),
+    ...(status === 'lossy' ? ['Lossy projection should stay review-required until host evidence handles the listed feature losses.'] : [])
+  ]);
+}
+
+export function projectionReadinessLanguageSummary(targets) {
+  const summary = { targetEntries: targets.length, featureCells: 0, byStatus: {}, byFeatureStatus: {} };
+  for (const target of targets) {
+    summary.byStatus[target.status] = (summary.byStatus[target.status] ?? 0) + 1;
+    for (const feature of target.features ?? []) {
+      summary.featureCells += 1;
+      summary.byFeatureStatus[feature.category] ??= {};
+      summary.byFeatureStatus[feature.category][feature.status] = (summary.byFeatureStatus[feature.category][feature.status] ?? 0) + 1;
+    }
+  }
+  return addStatusCounts(summary);
+}
+
+export function projectionReadinessMatrixSummary(languages) {
+  const summary = { languages: languages.length, targetEntries: 0, featureCells: 0, byStatus: {}, byFeatureStatus: {} };
+  for (const language of languages) {
+    summary.targetEntries += language.summary.targetEntries;
+    summary.featureCells += language.summary.featureCells;
+    for (const [status, count] of Object.entries(language.summary.byStatus)) {
+      summary.byStatus[status] = (summary.byStatus[status] ?? 0) + count;
+    }
+    for (const [category, statuses] of Object.entries(language.summary.byFeatureStatus)) {
+      summary.byFeatureStatus[category] ??= {};
+      for (const [status, count] of Object.entries(statuses)) {
+        summary.byFeatureStatus[category][status] = (summary.byFeatureStatus[category][status] ?? 0) + count;
+      }
+    }
+  }
+  return addStatusCounts(summary);
+}
+
+export function maxProjectionReadinessStatus(left, right) {
+  const leftRank = statusRank[left] ?? statusRank.lossy;
+  const rightRank = statusRank[right] ?? statusRank.lossy;
+  return leftRank >= rightRank ? left : right;
+}
+
+export function projectionLossKindsForFeatureCategory(lossKinds, category) {
+  return uniqueStrings((lossKinds ?? []).filter((lossKind) => (lossKindFeatureCategories[lossKind] ?? []).includes(category)));
+}
+
+export function normalizeProjectionReadinessFeatureCategories(value) {
+  const requested = value === undefined || value === null ? NativeParserFeatureCategories : Array.isArray(value) ? value : [value];
+  const normalized = uniqueStrings(requested.map(normalizeProjectionReadinessFeatureCategory).filter(Boolean));
+  return normalized.length ? normalized : [...NativeParserFeatureCategories];
+}
+
+export function normalizeProjectionReadinessFeatureCategory(value) {
+  if (!value) return undefined;
+  const compact = String(value).trim().toLowerCase().replace(/[-_\s]+/g, '');
+  const aliases = {
+    ast: 'syntax',
+    syntax: 'syntax',
+    semantic: 'semantic',
+    semantics: 'semantic',
+    type: 'type',
+    types: 'type',
+    typechecking: 'type',
+    controlflow: 'controlFlow',
+    cfg: 'controlFlow',
+    macro: 'macroMetaprogramming',
+    macros: 'macroMetaprogramming',
+    metaprogramming: 'macroMetaprogramming',
+    macrometaprogramming: 'macroMetaprogramming',
+    source: 'sourcePreservation',
+    sourcepreservation: 'sourcePreservation',
+    sourcemap: 'sourcePreservation',
+    roundtrip: 'sourcePreservation'
+  };
+  const category = aliases[compact] ?? String(value).trim();
+  return NativeParserFeatureCategories.includes(category) ? category : undefined;
+}
+
+export function projectionLanguageIds(entry) {
+  return uniqueStrings([entry?.language, ...(entry?.aliases ?? [])].map(normalizeNativeLanguageId).filter(Boolean));
+}
+
+export { maxSemanticMergeReadiness };
+
+function addStatusCounts(summary) {
+  return {
+    ...summary,
+    preserveTargets: summary.byStatus.preserve ?? 0,
+    lowerTargets: summary.byStatus.lower ?? 0,
+    shimTargets: summary.byStatus.shim ?? 0,
+    lossyTargets: summary.byStatus.lossy ?? 0,
+    blockedTargets: summary.byStatus.blocked ?? 0
+  };
+}

package/dist/projection-readiness-matrix.js

@@ -0,0 +1,122 @@
+import { nativeLanguageCompileTarget, normalizeProjectionMatrixTargets } from './coverage-matrix-profiles.js';
+import { createProjectionTargetLossMatrix } from './projection-target-loss-matrix.js';
+import {
+  maxProjectionReadinessStatus,
+  maxSemanticMergeReadiness,
+  normalizeProjectionReadinessFeatureCategories,
+  normalizeProjectionReadinessFeatureCategory,
+  projectionLanguageIds,
+  projectionLossKindsForFeatureCategory,
+  ProjectionReadinessStatuses,
+  projectionReadinessFeatureNotes,
+  projectionReadinessFeatureReasons,
+  projectionReadinessLanguageSummary,
+  projectionReadinessMatrixSummary,
+  projectionReadinessSemanticReadiness,
+  projectionReadinessStatusForFeature
+} from './projection-readiness-helpers.js';
+
+export { ProjectionReadinessStatuses };
+
+export function createProjectionReadinessMatrix(input = {}, context = {}) {
+  const featureCategories = normalizeProjectionReadinessFeatureCategories(input.featureCategories);
+  const projectionTargets = input.projectionTargetMatrix?.kind === 'frontier.lang.projectionTargetLossMatrix'
+    ? input.projectionTargetMatrix
+    : createProjectionTargetLossMatrix(input, context);
+  const languages = (projectionTargets.languages ?? []).map((language) => projectionReadinessLanguageRow(language, featureCategories));
+  return {
+    kind: 'frontier.lang.projectionReadinessMatrix',
+    version: 1,
+    generatedAt: input.generatedAt ?? projectionTargets.generatedAt ?? Date.now(),
+    languages,
+    summary: projectionReadinessMatrixSummary(languages),
+    matrices: { projectionTargets },
+    metadata: {
+      statuses: [...ProjectionReadinessStatuses],
+      featureCategories,
+      compileTargets: projectionTargets.metadata?.compileTargets ?? [],
+      note: 'Projection readiness reports preserve/lower/shim/lossy/blocked status by source language, target language, and feature category. It is coordinator evidence, not a proof of semantic equivalence.'
+    }
+  };
+}
+
+export function queryProjectionReadinessMatrix(matrixOrInput = {}, query = {}, context = {}) {
+  const matrix = matrixOrInput?.kind === 'frontier.lang.projectionReadinessMatrix'
+    ? matrixOrInput
+    : createProjectionReadinessMatrix(matrixOrInput, context);
+  const sourceLanguage = projectionLanguageIds({ language: query.sourceLanguage ?? query.language })[0];
+  const target = normalizeProjectionMatrixTargets(query.target)[0];
+  const featureCategory = normalizeProjectionReadinessFeatureCategory(query.featureCategory ?? query.category);
+  const language = (matrix.languages ?? []).find((entry) => !sourceLanguage || projectionLanguageIds(entry).includes(sourceLanguage));
+  const cell = (language?.targets ?? []).find((entry) => !target || entry.target === target);
+  const feature = featureCategory ? (cell?.features ?? []).find((entry) => entry.category === featureCategory) : undefined;
+  const status = feature?.status ?? cell?.status ?? 'blocked';
+  const readiness = feature?.readiness ?? cell?.readiness ?? 'blocked';
+  return {
+    kind: 'frontier.lang.projectionReadinessQuery',
+    version: 1,
+    found: Boolean(language && cell && (!featureCategory || feature)),
+    sourceLanguage: language?.language ?? sourceLanguage,
+    target: cell?.target ?? target,
+    featureCategory: feature?.category ?? featureCategory,
+    status,
+    readiness,
+    cell,
+    feature,
+    reasons: feature?.reasons ?? cell?.reasons ?? [`No projection readiness cell matched source=${query.sourceLanguage ?? query.language ?? '*'} target=${query.target ?? '*'}.`]
+  };
+}
+
+function projectionReadinessLanguageRow(language, featureCategories) {
+  const targets = (language.targets ?? []).map((target) => projectionReadinessTargetCell(language, target, featureCategories));
+  return {
+    language: language.language,
+    aliases: language.aliases ?? [],
+    extensions: language.extensions ?? [],
+    targets,
+    summary: projectionReadinessLanguageSummary(targets)
+  };
+}
+
+function projectionReadinessTargetCell(language, target, featureCategories) {
+  const features = featureCategories.map((category) => projectionReadinessFeatureCell(language, target, category));
+  const status = features.reduce((current, feature) => maxProjectionReadinessStatus(current, feature.status), 'preserve');
+  const readiness = features.reduce((current, feature) => maxSemanticMergeReadiness(current, feature.readiness), 'ready');
+  return {
+    sourceLanguage: language.language,
+    target: target.target,
+    status,
+    readiness,
+    lossClass: target.lossClass,
+    supported: target.supported,
+    adapter: target.adapter,
+    adapterKind: target.adapterKind,
+    features,
+    byFeature: Object.fromEntries(features.map((feature) => [feature.category, feature.status])),
+    blockingFeatures: features.filter((feature) => feature.status === 'blocked').map((feature) => feature.category),
+    lossyFeatures: features.filter((feature) => feature.status === 'lossy').map((feature) => feature.category),
+    shimFeatures: features.filter((feature) => feature.status === 'shim').map((feature) => feature.category),
+    lowerFeatures: features.filter((feature) => feature.status === 'lower').map((feature) => feature.category),
+    preserveFeatures: features.filter((feature) => feature.status === 'preserve').map((feature) => feature.category),
+    lossKinds: target.lossKinds ?? [],
+    categories: target.categories ?? [],
+    reasons: [...new Set([target.reason, ...features.flatMap((feature) => feature.reasons)].filter(Boolean))],
+    notes: target.notes ?? []
+  };
+}
+
+function projectionReadinessFeatureCell(language, target, category) {
+  const sourceTarget = nativeLanguageCompileTarget(language.language, language.aliases ?? []);
+  const sameSourceTarget = Boolean(sourceTarget && target.target === sourceTarget);
+  const lossKinds = projectionLossKindsForFeatureCategory(target.lossKinds ?? [], category);
+  const status = projectionReadinessStatusForFeature({ category, lossKinds, sameSourceTarget, target });
+  return {
+    category,
+    status,
+    readiness: projectionReadinessSemanticReadiness(status, target.readiness),
+    lossClass: target.lossClass,
+    lossKinds,
+    reasons: projectionReadinessFeatureReasons({ category, lossKinds, language, sameSourceTarget, status, target }),
+    notes: projectionReadinessFeatureNotes(status, target)
+  };
+}

package/dist/projection-target-loss-matrix.js

@@ -0,0 +1,318 @@
+import {
+  normalizeNativeLanguageId,
+  uniqueStrings
+} from './native-import-utils.js';
+import {
+  NativeImportLanguageProfiles,
+  ProjectionTargetLossClasses,
+  mergeNativeImportProfiles,
+  nativeLanguageCompileTarget,
+  normalizeProjectionMatrixTargets
+} from './coverage-matrix-profiles.js';
+
+export function createProjectionTargetLossMatrix(input = {}, context = {}) {
+  const imports = input.imports ?? [];
+  const adapters = input.adapters ?? [];
+  const targetAdapters = input.targetAdapters ?? [];
+  const profiles = mergeNativeImportProfiles(input.languages ?? NativeImportLanguageProfiles, imports, adapters, targetAdapters, context);
+  const targets = normalizeProjectionMatrixTargets(input.targets ?? context.compileTargets ?? []);
+  const languages = profiles.map((profile) => projectionTargetCoverageForProfile(profile, {
+    imports,
+    adapters,
+    targetAdapters,
+    targets
+  }, context));
+  const summary = projectionTargetLossMatrixSummary(languages);
+  return {
+    kind: 'frontier.lang.projectionTargetLossMatrix',
+    version: 1,
+    generatedAt: input.generatedAt ?? Date.now(),
+    languages,
+    summary,
+    metadata: {
+      compileTargets: targets,
+      lossClasses: [...ProjectionTargetLossClasses],
+      note: 'Projection target coverage separates exact source preservation, declaration stubs, host-owned target adapters, known unsupported target features, and missing native-to-target adapters.'
+    }
+  };
+}
+
+function projectionTargetCoverageForProfile(profile, input, context = {}) {
+  const aliases = new Set([profile.language, ...(profile.aliases ?? [])].map(normalizeNativeLanguageId).filter(Boolean));
+  const matchingImports = (input.imports ?? []).filter((imported) => aliases.has(normalizeNativeLanguageId(imported?.language ?? imported?.nativeAst?.language)));
+  const matchingAdapters = (input.adapters ?? []).filter((adapter) => aliases.has(normalizeNativeLanguageId(adapter?.language)));
+  const matchingTargetAdapters = (input.targetAdapters ?? []).filter((adapter) => aliases.has(normalizeNativeLanguageId(adapter?.sourceLanguage ?? adapter?.language)));
+  const importedLossKinds = uniqueStrings(matchingImports.flatMap((imported) => (imported?.losses ?? []).map((loss) => loss.kind).filter(Boolean)));
+  const knownLossKinds = uniqueStrings([...(profile.knownLossKinds ?? []), ...importedLossKinds]);
+  const parserAdapters = uniqueStrings([
+    ...(profile.parserAdapters ?? []),
+    ...matchingAdapters.map((adapter) => adapter.parser ?? adapter.id).filter(Boolean)
+  ]);
+  const sourceProjection = sourceProjectionCoverageForProfile(profile, matchingImports, knownLossKinds);
+  const targets = (input.targets ?? context.compileTargets ?? []).map((target) => projectionTargetCoverageEntry(profile, target, {
+    matchingImports,
+    matchingAdapters,
+    matchingTargetAdapters,
+    knownLossKinds
+  }, context));
+  return {
+    language: profile.language,
+    aliases: profile.aliases,
+    extensions: profile.extensions,
+    supportsLightweightScan: profile.supportsLightweightScan,
+    parserAdapters,
+    projectionTargets: profile.projectionTargets,
+    knownLossKinds,
+    defaultReadiness: profile.defaultReadiness,
+    notes: profile.notes,
+    sourceProjection,
+    targets,
+    summary: {
+      imports: matchingImports.length,
+      parserAdapters: parserAdapters.length,
+      targetEntries: targets.length,
+      byLossClass: countProjectionLossClasses(targets),
+      exactSourceImports: sourceProjection.exactSource.evidence.importsWithExactSource,
+      stubDeclarationImports: sourceProjection.stubs.evidence.importsWithDeclarations
+    }
+  };
+}
+
+function sourceProjectionCoverageForProfile(profile, imports, knownLossKinds) {
+  const exactSourceImports = imports.filter(hasExactSourceProjectionEvidence).length;
+  const declarationImports = imports.filter(hasNativeProjectionDeclarations).length;
+  return {
+    exactSource: {
+      lossClass: 'exactSourceProjection',
+      mode: 'preserved-source',
+      supported: true,
+      readiness: 'ready',
+      lossKinds: [],
+      categories: [],
+      reason: exactSourceImports
+        ? 'At least one import carries matching source-preservation evidence, so projectNativeImportToSource can emit the original source exactly.'
+        : 'Exact source projection is available when the import carries sourceText or source-preservation evidence whose hash matches the native source hash.',
+      evidence: {
+        imports: imports.length,
+        importsWithExactSource: exactSourceImports
+      },
+      notes: ['Preserved source is the only currently lossless native-source projection mode in this facade.']
+    },
+    stubs: {
+      lossClass: 'nativeSourceStubs',
+      mode: 'native-source-stubs',
+      supported: profile.supportsLightweightScan || declarationImports > 0,
+      readiness: 'needs-review',
+      lossKinds: uniqueStrings([
+        'targetProjectionLoss',
+        ...(declarationImports || profile.supportsLightweightScan ? [] : ['declarationOnlyCoverage'])
+      ]),
+      categories: uniqueStrings([
+        'targetProjectionLoss',
+        ...(declarationImports || profile.supportsLightweightScan ? [] : ['declarationsOnly'])
+      ]),
+      reason: 'Declaration stubs are emitted when exact source is unavailable or disabled; executable bodies and full type semantics remain unavailable.',
+      evidence: {
+        imports: imports.length,
+        importsWithDeclarations: declarationImports
+      },
+      notes: uniqueStrings([
+        'Stub projection is review-required and should not be treated as a round-trip proof.',
+        ...(projectionUnsupportedFeatureLossKinds(knownLossKinds).length
+          ? ['Known source-language feature losses may still be present behind preserved source or stubs.']
+          : [])
+      ])
+    }
+  };
+}
+
+function projectionTargetCoverageEntry(profile, target, input, context = {}) {
+  const normalizedTarget = normalizeProjectionMatrixTargets([target])[0] ?? String(target);
+  const declaredTargets = new Set(normalizeProjectionMatrixTargets(profile.projectionTargets ?? []));
+  const adapterTargets = new Set((input.matchingAdapters ?? []).flatMap(adapterProjectionTargets));
+  const targetAdapter = context.matchingNativeTargetProjectionAdapter({
+    sourceLanguage: profile.language,
+    target: normalizedTarget,
+    sourcePath: input.matchingImports?.[0]?.sourcePath ?? input.matchingImports?.[0]?.nativeSource?.sourcePath
+  }, input.matchingTargetAdapters ?? []);
+  const targetAdapterSummary = targetAdapter ? context.normalizeNativeTargetProjectionAdapter(targetAdapter) : undefined;
+  const sameSourceTarget = nativeLanguageCompileTarget(profile.language, profile.aliases) === normalizedTarget;
+  const hasProjectionAdapter = Boolean(targetAdapterSummary) || declaredTargets.has(normalizedTarget) || adapterTargets.has(normalizedTarget);
+  if (!hasProjectionAdapter) {
+    return {
+      target: normalizedTarget,
+      lossClass: 'missingAdapter',
+      supported: false,
+      readiness: 'blocked',
+      lossKinds: ['targetProjectionLoss'],
+      categories: ['targetProjectionLoss'],
+      reason: `No native-to-${normalizedTarget} projection adapter is declared for ${profile.language}.`,
+      adapter: undefined,
+      notes: ['The source can still be preserved or stubbed in its original language when import evidence supports that mode.']
+    };
+  }
+
+  const featureLossKinds = projectionUnsupportedFeatureLossKinds(input.knownLossKinds);
+  if (targetAdapterSummary) {
+    const handledLossKinds = new Set(targetAdapterSummary.coverage.handledLossKinds ?? []);
+    const unhandledFeatureLossKinds = featureLossKinds.filter((kind) => !handledLossKinds.has(kind));
+    if (unhandledFeatureLossKinds.length) {
+      return {
+        target: normalizedTarget,
+        lossClass: 'unsupportedTargetFeatures',
+        supported: true,
+        readiness: 'needs-review',
+        lossKinds: unhandledFeatureLossKinds,
+        categories: uniqueStrings(unhandledFeatureLossKinds.map(context.nativeImportCategoryForLossKind)),
+        reason: `${profile.language} has target adapter ${targetAdapterSummary.id}, but source feature losses remain unhandled for ${normalizedTarget}: ${unhandledFeatureLossKinds.join(', ')}.`,
+        adapter: targetAdapterSummary.id,
+        adapterKind: 'targetProjection',
+        adapterVersion: targetAdapterSummary.version,
+        adapterCoverage: targetAdapterSummary.coverage,
+        notes: uniqueStrings([
+          ...(targetAdapterSummary.coverage.notes ?? []),
+          'Adapter output is available, but merge readiness still requires review for unhandled source-language feature losses.'
+        ])
+      };
+    }
+    const adapterLossKinds = uniqueStrings(targetAdapterSummary.coverage.lossKinds ?? []);
+    return {
+      target: normalizedTarget,
+      lossClass: 'targetAdapterProjection',
+      supported: true,
+      readiness: targetAdapterSummary.coverage.readiness ?? 'needs-review',
+      lossKinds: adapterLossKinds,
+      categories: uniqueStrings(adapterLossKinds.map(context.nativeImportCategoryForLossKind)),
+      reason: `${profile.language} can project to ${normalizedTarget} through host target adapter ${targetAdapterSummary.id}.`,
+      adapter: targetAdapterSummary.id,
+      adapterKind: 'targetProjection',
+      adapterVersion: targetAdapterSummary.version,
+      adapterCoverage: targetAdapterSummary.coverage,
+      notes: uniqueStrings([
+        ...(targetAdapterSummary.coverage.notes ?? []),
+        'The host adapter owns native-to-target translation semantics and must provide evidence for merge admission.'
+      ])
+    };
+  }
+
+  if (featureLossKinds.length) {
+    return {
+      target: normalizedTarget,
+      lossClass: 'unsupportedTargetFeatures',
+      supported: true,
+      readiness: 'needs-review',
+      lossKinds: featureLossKinds,
+      categories: uniqueStrings(featureLossKinds.map(context.nativeImportCategoryForLossKind)),
+      reason: `${profile.language} coverage declares source features that this facade cannot prove lossless for ${normalizedTarget}: ${featureLossKinds.join(', ')}.`,
+      adapter: projectionTargetAdapterName(profile, normalizedTarget, input.matchingAdapters),
+      notes: ['Use exact parser or semantic adapter evidence before treating this target projection as merge-ready.']
+    };
+  }
+
+  if (sameSourceTarget) {
+    return {
+      target: normalizedTarget,
+      lossClass: 'exactSourceProjection',
+      supported: true,
+      readiness: 'ready',
+      lossKinds: [],
+      categories: [],
+      reason: `${profile.language} can project to its source language exactly when source preservation evidence is available.`,
+      adapter: projectionTargetAdapterName(profile, normalizedTarget, input.matchingAdapters),
+      notes: ['Without exact source text, the source projection falls back to declaration stubs.']
+    };
+  }
+
+  return {
+    target: normalizedTarget,
+    lossClass: 'nativeSourceStubs',
+    supported: true,
+    readiness: 'needs-review',
+    lossKinds: ['targetProjectionLoss'],
+    categories: ['targetProjectionLoss'],
+    reason: `${profile.language} declares a ${normalizedTarget} target slot, but this facade only exposes declaration-level native import projection evidence.`,
+    adapter: projectionTargetAdapterName(profile, normalizedTarget, input.matchingAdapters),
+    notes: ['Host-owned semantic adapters can upgrade this cell with stronger evidence.']
+  };
+}
+
+function projectionTargetLossMatrixSummary(languages) {
+  const byLossClass = {};
+  const sourceProjectionByLossClass = {};
+  let targetEntries = 0;
+  for (const language of languages) {
+    for (const projection of [language.sourceProjection?.exactSource, language.sourceProjection?.stubs].filter(Boolean)) {
+      sourceProjectionByLossClass[projection.lossClass] = (sourceProjectionByLossClass[projection.lossClass] ?? 0) + 1;
+    }
+    for (const target of language.targets ?? []) {
+      targetEntries += 1;
+      byLossClass[target.lossClass] = (byLossClass[target.lossClass] ?? 0) + 1;
+    }
+  }
+  return {
+    languages: languages.length,
+    targetEntries,
+    byLossClass,
+    sourceProjectionByLossClass,
+    exactSourceProjection: (sourceProjectionByLossClass.exactSourceProjection ?? 0) + (byLossClass.exactSourceProjection ?? 0),
+    nativeSourceStubs: (sourceProjectionByLossClass.nativeSourceStubs ?? 0) + (byLossClass.nativeSourceStubs ?? 0),
+    targetAdapterProjection: byLossClass.targetAdapterProjection ?? 0,
+    unsupportedTargetFeatures: byLossClass.unsupportedTargetFeatures ?? 0,
+    missingAdapters: byLossClass.missingAdapter ?? 0
+  };
+}
+
+function countProjectionLossClasses(entries) {
+  const counts = {};
+  for (const entry of entries ?? []) {
+    counts[entry.lossClass] = (counts[entry.lossClass] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function hasExactSourceProjectionEvidence(imported) {
+  const preservation = imported?.metadata?.sourcePreservation
+    ?? imported?.nativeSource?.metadata?.sourcePreservation
+    ?? imported?.nativeAst?.metadata?.sourcePreservation;
+  const expectedHash = imported?.nativeSource?.sourceHash ?? imported?.nativeAst?.sourceHash ?? imported?.sourceHash;
+  return Boolean(preservation?.summary?.exactSourceAvailable && (!expectedHash || preservation.sourceHash === expectedHash));
+}
+
+function hasNativeProjectionDeclarations(imported) {
+  const semanticIndex = imported?.semanticIndex ?? imported?.universalAst?.semanticIndex;
+  return (semanticIndex?.symbols?.length ?? 0) > 0;
+}
+
+function projectionUnsupportedFeatureLossKinds(lossKinds) {
+  const unsupported = new Set([
+    'macroExpansion',
+    'macroHygiene',
+    'preprocessor',
+    'conditionalCompilation',
+    'metaprogramming',
+    'reflection',
+    'dynamicRuntime',
+    'dynamicDispatch',
+    'generatedCode',
+    'overloadResolution',
+    'typeInference',
+    'unsupportedSyntax',
+    'unsupportedSemantic'
+  ]);
+  return uniqueStrings((lossKinds ?? []).filter((kind) => unsupported.has(kind)));
+}
+
+function adapterProjectionTargets(adapter) {
+  return normalizeProjectionMatrixTargets(
+    adapter?.projectionTargets
+      ?? adapter?.coverage?.projectionTargets
+      ?? adapter?.metadata?.projectionTargets
+      ?? []
+  );
+}
+
+function projectionTargetAdapterName(profile, target, adapters = []) {
+  const adapter = adapters.find((candidate) => adapterProjectionTargets(candidate).includes(target));
+  if (adapter) return adapter.id ?? adapter.parser;
+  return profile.projectionTargets?.includes(target) ? `frontier-native-source-${target}` : undefined;
+}