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

package/dist/semantic-import-sidecar-admission-types.d.ts

@@ -0,0 +1,61 @@
+import type { SemanticMergeReadiness } from '@shapeshift-labs/frontier-lang-kernel';
+
+export interface SemanticImportSidecarQualityWarning {
+  readonly code: string;
+  readonly severity: 'warning' | string;
+  readonly message: string;
+  readonly action: string;
+  readonly sourcePaths: readonly string[];
+}
+
+export interface SemanticImportSidecarProofAdmissionSummary {
+  readonly total: number;
+  readonly obligations: number;
+  readonly discharged: number;
+  readonly pending?: number;
+  readonly failed: number;
+  readonly assumed?: number;
+  readonly externalToolRequired?: number;
+  readonly open: number;
+  readonly unknown: number;
+  readonly empty: boolean;
+  readonly autoMergeProof?: false;
+}
+
+export interface SemanticImportSidecarQuality {
+  readonly schema: 'frontier.lang.semanticSidecarQuality.v1';
+  readonly selected: boolean;
+  readonly eligible: boolean;
+  readonly imported: boolean;
+  readonly importCount: number;
+  readonly symbolCount: number;
+  readonly ownershipRegionCount: number;
+  readonly patchHintCount: number;
+  readonly proofSummary: SemanticImportSidecarProofAdmissionSummary;
+  readonly evidenceCount: number;
+  readonly warningCount: number;
+  readonly warnings: readonly SemanticImportSidecarQualityWarning[];
+  readonly emptyEvidenceWarnings: readonly SemanticImportSidecarQualityWarning[];
+}
+
+export interface SemanticImportSidecarAdmission {
+  readonly schema: 'frontier.lang.semanticSidecarAdmission.v1';
+  readonly selected: boolean;
+  readonly eligible: boolean;
+  readonly imported: boolean;
+  readonly importCount: number;
+  readonly readiness: SemanticMergeReadiness;
+  readonly action: string;
+  readonly counts: {
+    readonly symbols: number;
+    readonly ownershipRegions: number;
+    readonly patchHints: number;
+    readonly evidence: number;
+    readonly proofRecords: number;
+    readonly proofObligations: number;
+    readonly proofFailedObligations: number;
+  };
+  readonly proofSummary: SemanticImportSidecarProofAdmissionSummary;
+  readonly warnings: readonly SemanticImportSidecarQualityWarning[];
+  readonly emptyEvidenceWarnings: readonly SemanticImportSidecarQualityWarning[];
+}

package/dist/semantic-import-sidecar-entry.js

