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

package/dist/language-adapter-package-contracts.js

@@ -0,0 +1,289 @@
+import {
+  nativeProjectionTargetsForLanguage
+} from './coverage-matrix-profiles.js';
+import {
+  NativeParserAstFormatProfiles,
+  parserAstFormatIdForParser
+} from './native-parser-ast-format-profiles.js';
+import {
+  idFragment,
+  normalizeNativeLanguageId,
+  uniqueStrings
+} from './native-import-utils.js';
+
+export const LanguageAdapterPackageReleaseReadinessStatuses = Object.freeze([
+  'ready',
+  'ready-with-losses',
+  'needs-review',
+  'blocked'
+]);
+
+const packageRows = [
+  row('@shapeshift-labs/frontier-lang-typescript', '0.3.6', 'typescript', 'typescript-compiler-api', { target: 'typescript' }),
+  row('@shapeshift-labs/frontier-lang-javascript', '0.2.6', 'javascript', 'estree', { target: 'javascript', formats: ['estree', 'babel'] }),
+  row('@shapeshift-labs/frontier-lang-rust', '0.2.6', 'rust', 'rust-syn', { target: 'rust', proofKeys: ['parserAst', 'sourceMap', 'semanticSidecar', 'macroExpansionEvidence'] }),
+  row('@shapeshift-labs/frontier-lang-python', '0.2.6', 'python', 'python-ast', { target: 'python', formats: ['python-ast', 'libcst'] }),
+  row('@shapeshift-labs/frontier-lang-c', '0.2.6', 'c', 'clang-ast-json', { target: 'c', proofKeys: ['parserAst', 'sourceMap', 'semanticSidecar', 'compileCommandsHash', 'preprocessorRecordsHash'] }),
+  platform('@shapeshift-labs/frontier-lang-java', '0.0.0', 'java', 'java-ast', ['semanticdb', 'lsp']),
+  platform('@shapeshift-labs/frontier-lang-kotlin', '0.0.0', 'kotlin', 'kotlin-psi', ['semanticdb', 'lsp']),
+  platform('@shapeshift-labs/frontier-lang-swift', '0.0.0', 'swift', 'swift-syntax', ['sourcekit-lsp', 'lsp']),
+  platform('@shapeshift-labs/frontier-lang-csharp', '0.0.0', 'csharp', 'roslyn-csharp', ['lsp']),
+  platform('@shapeshift-labs/frontier-lang-go', '0.0.0', 'go', 'go-ast', ['lsp']),
+  platform('@shapeshift-labs/frontier-lang-clang', '0.0.0', 'c', 'clang-ast-json', ['lsp'], {
+    supportedLanguages: ['c', 'cpp'],
+    proofKeys: ['parserAst', 'semanticIndex', 'compileCommandsHash', 'preprocessorRecordsHash']
+  })
+];
+
+export const LanguageAdapterPackageContracts = Object.freeze(packageRows.map(createLanguageAdapterPackageContract));
+
+export function createLanguageAdapterPackageContract(input = {}) {
+  const language = normalizeNativeLanguageId(input.language);
+  const parser = String(input.parser ?? input.sourceParser?.parser ?? input.parserFormat ?? 'unknown');
+  const format = parserAstFormatIdForParser(input.parserFormat ?? input.sourceParser?.format ?? parser);
+  const formatProfile = NativeParserAstFormatProfiles.find((profile) =>
+    profile.id === format || (profile.aliases ?? []).includes(format)
+  );
+  const packageName = String(input.packageName ?? input.package?.name ?? `@shapeshift-labs/frontier-lang-${language || 'adapter'}`);
+  const packageVersion = String(input.packageVersion ?? input.package?.version ?? '0.0.0');
+  const packageClass = input.packageClass ?? input.package?.packageClass ?? 'target-projection';
+  const targetRows = projectionRows(input, language);
+  const releaseStatus = normalizeReleaseStatus(input.releaseReadiness?.status ?? input.releaseReadiness ?? input.readiness);
+  const releaseReady = input.releaseReadiness?.releaseReady ?? input.releaseReady ?? (releaseStatus === 'ready' || releaseStatus === 'ready-with-losses');
+  const supportedTargetRows = targetRows.filter((target) => target.supported);
+  const contract = {
+    kind: 'frontier.lang.languageAdapterPackageContract',
+    version: 3,
+    id: input.id ?? `language_adapter_package_contract_${idFragment(packageName)}`,
+    packageName,
+    packageVersion,
+    package: Object.freeze({
+      name: packageName,
+      version: packageVersion,
+      exportPath: input.exportPath ?? input.package?.exportPath ?? '.',
+      packageClass,
+      family: input.family ?? input.package?.family ?? adapterFamily(language, parser),
+      adapterId: input.adapterId ?? `${idFragment(packageName)}_adapter`
+    }),
+    sourceParser: Object.freeze({
+      language,
+      parser,
+      format,
+      supportedLanguages: freezeStrings(input.supportedLanguages ?? input.languages ?? input.sourceParser?.supportedLanguages ?? [language]),
+      supportedFormats: freezeStrings(input.supportedFormats ?? input.formats ?? [format]),
+      formatKind: formatProfile?.kind ?? 'unknown',
+      exactness: input.exactness ?? formatProfile?.exactness ?? 'unknown',
+      sourceRangeModel: input.sourceRangeModel ?? formatProfile?.sourceRangeModel ?? 'unknown',
+      preservesTokens: input.preservesTokens ?? formatProfile?.preservesTokens ?? false,
+      preservesTrivia: input.preservesTrivia ?? formatProfile?.preservesTrivia ?? false,
+      supportsErrorRecovery: input.supportsErrorRecovery ?? formatProfile?.supportsErrorRecovery ?? false,
+      caveats: freezeTextList(input.sourceParser?.caveats ?? input.parserCaveats ?? formatProfile?.notes ?? [])
+    }),
+    targetProjection: Object.freeze({
+      supported: targetRows.some((target) => target.supported),
+      targets: freezeStrings(supportedTargetRows.map((target) => target.target)),
+      defaultTarget: input.target ?? supportedTargetRows[0]?.target,
+      support: Object.freeze(targetRows),
+      caveats: freezeTextList(input.targetProjection?.caveats ?? input.targetCaveats ?? targetProjectionCaveats(targetRows, packageClass))
+    }),
+    semanticIndex: Object.freeze({
+      supported: input.semanticIndex?.supported ?? true,
+      formats: freezeStrings(input.semanticIndex?.formats ?? ['frontier-semantic-index']),
+      capabilities: freezeStrings(input.semanticIndex?.capabilities ?? ['declarations', 'symbols', 'sourceMapMappings', 'ownershipRegions']),
+      hostEvidenceRequired: input.semanticIndex?.hostEvidenceRequired ?? packageClass !== 'target-projection'
+    }),
+    proofEvidence: Object.freeze({
+      supported: input.proofEvidence?.supported ?? true,
+      evidenceKinds: freezeStrings(input.proofEvidence?.evidenceKinds ?? ['parser', 'source-map', 'semantic-sidecar', 'package-contract']),
+      proofKinds: freezeStrings(input.proofEvidence?.proofKinds ?? ['semantic-import-sidecar', 'native-import-result-contract']),
+      requiredEvidenceKeys: freezeStrings(input.proofEvidence?.requiredEvidenceKeys ?? input.proofKeys ?? ['parserAst', 'sourceMap', 'semanticSidecar']),
+      hostEvidenceRequired: input.proofEvidence?.hostEvidenceRequired ?? packageClass !== 'target-projection'
+    }),
+    releaseReadiness: Object.freeze({
+      status: releaseStatus,
+      releaseReady,
+      packageName,
+      packageVersion,
+      versionSource: input.releaseReadiness?.versionSource ?? input.versionSource ?? packageVersionSource(packageVersion, packageClass),
+      reasons: freezeStrings(input.releaseReadiness?.reasons ?? input.reasons ?? releaseReasons(packageClass, releaseStatus)),
+      blockers: freezeStrings(input.releaseReadiness?.blockers ?? input.blockers ?? (releaseReady ? [] : ['adapter package is a structural contract candidate'])),
+      signals: freezeTextList(input.releaseReadiness?.signals ?? input.signals ?? releaseSignals(packageClass, releaseStatus, releaseReady, packageVersion, input.releaseReadiness?.versionSource ?? input.versionSource))
+    }),
+    runtime: Object.freeze({
+      importsAdapterPackage: false,
+      contractOnly: true,
+      importPath: input.runtime?.importPath ?? packageName
+    }),
+    metadata: Object.freeze({
+      note: 'Static adapter package contract metadata for release trains and semantic merge planners; querying it does not import the adapter package.',
+      ...(input.metadata ?? {})
+    })
+  };
+  return Object.freeze(contract);
+}
+
+export function getLanguageAdapterPackageContract(ref, contracts = LanguageAdapterPackageContracts) {
+  if (ref && typeof ref === 'object') return queryLanguageAdapterPackageContracts(ref, contracts)[0];
+  const text = String(ref ?? '').trim();
+  const normalized = normalizeNativeLanguageId(text);
+  return (contracts ?? []).find((contract) =>
+    contract.id === text ||
+    contract.packageName === text ||
+    contract.package.name === text ||
+    contract.package.adapterId === text ||
+    contract.sourceParser.language === normalized
+  );
+}
+
+export function queryLanguageAdapterPackageContracts(query = {}, contracts = LanguageAdapterPackageContracts) {
+  const language = normalizeNativeLanguageId(query.language ?? query.sourceLanguage);
+  const target = query.target ? String(query.target).toLowerCase() : '';
+  const semanticFormat = query.semanticIndexFormat ? String(query.semanticIndexFormat).toLowerCase() : '';
+  return (contracts ?? []).filter((contract) =>
+    (!query.packageName || contract.packageName === query.packageName) &&
+    (!query.packageClass || contract.package.packageClass === query.packageClass) &&
+    (!language || contract.sourceParser.language === language) &&
+    (!target || contract.targetProjection.targets.includes(target)) &&
+    (!semanticFormat || contract.semanticIndex.formats.map((format) => format.toLowerCase()).includes(semanticFormat)) &&
+    (query.releaseReady === undefined || contract.releaseReadiness.releaseReady === query.releaseReady) &&
+    (query.importsAdapterPackage === undefined || contract.runtime.importsAdapterPackage === query.importsAdapterPackage) &&
+    (query.proofEvidenceSupported === undefined || contract.proofEvidence.supported === query.proofEvidenceSupported)
+  );
+}
+
+export function summarizeLanguageAdapterPackageContracts(contracts = LanguageAdapterPackageContracts) {
+  const list = [...(contracts ?? [])];
+  return Object.freeze({
+    kind: 'frontier.lang.languageAdapterPackageContractSummary',
+    version: 1,
+    packages: list.length,
+    releaseReady: list.filter((contract) => contract.releaseReadiness.releaseReady).length,
+    runtimeImportsAdapterPackages: list.filter((contract) => contract.runtime.importsAdapterPackage).length,
+    languages: freezeStrings(list.map((contract) => contract.sourceParser.language)),
+    parserFormats: freezeStrings(list.map((contract) => contract.sourceParser.format)),
+    projectionTargets: freezeStrings(list.flatMap((contract) => contract.targetProjection.targets)),
+    semanticIndexFormats: freezeStrings(list.flatMap((contract) => contract.semanticIndex.formats)),
+    byPackageClass: countContracts(list, (contract) => contract.package.packageClass),
+    byReleaseReadiness: countContracts(list, (contract) => contract.releaseReadiness.status)
+  });
+}
+
+function row(packageName, packageVersion, language, parser, input = {}) {
+  return {
+    packageName,
+    packageVersion,
+    language,
+    parser,
+    supportedFormats: input.formats,
+    target: input.target,
+    packageClass: 'target-projection',
+    releaseReadiness: { status: 'ready-with-losses', releaseReady: true, versionSource: 'package-json-dependency' },
+    semanticIndex: { formats: ['frontier-semantic-index', 'scip', 'lsif', 'lsp'], hostEvidenceRequired: false },
+    proofKeys: input.proofKeys
+  };
+}
+
+function platform(packageName, packageVersion, language, parser, semanticFormats, input = {}) {
+  return {
+    packageName,
+    packageVersion,
+    language,
+    parser,
+    supportedLanguages: input.supportedLanguages,
+    supportedFormats: input.formats,
+    packageClass: 'platform-importer',
+    targetProjection: { targets: [], caveats: input.targetCaveats },
+    releaseReadiness: { status: 'needs-review', releaseReady: false, versionSource: 'related-package-catalog-placeholder', signals: input.signals },
+    semanticIndex: { formats: ['frontier-semantic-index', ...semanticFormats], hostEvidenceRequired: true },
+    proofEvidence: { hostEvidenceRequired: true, requiredEvidenceKeys: input.proofKeys ?? ['parserAst', 'semanticIndex', 'buildGraphEvidence'] },
+    parserCaveats: input.parserCaveats
+  };
+}
+
+function projectionRows(input, language) {
+  const targets = input.targetProjection?.targets ?? input.targets ?? input.target ?? nativeProjectionTargetsForLanguage(language);
+  const normalizedTargets = freezeStrings(targets);
+  if (normalizedTargets.length === 0) {
+    return [Object.freeze({
+      target: 'none',
+      supported: false,
+      support: 'not-shipped',
+      readiness: 'needs-review',
+      lossClass: 'missingAdapter',
+      reasons: Object.freeze(['No target projection package is declared for this platform importer contract.'])
+    })];
+  }
+  return normalizedTargets.map((target) => Object.freeze({
+    target,
+    supported: true,
+    support: input.targetProjection?.support ?? 'package-projection',
+    readiness: input.targetProjection?.readiness ?? 'ready-with-losses',
+    lossClass: input.targetProjection?.lossClass ?? 'targetAdapterProjection',
+    reasons: freezeStrings(input.targetProjection?.reasons ?? ['Same-language target projection is package-owned; semantic equivalence still depends on evidence.'])
+  }));
+}
+
+function normalizeReleaseStatus(value) {
+  const status = String(value ?? 'ready-with-losses').toLowerCase();
+  return LanguageAdapterPackageReleaseReadinessStatuses.includes(status) ? status : 'needs-review';
+}
+
+function releaseReasons(packageClass, status) {
+  if (packageClass === 'platform-importer') return ['Platform importer contract is structural and requires host parser/build evidence before release.'];
+  if (status === 'ready') return ['Package contract declares required parser, projection, semantic-index, and proof/evidence metadata.'];
+  return ['Package contract is release-ready with explicit loss/evidence boundaries.'];
+}
+
+function packageVersionSource(packageVersion, packageClass) {
+  if (packageVersion === '0.0.0') return 'related-package-catalog-placeholder';
+  if (packageClass === 'target-projection') return 'package-json-dependency';
+  return 'static-package-catalog';
+}
+
+function releaseSignals(packageClass, status, releaseReady, packageVersion, versionSource) {
+  const source = versionSource ?? packageVersionSource(packageVersion, packageClass);
+  const signals = ['Contract metadata is static and does not import the adapter package at runtime.'];
+  if (source === 'package-json-dependency') signals.push('Package version must match this facade package.json dependency.');
+  if (packageVersion === '0.0.0') signals.push('0.0.0 marks a structural placeholder until a standalone adapter package version is pinned.');
+  if (packageClass !== 'target-projection') signals.push('Host parser, build graph, and semantic evidence are required before release.');
+  signals.push(releaseReady
+    ? `Release status ${status} is ready for the facade with explicit loss boundaries.`
+    : `Release status ${status} blocks package release without additional evidence.`);
+  return signals;
+}
+
+function targetProjectionCaveats(targetRows, packageClass) {
+  if (!targetRows.some((target) => target.supported)) {
+    return ['No target projection package is declared; preserve native source or require host-owned target adapter evidence.'];
+  }
+  const caveats = ['Target projection support is a package-contract claim; semantic equivalence still depends on parser, source-map, and proof evidence.'];
+  if (packageClass !== 'target-projection') caveats.push('Platform importer contracts do not ship target projection adapters from this facade.');
+  return caveats;
+}
+
+function adapterFamily(language, parser) {
+  if (language === 'javascript' || language === 'typescript') return 'javascript-typescript';
+  if (language === 'java' || language === 'kotlin') return 'jvm';
+  if (language === 'csharp') return 'dotnet';
+  if (language === 'c' || language === 'cpp' || language === 'rust') return 'systems';
+  return language || parser || 'native';
+}
+
+function freezeStrings(value) {
+  if (value === undefined || value === null) return Object.freeze([]);
+  return Object.freeze(uniqueStrings(Array.isArray(value) ? value : [value]).map((entry) => String(entry).toLowerCase()));
+}
+
+function freezeTextList(value) {
+  if (value === undefined || value === null) return Object.freeze([]);
+  return Object.freeze(uniqueStrings(Array.isArray(value) ? value : [value]));
+}
+
+function countContracts(contracts, select) {
+  const counts = {};
+  for (const contract of contracts) {
+    const key = String(select(contract) ?? 'unknown');
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return Object.freeze(counts);
+}

package/dist/native-import-coverage-matrix.js

@@ -0,0 +1,237 @@
+import {
+  normalizeNativeLanguageId,
+  uniqueStrings
+} from './native-import-utils.js';
+import {
+  NativeImportLanguageProfiles,
+  ProjectionTargetLossClasses,
+  mergeNativeImportProfiles
+} from './coverage-matrix-profiles.js';
+
+export function createNativeImportCoverageMatrix(input = {}, context = {}) {
+  const imports = input.imports ?? [];
+  const adapters = input.adapters ?? [];
+  const profiles = mergeNativeImportProfiles(input.languages ?? NativeImportLanguageProfiles, imports, adapters, [], context);
+  const languages = profiles.map((profile) => nativeImportCoverageForProfile(profile, imports, adapters, context));
+  const summary = languages.reduce((totals, entry) => {
+    totals.languages += 1;
+    if (entry.supportsLightweightScan) totals.lightweightScanners += 1;
+    if (entry.parserAdapters.length) totals.parserAdapterSlots += entry.parserAdapters.length;
+    totals.imports += entry.imports.total;
+    totals.symbols += entry.imports.symbols;
+    totals.sourceMaps += entry.imports.sourceMaps;
+    totals.sourceMapMappings += entry.imports.sourceMapMappings;
+    totals.losses += entry.imports.losses;
+    totals.byReadiness[entry.imports.readiness] = (totals.byReadiness[entry.imports.readiness] ?? 0) + 1;
+    for (const [kind, count] of Object.entries(entry.imports.lossKinds)) {
+      totals.lossKinds[kind] = (totals.lossKinds[kind] ?? 0) + count;
+    }
+    totals.adapterCoverage = mergeNativeImporterAdapterCoverageAggregates(totals.adapterCoverage, entry.adapterCoverage);
+    return totals;
+  }, {
+    languages: 0,
+    lightweightScanners: 0,
+    parserAdapterSlots: 0,
+    imports: 0,
+    symbols: 0,
+    sourceMaps: 0,
+    sourceMapMappings: 0,
+    losses: 0,
+    byReadiness: {},
+    lossKinds: {},
+    adapterCoverage: emptyNativeImporterAdapterCoverageAggregate()
+  });
+  return {
+    kind: 'frontier.lang.nativeImportCoverageMatrix',
+    version: 1,
+    generatedAt: input.generatedAt ?? Date.now(),
+    languages,
+    summary,
+    metadata: {
+      compileTargets: [...(context.compileTargets ?? [])],
+      projectionTargetLossClasses: [...ProjectionTargetLossClasses],
+      note: 'Coverage is evidence and capability metadata, not a claim that every language feature is losslessly portable.'
+    }
+  };
+}
+
+export function nativeImportReadiness(imported) {
+  return imported?.metadata?.semanticMergeReadiness
+    ?? imported?.metadata?.nativeImportLossSummary?.semanticMergeReadiness
+    ?? imported?.mergeCandidates?.[0]?.readiness
+    ?? 'ready';
+}
+
+function nativeImportCoverageForProfile(profile, imports, adapters, context = {}) {
+  const aliases = new Set([profile.language, ...(profile.aliases ?? [])].map(normalizeNativeLanguageId).filter(Boolean));
+  const matchingImports = imports.filter((imported) => aliases.has(normalizeNativeLanguageId(imported?.language ?? imported?.nativeAst?.language)));
+  const matchingAdapters = adapters.filter((adapter) => aliases.has(normalizeNativeLanguageId(adapter?.language)));
+  const lossSummary = context.summarizeNativeImportLosses(matchingImports.flatMap((imported) => imported?.losses ?? []), {
+    evidence: matchingImports.flatMap((imported) => imported?.evidence ?? [])
+  });
+  const readiness = matchingImports.length
+    ? lossSummary.semanticMergeReadiness
+    : profile.supportsLightweightScan ? profile.defaultReadiness : 'blocked';
+  const importedParsers = uniqueStrings(matchingImports.map((imported) => imported?.nativeAst?.parser ?? imported?.parser ?? imported?.metadata?.parser).filter(Boolean));
+  const sourceMaps = matchingImports.flatMap((imported) => imported?.sourceMaps ?? imported?.universalAst?.sourceMaps ?? []);
+  const adapterCoverage = summarizeNativeImporterAdapterCoverageEntries([
+    ...matchingImports.map((imported) => nativeImporterAdapterCoverageEntryFromImport(imported)).filter(Boolean),
+    ...matchingAdapters.map((adapter) => nativeImporterAdapterCoverageEntryFromAdapter(adapter, context)).filter(Boolean)
+  ], context);
+  return {
+    language: profile.language,
+    aliases: profile.aliases,
+    extensions: profile.extensions,
+    supportsLightweightScan: profile.supportsLightweightScan,
+    parserAdapters: uniqueStrings([...(profile.parserAdapters ?? []), ...matchingAdapters.map((adapter) => adapter.parser ?? adapter.id).filter(Boolean)]),
+    projectionTargets: profile.projectionTargets,
+    knownLossKinds: uniqueStrings([...(profile.knownLossKinds ?? []), ...Object.keys(lossSummary.byKind)]),
+    defaultReadiness: profile.defaultReadiness,
+    notes: profile.notes,
+    adapterCoverage,
+    imports: {
+      total: matchingImports.length,
+      parsers: importedParsers,
+      readiness,
+      readinessReasons: matchingImports.length ? lossSummary.readinessReasons : nativeImportCoverageReasons(profile),
+      symbols: matchingImports.reduce((sum, imported) => sum + (imported?.semanticIndex?.symbols?.length ?? imported?.universalAst?.semanticIndex?.symbols?.length ?? 0), 0),
+      sourceMaps: sourceMaps.length,
+      sourceMapMappings: sourceMaps.reduce((sum, sourceMap) => sum + (sourceMap?.mappings?.length ?? 0), 0),
+      losses: lossSummary.total,
+      lossKinds: lossSummary.byKind,
+      lossCategories: lossSummary.categories
+    }
+  };
+}
+
+export function nativeImporterAdapterCoverageEntryFromImport(imported) {
+  const coverage = imported?.adapter?.coverage
+    ?? imported?.metadata?.adapterCoverage
+    ?? imported?.nativeAst?.metadata?.adapterCoverage
+    ?? imported?.nativeSource?.metadata?.adapterCoverage;
+  if (!coverage) return undefined;
+  return {
+    adapterId: imported?.adapter?.id ?? imported?.metadata?.adapterId ?? imported?.nativeAst?.metadata?.adapterId,
+    language: imported?.adapter?.language ?? imported?.language ?? imported?.nativeAst?.language,
+    parser: imported?.adapter?.parser ?? imported?.nativeAst?.parser ?? imported?.nativeSource?.parser,
+    coverage
+  };
+}
+
+function nativeImporterAdapterCoverageEntryFromAdapter(adapter, context = {}) {
+  if (!adapter) return undefined;
+  const summary = context.normalizeNativeImporterAdapter(adapter);
+  return {
+    adapterId: summary.id,
+    language: summary.language,
+    parser: summary.parser,
+    coverage: summary.coverage
+  };
+}
+
+export function safeNativeImporterAdapterSummary(adapter, context = {}) {
+  try {
+    return context.normalizeNativeImporterAdapter(adapter);
+  } catch {
+    return undefined;
+  }
+}
+
+export function summarizeNativeImporterAdapterCoverageEntries(entries = [], context = {}) {
+  const aggregate = emptyNativeImporterAdapterCoverageAggregate();
+  for (const entry of entries) {
+    const coverage = normalizeNativeImporterAdapterCoverageForEvidence(entry.coverage, context);
+    const capabilityEvidence = coverage.capabilityEvidence;
+    const summary = {
+      adapterId: entry.adapterId,
+      language: entry.language,
+      parser: entry.parser,
+      exactness: coverage.exactness,
+      declared: capabilityNamesByBoolean(capabilityEvidence.capabilities, 'declared'),
+      observed: capabilityNamesByBoolean(capabilityEvidence.capabilities, 'observed'),
+      effective: capabilityNamesByBoolean(capabilityEvidence.capabilities, 'effective'),
+      gaps: capabilityEvidence.gaps,
+      declaredOnly: capabilityEvidence.declaredOnly,
+      observedOnly: capabilityEvidence.observedOnly
+    };
+    aggregate.total += 1;
+    aggregate.summaries.push(summary);
+    incrementCoverageCapabilityCounts(aggregate.declared, summary.declared);
+    incrementCoverageCapabilityCounts(aggregate.observed, summary.observed);
+    incrementCoverageCapabilityCounts(aggregate.effective, summary.effective);
+    incrementCoverageCapabilityCounts(aggregate.gaps, summary.gaps);
+    incrementCoverageCapabilityCounts(aggregate.declaredOnly, summary.declaredOnly);
+    incrementCoverageCapabilityCounts(aggregate.observedOnly, summary.observedOnly);
+  }
+  return {
+    ...aggregate,
+    summaries: Object.freeze(aggregate.summaries)
+  };
+}
+
+function normalizeNativeImporterAdapterCoverageForEvidence(coverage = {}, context = {}) {
+  if (coverage.capabilityEvidence) return coverage;
+  const declared = coverage.declared ?? context.adapterCoverageSnapshotFromSummary(coverage);
+  const observed = context.normalizeNativeImporterAdapterObservedCoverage(coverage.observed, declared);
+  const effective = context.effectiveNativeImporterAdapterCoverage(declared, observed);
+  return {
+    ...coverage,
+    ...effective,
+    declared,
+    observed,
+    capabilityEvidence: context.nativeImporterAdapterCapabilityEvidence(declared, observed, effective)
+  };
+}
+
+export function emptyNativeImporterAdapterCoverageAggregate() {
+  return {
+    total: 0,
+    declared: {},
+    observed: {},
+    effective: {},
+    gaps: {},
+    declaredOnly: {},
+    observedOnly: {},
+    summaries: []
+  };
+}
+
+function mergeNativeImporterAdapterCoverageAggregates(left, right) {
+  const merged = emptyNativeImporterAdapterCoverageAggregate();
+  for (const aggregate of [left, right]) {
+    if (!aggregate) continue;
+    merged.total += aggregate.total ?? 0;
+    incrementCoverageCapabilityCounts(merged.declared, aggregate.declared ?? {});
+    incrementCoverageCapabilityCounts(merged.observed, aggregate.observed ?? {});
+    incrementCoverageCapabilityCounts(merged.effective, aggregate.effective ?? {});
+    incrementCoverageCapabilityCounts(merged.gaps, aggregate.gaps ?? {});
+    incrementCoverageCapabilityCounts(merged.declaredOnly, aggregate.declaredOnly ?? {});
+    incrementCoverageCapabilityCounts(merged.observedOnly, aggregate.observedOnly ?? {});
+    merged.summaries.push(...(aggregate.summaries ?? []));
+  }
+  return {
+    ...merged,
+    summaries: Object.freeze(merged.summaries)
+  };
+}
+
+function capabilityNamesByBoolean(rows, property) {
+  return rows.filter((row) => row[property]).map((row) => row.capability);
+}
+
+function incrementCoverageCapabilityCounts(target, capabilities) {
+  if (Array.isArray(capabilities)) {
+    for (const capability of capabilities) {
+      target[capability] = (target[capability] ?? 0) + 1;
+    }
+    return;
+  }
+  for (const [capability, count] of Object.entries(capabilities ?? {})) {
+    target[capability] = (target[capability] ?? 0) + count;
+  }
+}
+
+export function nativeImportCoverageReasons(profile) {
+  if (!profile.supportsLightweightScan) return ['No built-in scanner coverage profile; host must provide an exact adapter or mark unsupported.'];
+  return ['Built-in coverage is declaration-level only; use injected parser adapters for exact AST/CST, tokens, trivia, type resolution, and round-trip evidence.'];
+}