@@ -0,0 +1,78 @@
+import { uniqueRecordsById, uniqueStrings } from './native-import-utils.js';
+import { semanticOwnershipRegionForSymbol, summarizeSemanticImportRegionTaxonomy } from './semantic-import-regions.js';
+import { collectKernelSourcePreservationFromImport } from './semantic-import-source-preservation.js';
+import {
+  summarizeParadigmSemanticsLayer,
+  summarizeProofSpecLayer,
+  summarizeUniversalAstLayers
+} from './semantic-import-layers.js';
+
+function semanticImportSidecarEntry(imported, index, options) {
+  const semanticIndex = imported?.semanticIndex ?? imported?.universalAst?.semanticIndex;
+  const nativeAst = imported?.nativeAst ?? imported?.nativeSource?.ast;
+  const sourceMaps = imported?.sourceMaps ?? imported?.universalAst?.sourceMaps ?? [];
+  const sourceMapMappings = sourceMaps.flatMap((sourceMap) => sourceMap?.mappings ?? []);
+  const sourcePreservationRecords = collectKernelSourcePreservationFromImport(imported);
+  const universalAstLayers = summarizeUniversalAstLayers(imported?.universalAst);
+  const proofSpec = summarizeProofSpecLayer(imported?.universalAst?.proof ?? imported?.proof);
+  const paradigmSemantics = summarizeParadigmSemanticsLayer(imported?.universalAst?.paradigmSemantics ?? imported?.paradigmSemantics);
+  const mappingsBySymbolId = new Map();
+  for (const mapping of sourceMapMappings) {
+    if (mapping.semanticSymbolId && !mappingsBySymbolId.has(mapping.semanticSymbolId)) {
+      mappingsBySymbolId.set(mapping.semanticSymbolId, mapping);
+    }
+  }
+  const symbols = [];
+  const regions = [];
+  for (const symbol of semanticIndex?.symbols ?? []) {
+    const mapping = mappingsBySymbolId.get(symbol.id);
+    const nativeNode = symbol.nativeAstNodeId ? nativeAst?.nodes?.[symbol.nativeAstNodeId] : undefined;
+    const region = semanticOwnershipRegionForSymbol(imported, symbol, mapping, nativeNode, options);
+    regions.push(region);
+    symbols.push({
+      id: symbol.id,
+      name: symbol.name,
+      kind: symbol.kind,
+      language: symbol.language ?? imported?.language,
+      nativeAstNodeId: symbol.nativeAstNodeId,
+      semanticOccurrenceId: mapping?.semanticOccurrenceId,
+      sourceMapMappingId: mapping?.id,
+      sourceSpan: mapping?.sourceSpan ?? symbol.definitionSpan ?? nativeNode?.span,
+      signatureHash: symbol.signatureHash,
+      ownershipRegionId: region.id,
+      ownershipKey: region.key,
+      ownershipRegionKind: region.regionKind,
+      readiness: imported?.metadata?.semanticMergeReadiness ?? imported?.mergeCandidates?.[0]?.readiness ?? 'needs-review'
+    });
+  }
+  const ownershipRegions = uniqueRecordsById(regions);
+  const regionTaxonomy = summarizeSemanticImportRegionTaxonomy(ownershipRegions);
+  return {
+    id: imported?.id ?? `import_${index + 1}`,
+    language: imported?.language,
+    sourcePath: imported?.sourcePath ?? imported?.nativeSource?.sourcePath ?? nativeAst?.sourcePath,
+    sourceHash: imported?.nativeSource?.sourceHash ?? nativeAst?.sourceHash,
+    parser: imported?.nativeAst?.parser ?? nativeAst?.parser,
+    nativeSourceId: imported?.nativeSource?.id,
+    nativeAstId: nativeAst?.id,
+    semanticIndexId: semanticIndex?.id,
+    universalAstId: imported?.universalAst?.id,
+    symbolCount: symbols.length,
+    sourceMapCount: sourceMaps.length,
+    sourceMapMappingCount: sourceMapMappings.length,
+    sourcePreservationRecordCount: sourcePreservationRecords.length,
+    sourcePreservationLevels: uniqueStrings(sourcePreservationRecords.map((record) => record.level).filter(Boolean)),
+    universalAstLayerCount: universalAstLayers.total,
+    universalAstLayerNames: universalAstLayers.names,
+    universalAstLayerIds: universalAstLayers.ids,
+    proofSpec,
+    paradigmSemantics,
+    readiness: imported?.metadata?.semanticMergeReadiness ?? imported?.mergeCandidates?.[0]?.readiness ?? 'needs-review',
+    emptySemanticIndex: symbols.length === 0,
+    regionTaxonomy,
+    symbols,
+    ownershipRegions
+  };
+}
+
+export { semanticImportSidecarEntry };

package/dist/semantic-import-sidecar-types.d.ts

@@ -0,0 +1,275 @@
+import type {
+  FrontierSourceLanguage,
+  SemanticMergeReadiness,
+  SourceMapMappingRecord,
+  SourcePreservationLevel,
+  SourceSpan
+} from '@shapeshift-labs/frontier-lang-kernel';
+import type { NativeImportRegionTaxonomyKind, NativeImportTaxonomyKind } from './index.js';
+import type { SemanticImportSidecarAdmission, SemanticImportSidecarQuality } from './semantic-import-sidecar-admission-types.js';
+import type { SemanticMergeConflictClass, SemanticMergeConflictSummary } from './declarations/semantic-merge-conflicts.js';
+
+export interface SemanticImportOwnershipRegion {
+  readonly id: string;
+  readonly key: string;
+  readonly regionKind?: NativeImportRegionTaxonomyKind;
+  readonly granularity: 'symbol' | string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly documentId?: string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly symbolId?: string;
+  readonly symbolName?: string;
+  readonly symbolKind?: string;
+  readonly nativeAstNodeId?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly precision?: 'exact' | 'declaration' | 'line' | 'estimated' | 'unknown' | string;
+  readonly mergePolicy?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface SemanticImportSidecarSymbol {
+  readonly id: string;
+  readonly name?: string;
+  readonly kind?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly nativeAstNodeId?: string;
+  readonly semanticOccurrenceId?: string;
+  readonly sourceMapMappingId?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly signatureHash?: string;
+  readonly ownershipRegionId: string;
+  readonly ownershipKey: string;
+  readonly ownershipRegionKind?: NativeImportRegionTaxonomyKind;
+  readonly readiness: SemanticMergeReadiness;
+}
+
+export interface SemanticImportRegionTaxonomySummary {
+  readonly kinds: readonly NativeImportRegionTaxonomyKind[];
+  readonly presentKinds: readonly NativeImportRegionTaxonomyKind[];
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly keys: readonly string[];
+  readonly keysByKind: Readonly<Record<string, readonly string[]>>;
+}
+
+export interface SemanticImportPatchHint {
+  readonly id: string;
+  readonly kind: 'source-region-patch' | string;
+  readonly ownershipRegionId: string;
+  readonly ownershipKey: string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly readiness: SemanticMergeReadiness;
+  readonly precision?: string;
+  readonly supportedOperations: readonly string[];
+  readonly projection: {
+    readonly sourceLanguage?: FrontierSourceLanguage | string;
+    readonly targetPath?: string;
+    readonly requiresSourceMap: boolean;
+  };
+}
+
+export interface SemanticImportSidecarImportEntry {
+  readonly id: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly parser?: string;
+  readonly nativeSourceId?: string;
+  readonly nativeAstId?: string;
+  readonly semanticIndexId?: string;
+  readonly universalAstId?: string;
+  readonly symbolCount: number;
+  readonly sourceMapCount: number;
+  readonly sourceMapMappingCount: number;
+  readonly sourcePreservationRecordCount: number;
+  readonly sourcePreservationLevels: readonly SourcePreservationLevel[];
+  readonly universalAstLayerCount: number;
+  readonly universalAstLayerNames: readonly string[];
+  readonly universalAstLayerIds: readonly string[];
+  readonly proofSpec: SemanticImportSidecarProofSpecSummary;
+  readonly paradigmSemantics: SemanticImportSidecarParadigmSemanticsSummary;
+  readonly readiness: SemanticMergeReadiness;
+  readonly emptySemanticIndex: boolean;
+  readonly regionTaxonomy?: SemanticImportRegionTaxonomySummary;
+}
+
+export interface SemanticImportSidecarSourcePreservationRecord {
+  readonly id: string;
+  readonly level: SourcePreservationLevel;
+  readonly precision?: string;
+  readonly sourceMapId?: string;
+  readonly sourceMapMappingId?: string;
+  readonly semanticNodeId?: string;
+  readonly nativeSourceId?: string;
+  readonly nativeAstNodeId?: string;
+  readonly semanticSymbolId?: string;
+  readonly semanticOccurrenceId?: string;
+  readonly sourcePath?: string;
+  readonly generatedPath?: string;
+  readonly lossIds: readonly string[];
+  readonly evidenceIds: readonly string[];
+  readonly reasons: readonly string[];
+}
+
+export interface SemanticImportSidecarUniversalAstLayerSummary {
+  readonly total: number;
+  readonly names: readonly string[];
+  readonly ids: readonly string[];
+  readonly byName: Readonly<Record<string, number>>;
+  readonly empty: boolean;
+}
+
+export interface SemanticImportSidecarProofSpecSummary {
+  readonly total: number;
+  readonly ids: readonly string[];
+  readonly contracts: number;
+  readonly refinements: number;
+  readonly invariants: number;
+  readonly termination: number;
+  readonly temporal: number;
+  readonly obligations: number;
+  readonly artifacts: number;
+  readonly assumptions: number;
+  readonly evidence: number;
+  readonly discharged: number;
+  readonly pending?: number;
+  readonly failed: number;
+  readonly open: number;
+  readonly unknown: number;
+  readonly stale: number;
+  readonly assumed: number;
+  readonly externalToolRequired?: number;
+  readonly contractKinds: readonly string[];
+  readonly artifactKinds: readonly string[];
+  readonly byStatus: Readonly<Record<string, number>>;
+  readonly byReadinessStatus?: Readonly<Record<string, number>>;
+  readonly byContractKind: Readonly<Record<string, number>>;
+  readonly byArtifactKind: Readonly<Record<string, number>>;
+  readonly empty: boolean;
+}
+
+export interface SemanticImportSidecarParadigmSemanticsSummary {
+  readonly total: number;
+  readonly ids: readonly string[];
+  readonly groups: readonly string[];
+  readonly kinds: readonly string[];
+  readonly evidence: number;
+  readonly bindingScopes: number;
+  readonly bindings: number;
+  readonly patterns: number;
+  readonly typeConstraints: number;
+  readonly evaluationModels: number;
+  readonly memoryLocations: number;
+  readonly effectRegions: number;
+  readonly controlRegions: number;
+  readonly logicPrograms: number;
+  readonly actorSystems: number;
+  readonly stackEffects: number;
+  readonly arrayShapes: number;
+  readonly numericKernels: number;
+  readonly dataflowNetworks: number;
+  readonly clockModels: number;
+  readonly objectModels: number;
+  readonly macroExpansions: number;
+  readonly reflectionBoundaries: number;
+  readonly loweringRecords: number;
+  readonly byGroup: Readonly<Record<string, number>>;
+  readonly byKind: Readonly<Record<string, number>>;
+  readonly hasRuntimeSemantics: boolean;
+  readonly hasLogicSemantics: boolean;
+  readonly hasStackSemantics: boolean;
+  readonly hasArraySemantics: boolean;
+  readonly hasMacroOrReflection: boolean;
+  readonly hasLowering: boolean;
+  readonly empty: boolean;
+}
+
+export interface SemanticImportSidecar {
+  readonly kind: 'frontier.lang.semanticImportSidecar';
+  readonly version: 1;
+  readonly id: string;
+  readonly generatedAt: number;
+  readonly language?: FrontierSourceLanguage | 'mixed' | string;
+  readonly projectRoot?: string;
+  readonly imports: readonly SemanticImportSidecarImportEntry[];
+  readonly symbols: readonly SemanticImportSidecarSymbol[];
+  readonly ownershipRegions: readonly SemanticImportOwnershipRegion[];
+  readonly sourceMaps: {
+    readonly total: number;
+    readonly mappings: number;
+    readonly ids: readonly string[];
+  };
+  readonly sourcePreservation: {
+    readonly total: number;
+    readonly ids: readonly string[];
+    readonly byLevel: Readonly<Record<string, number>>;
+    readonly exact: number;
+    readonly declaration: number;
+    readonly estimated: number;
+    readonly blocked: number;
+    readonly sourcePaths: readonly string[];
+    readonly sourceMapIds: readonly string[];
+    readonly sourceMapMappingIds: readonly string[];
+    readonly records: readonly SemanticImportSidecarSourcePreservationRecord[];
+  };
+  readonly universalAstLayers: SemanticImportSidecarUniversalAstLayerSummary;
+  readonly proofSpec: SemanticImportSidecarProofSpecSummary;
+  readonly paradigmSemantics: SemanticImportSidecarParadigmSemanticsSummary;
+  readonly patchHints: readonly SemanticImportPatchHint[];
+  readonly quality: SemanticImportSidecarQuality;
+  readonly admission: SemanticImportSidecarAdmission;
+  readonly mergeCandidates: readonly {
+    readonly id?: string;
+    readonly readiness?: SemanticMergeReadiness;
+    readonly reasons: readonly string[];
+    readonly conflictClasses?: readonly SemanticMergeConflictClass[];
+    readonly conflictSummary?: SemanticMergeConflictSummary;
+    readonly risk?: string;
+    readonly operationCount: number;
+  }[];
+  readonly losses: {
+    readonly total: number;
+    readonly byKind: Readonly<Record<string, number>>;
+    readonly bySeverity: Readonly<Record<string, number>>;
+    readonly categories: readonly NativeImportTaxonomyKind[];
+    readonly blockingLossIds: readonly string[];
+    readonly reviewLossIds: readonly string[];
+  };
+  readonly regionTaxonomy: SemanticImportRegionTaxonomySummary;
+  readonly evidence: {
+    readonly total: number;
+    readonly failed: readonly string[];
+    readonly ids: readonly string[];
+  };
+  readonly summary: {
+    readonly imports: number;
+    readonly symbols: number;
+    readonly ownershipRegions: number;
+    readonly regionKinds: number;
+    readonly sourceMapMappings: number;
+    readonly sourcePreservationRecords: number;
+    readonly universalAstLayers: number;
+    readonly universalAstLayerNames: readonly string[];
+    readonly proofSpecRecords: number;
+    readonly proofSpecObligations: number;
+    readonly proofSpecFailedObligations: number;
+    readonly paradigmSemanticsRecords: number;
+    readonly paradigmSemanticsGroups: number;
+    readonly paradigmSemanticsLoweringRecords: number;
+    readonly patchHints: number;
+    readonly evidenceWarnings: number;
+    readonly readiness: SemanticMergeReadiness;
+    readonly emptySemanticIndex: boolean;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface SemanticImportSidecarOptions {
+  readonly id?: string;
+  readonly generatedAt?: number;
+  readonly regionPrefix?: string;
+  readonly targetPath?: string;
+  readonly metadata?: Record<string, unknown>;
+}

package/dist/semantic-import-source-preservation.js

@@ -0,0 +1,198 @@
+import { createSourcePreservationRecord, explainSourcePreservation } from '@shapeshift-labs/frontier-lang-kernel';
+import { countBy, idFragment, uniqueRecordsById, uniqueStrings } from './native-import-utils.js';
+
+function createKernelSourcePreservationRecords(input) {
+  const records = [];
+  if (input.sourcePreservation) {
+    const exactSource = input.sourcePreservation.summary?.exactSourceAvailable === true &&
+      (!input.sourceHash || input.sourcePreservation.sourceHash === input.sourceHash);
+    const hashMismatch = input.sourceHash &&
+      input.sourcePreservation.sourceHash &&
+      input.sourcePreservation.sourceHash !== input.sourceHash;
+    records.push(createSourcePreservationRecord({
+      id: `source_preservation_${idFragment(input.idPart ?? input.sourcePath ?? input.language)}_file`,
+      level: hashMismatch ? 'blocked' : exactSource ? 'exact' : 'estimated',
+      precision: exactSource ? 'exact' : 'estimated',
+      nativeSourceId: input.nativeSource?.id,
+      nativeAstNodeId: input.nativeAst?.rootId,
+      sourceSpan: {
+        sourceId: input.sourceHash,
+        path: input.sourcePath,
+        startLine: 1,
+        startColumn: 1
+      },
+      lossIds: (input.losses ?? []).filter((loss) => loss.kind === 'sourcePreservation' || loss.sourceMapId).map((loss) => loss.id),
+      evidenceIds: (input.evidence ?? []).map((record) => record.id).filter(Boolean),
+      losses: input.losses ?? [],
+      evidence: input.evidence ?? [],
+      reasons: hashMismatch
+        ? [`Preserved source hash ${input.sourcePreservation.sourceHash} does not match import hash ${input.sourceHash}.`]
+        : exactSource
+          ? ['Exact native source text is preserved for source-level replay and semantic merge review.']
+          : ['Native source preservation metadata exists, but exact source text is unavailable or unverified.'],
+      metadata: {
+        compilerRecord: 'nativeSourcePreservation',
+        nativeSourcePreservationId: input.sourcePreservation.id,
+        sourceBytes: input.sourcePreservation.sourceBytes,
+        lineCount: input.sourcePreservation.lineCount,
+        tokens: input.sourcePreservation.summary?.tokens ?? 0,
+        trivia: input.sourcePreservation.summary?.trivia ?? 0,
+        directives: input.sourcePreservation.summary?.directives ?? 0,
+        comments: input.sourcePreservation.summary?.comments ?? 0,
+        whitespace: input.sourcePreservation.summary?.whitespace ?? 0,
+        truncated: input.sourcePreservation.summary?.truncated === true
+      }
+    }));
+  }
+
+  for (const sourceMap of input.sourceMaps ?? []) {
+    for (const mapping of sourceMap.mappings ?? []) {
+      records.push(explainSourcePreservation({
+        id: `source_preservation_${idFragment(sourceMap.id)}_${idFragment(mapping.id)}`,
+        sourceMap,
+        mapping,
+        level: mapping.preservation,
+        losses: input.losses ?? [],
+        evidence: uniqueRecordsById([...(input.evidence ?? []), ...(sourceMap.evidence ?? [])]),
+        metadata: {
+          compilerRecord: 'sourceMapMapping',
+          language: input.language,
+          semanticIndexId: input.semanticIndex?.id,
+          sourceMapId: sourceMap.id,
+          sourceMapMappingId: mapping.id
+        }
+      }));
+    }
+  }
+
+  return uniqueRecordsById(records);
+}
+
+function summarizeKernelSourcePreservationRecords(records) {
+  const compactRecords = records.map(compactKernelSourcePreservationRecord);
+  const byLevel = countBy(compactRecords.map((record) => record.level ?? 'unknown'));
+  return {
+    total: compactRecords.length,
+    ids: compactRecords.map((record) => record.id).filter(Boolean),
+    byLevel,
+    exact: byLevel.exact ?? 0,
+    declaration: byLevel.declaration ?? 0,
+    estimated: byLevel.estimated ?? 0,
+    blocked: byLevel.blocked ?? 0,
+    sourcePaths: uniqueStrings(compactRecords.map((record) => record.sourcePath).filter(Boolean)),
+    sourceMapIds: uniqueStrings(compactRecords.map((record) => record.sourceMapId).filter(Boolean)),
+    sourceMapMappingIds: uniqueStrings(compactRecords.map((record) => record.sourceMapMappingId).filter(Boolean)),
+    records: compactRecords
+  };
+}
+
+function collectKernelSourcePreservationFromImport(imported) {
+  return uniqueRecordsById([
+    ...(imported?.metadata?.kernelSourcePreservationRecords ?? []),
+    ...(imported?.metadata?.sourcePreservationRecords ?? []),
+    ...(imported?.universalAst?.metadata?.kernelSourcePreservationRecords ?? []),
+    ...(imported?.universalAst?.metadata?.sourcePreservationRecords ?? [])
+  ].filter((record) => record?.kind === 'frontier.lang.sourcePreservation'));
+}
+
+function summarizeKernelSourcePreservation(importResult, imports) {
+  return summarizeKernelSourcePreservationRecords(uniqueRecordsById([
+    ...collectKernelSourcePreservationFromImport(importResult),
+    ...imports.flatMap((imported) => collectKernelSourcePreservationFromImport(imported))
+  ]));
+}
+
+function compactKernelSourcePreservationRecord(record) {
+  return {
+    id: record.id,
+    level: record.level,
+    precision: record.precision,
+    sourceMapId: record.sourceMapId,
+    sourceMapMappingId: record.sourceMapMappingId,
+    semanticNodeId: record.semanticNodeId,
+    nativeSourceId: record.nativeSourceId,
+    nativeAstNodeId: record.nativeAstNodeId,
+    semanticSymbolId: record.semanticSymbolId,
+    semanticOccurrenceId: record.semanticOccurrenceId,
+    sourcePath: record.sourceSpan?.path,
+    generatedPath: record.generatedSpan?.path ?? record.generatedSpan?.targetPath,
+    lossIds: record.lossIds ?? [],
+    evidenceIds: record.evidenceIds ?? [],
+    reasons: record.reasons ?? []
+  };
+}
+
+function summarizeImportSourcePreservation(importResult, imports) {
+  const records = uniqueSourcePreservationRecords([
+    ...collectSourcePreservationFromImport(importResult),
+    ...imports.flatMap((imported) => collectSourcePreservationFromImport(imported))
+  ]);
+  const compactRecords = records.map(compactSourcePreservationRecord);
+  return {
+    total: compactRecords.length,
+    ids: compactRecords.map((record) => record.id).filter(Boolean),
+    sourcePaths: uniqueStrings(compactRecords.map((record) => record.sourcePath).filter(Boolean)),
+    sourceHashes: uniqueStrings(compactRecords.map((record) => record.sourceHash).filter(Boolean)),
+    exactSourceAvailable: compactRecords.filter((record) => record.exactSourceAvailable).length,
+    sourceBytes: compactRecords.reduce((sum, record) => sum + (record.sourceBytes ?? 0), 0),
+    lineCount: compactRecords.reduce((sum, record) => sum + (record.lineCount ?? 0), 0),
+    tokens: compactRecords.reduce((sum, record) => sum + (record.tokens ?? 0), 0),
+    trivia: compactRecords.reduce((sum, record) => sum + (record.trivia ?? 0), 0),
+    directives: compactRecords.reduce((sum, record) => sum + (record.directives ?? 0), 0),
+    comments: compactRecords.reduce((sum, record) => sum + (record.comments ?? 0), 0),
+    whitespace: compactRecords.reduce((sum, record) => sum + (record.whitespace ?? 0), 0),
+    truncated: compactRecords.some((record) => record.truncated),
+    records: compactRecords
+  };
+}
+
+function collectSourcePreservationFromImport(imported) {
+  const nativeAst = imported?.nativeAst ?? imported?.nativeSource?.ast;
+  return [
+    imported?.metadata?.sourcePreservation,
+    imported?.nativeSource?.metadata?.sourcePreservation,
+    nativeAst?.metadata?.sourcePreservation,
+    imported?.universalAst?.metadata?.sourcePreservation,
+    ...(imported?.nativeSources ?? []).map((nativeSource) => nativeSource?.metadata?.sourcePreservation ?? nativeSource?.ast?.metadata?.sourcePreservation)
+  ].filter(Boolean);
+}
+
+function uniqueSourcePreservationRecords(records) {
+  const seen = new Set();
+  const result = [];
+  for (const record of records) {
+    const key = record.id ?? `${record.sourcePath ?? 'source'}#${record.sourceHash ?? result.length}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(record);
+  }
+  return result;
+}
+
+function compactSourcePreservationRecord(record) {
+  return {
+    id: record.id,
+    language: record.language,
+    sourcePath: record.sourcePath,
+    sourceHash: record.sourceHash,
+    sourceBytes: record.sourceBytes,
+    lineCount: record.lineCount,
+    newline: record.newline,
+    encoding: record.encoding,
+    exactSourceAvailable: record.summary?.exactSourceAvailable === true,
+    tokens: record.summary?.tokens ?? record.tokens?.length ?? 0,
+    trivia: record.summary?.trivia ?? record.trivia?.length ?? 0,
+    directives: record.summary?.directives ?? record.directives?.length ?? 0,
+    comments: record.summary?.comments ?? 0,
+    whitespace: record.summary?.whitespace ?? 0,
+    truncated: record.summary?.truncated === true
+  };
+}
+
+export {
+  collectKernelSourcePreservationFromImport,
+  createKernelSourcePreservationRecords,
+  summarizeImportSourcePreservation,
+  summarizeKernelSourcePreservation,
+  summarizeKernelSourcePreservationRecords
+};