@shapeshift-labs/frontier-lang-compiler 0.2.99 → 0.2.101

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

@@ -8,6 +8,16 @@ export interface SemanticImportSidecarQualityWarning {
   readonly sourcePaths: readonly string[];
 }
 
+export type SemanticImportSidecarRecordClassification = 'useful' | 'expected-empty' | 'unexpectedly-empty' | 'missing' | string;
+
+export interface SemanticImportSidecarQualityRecord {
+  readonly classification: SemanticImportSidecarRecordClassification;
+  readonly reasonCode: string;
+  readonly message: string;
+  readonly action: string;
+  readonly sourcePaths: readonly string[];
+}
+
 export interface SemanticImportSidecarProofAdmissionSummary {
   readonly total: number;
   readonly obligations: number;
@@ -26,12 +36,14 @@ export interface SemanticImportSidecarProofAdmissionSummary {
 export interface SemanticImportSidecarQuality {
   readonly schema: 'frontier.lang.semanticSidecarQuality.v1';
   readonly expected: boolean;
+  readonly expectedEmpty: boolean;
   readonly expectedSatisfied: boolean;
   readonly expectedMissingReasonCodes: readonly string[];
   readonly selected: boolean;
   readonly eligible: boolean;
   readonly imported: boolean;
   readonly importCount: number;
+  readonly record: SemanticImportSidecarQualityRecord;
   readonly symbolCount: number;
   readonly ownershipRegionCount: number;
   readonly patchHintCount: number;
@@ -45,6 +57,7 @@ export interface SemanticImportSidecarQuality {
 export interface SemanticImportSidecarAdmission {
   readonly schema: 'frontier.lang.semanticSidecarAdmission.v1';
   readonly expected: boolean;
+  readonly expectedEmpty: boolean;
   readonly expectedSatisfied: boolean;
   readonly expectedMissingReasonCodes: readonly string[];
   readonly selected: boolean;
@@ -53,6 +66,7 @@ export interface SemanticImportSidecarAdmission {
   readonly importCount: number;
   readonly readiness: SemanticMergeReadiness;
   readonly action: string;
+  readonly record: SemanticImportSidecarQualityRecord;
   readonly counts: {
     readonly symbols: number;
     readonly ownershipRegions: number;

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

@@ -1,6 +1,6 @@
 import { uniqueRecordsById, uniqueStrings } from './native-import-utils.js';
 import { summarizeSemanticImportDependencyRelations } from './semantic-import-dependencies.js';
-import { semanticOwnershipRegionForSymbol, summarizeSemanticImportRegionTaxonomy } from './semantic-import-regions.js';
+import { semanticOwnershipRegionForSymbol, semanticPatchHintForRegion, summarizeSemanticImportRegionTaxonomy } from './semantic-import-regions.js';
 import { collectKernelSourcePreservationFromImport } from './semantic-import-source-preservation.js';
 import {
   summarizeParadigmSemanticsLayer,
@@ -10,10 +10,12 @@ import {
 
 function semanticImportSidecarEntry(imported, index, options) {
   const semanticIndex = imported?.semanticIndex ?? imported?.universalAst?.semanticIndex;
+  const semanticSymbols = semanticSymbolsForImport(imported, semanticIndex);
   const nativeAst = imported?.nativeAst ?? imported?.nativeSource?.ast;
   const semanticFacts = semanticIndex?.facts ?? [];
   const sourceMaps = imported?.sourceMaps ?? imported?.universalAst?.sourceMaps ?? [];
   const sourceMapMappings = sourceMaps.flatMap((sourceMap) => sourceMap?.mappings ?? []);
+  const importedOwnershipRegions = semanticOwnershipRegionsForImport(imported);
   const sourcePreservationRecords = collectKernelSourcePreservationFromImport(imported);
   const universalAstLayers = summarizeUniversalAstLayers(imported?.universalAst);
   const proofSpec = summarizeProofSpecLayer(imported?.universalAst?.proof ?? imported?.proof);
@@ -29,10 +31,14 @@ function semanticImportSidecarEntry(imported, index, options) {
   }
   const symbols = [];
   const regions = [];
-  for (const symbol of semanticIndex?.symbols ?? []) {
+  for (const symbol of semanticSymbols) {
     const mapping = mappingsBySymbolId.get(symbol.id);
     const nativeNode = symbol.nativeAstNodeId ? nativeAst?.nodes?.[symbol.nativeAstNodeId] : undefined;
-    const region = semanticOwnershipRegionForSymbol(imported, symbol, mapping, nativeNode, options);
+    const generatedRegion = semanticOwnershipRegionForSymbol(imported, symbol, mapping, nativeNode, options);
+    const region = mergeSemanticOwnershipRegion(
+      generatedRegion,
+      semanticOwnershipRegionForImportedSymbol(importedOwnershipRegions, symbol, generatedRegion)
+    );
     regions.push(region);
     symbols.push({
       id: symbol.id,
@@ -42,7 +48,7 @@ function semanticImportSidecarEntry(imported, index, options) {
       nativeAstNodeId: symbol.nativeAstNodeId,
       semanticOccurrenceId: mapping?.semanticOccurrenceId,
       sourceMapMappingId: mapping?.id,
-      sourceSpan: mapping?.sourceSpan ?? symbol.definitionSpan ?? nativeNode?.span,
+      sourceSpan: region.sourceSpan ?? mapping?.sourceSpan ?? symbol.definitionSpan ?? nativeNode?.span,
       signatureHash: symbol.signatureHash,
       ownershipRegionId: region.id,
       ownershipKey: region.key,
@@ -50,13 +56,25 @@ function semanticImportSidecarEntry(imported, index, options) {
       readiness
     });
   }
+  for (const [regionIndex, region] of importedOwnershipRegions.entries()) {
+    regions.push(normalizeImportedOwnershipRegion(imported, region, regionIndex, options));
+  }
   const ownershipRegions = uniqueRecordsById(regions);
   const regionTaxonomy = summarizeSemanticImportRegionTaxonomy(ownershipRegions);
+  const patchHints = ownershipRegions.map((region) => semanticPatchHintForRegion(region, readiness, options));
+  const sourcePath = imported?.sourcePath ?? imported?.nativeSource?.sourcePath ?? nativeAst?.sourcePath;
+  const qualityRecord = semanticImportSidecarQualityRecord({
+    expected: options.expected === true || options.semanticImportExpected === true,
+    expectedEmpty: options.expectedEmpty === true || options.semanticImportExpectedEmpty === true,
+    importCount: 1,
+    symbolCount: symbols.length,
+    sourcePaths: [sourcePath]
+  });
   return {
     id: imported?.id ?? `import_${index + 1}`,
     language: imported?.language,
-    sourcePath: imported?.sourcePath ?? imported?.nativeSource?.sourcePath ?? nativeAst?.sourcePath,
-    sourceHash: imported?.nativeSource?.sourceHash ?? nativeAst?.sourceHash,
+    sourcePath,
+    sourceHash: imported?.nativeSource?.sourceHash ?? nativeAst?.sourceHash ?? imported?.sourceHash,
     parser: imported?.nativeAst?.parser ?? nativeAst?.parser,
     nativeSourceId: imported?.nativeSource?.id,
     nativeAstId: nativeAst?.id,
@@ -77,14 +95,140 @@ function semanticImportSidecarEntry(imported, index, options) {
     semanticFactCount: semanticFacts.length,
     semanticFactPredicates: factSummary.predicates,
     semanticFactSummary: factSummary.byPredicate,
+    patchHintCount: patchHints.length,
+    patchHintOperations: uniqueStrings(patchHints.map((hint) => hint.operation).filter(Boolean)),
+    patchHints,
     readiness,
     emptySemanticIndex: symbols.length === 0,
+    qualityRecord,
     regionTaxonomy,
     symbols,
     ownershipRegions
   };
 }
 
+function semanticImportSidecarQualityRecord(input = {}) {
+  const expected = input.expected === true;
+  const expectedEmpty = input.expectedEmpty === true || input.semanticImportExpectedEmpty === true;
+  const importCount = Number(input.importCount ?? 0);
+  const symbolCount = Number(input.symbolCount ?? 0);
+  const sourcePaths = uniqueStrings(input.sourcePaths ?? []);
+  if (importCount === 0) {
+    return {
+      classification: 'missing',
+      reasonCode: expected || expectedEmpty ? 'expected-semantic-import-missing' : 'missing-imports',
+      message: 'Semantic import produced no selected import records.',
+      action: 'check-semantic-import-include-globs-and-workspace-paths',
+      sourcePaths
+    };
+  }
+  if (symbolCount === 0 && expectedEmpty) {
+    return {
+      classification: 'expected-empty',
+      reasonCode: 'semantic-import-expected-empty',
+      message: 'Semantic import was expected to produce no semantic symbols for this source set.',
+      action: 'skip-expected-empty',
+      sourcePaths
+    };
+  }
+  if (symbolCount === 0) {
+    return {
+      classification: 'unexpectedly-empty',
+      reasonCode: expected ? 'expected-semantic-import-empty' : 'empty-semantic-index',
+      message: 'Semantic import selected sources but produced zero semantic symbols.',
+      action: 'rerun-importer-with-semantic-source-selection',
+      sourcePaths
+    };
+  }
+  return {
+    classification: 'useful',
+    reasonCode: 'semantic-import-useful',
+    message: 'Semantic import produced semantic symbols for merge review.',
+    action: 'use-semantic-import-evidence',
+    sourcePaths
+  };
+}
+
+function semanticSymbolsForImport(imported, semanticIndex) {
+  if (Array.isArray(semanticIndex?.symbols)) return semanticIndex.symbols;
+  for (const symbols of [
+    imported?.semanticSymbols,
+    imported?.symbols,
+    imported?.metadata?.semanticSymbols,
+    imported?.metadata?.symbols
+  ]) {
+    if (Array.isArray(symbols)) return symbols;
+  }
+  return [];
+}
+
+function semanticOwnershipRegionsForImport(imported) {
+  return [
+    ...(Array.isArray(imported?.ownershipRegions) ? imported.ownershipRegions : []),
+    ...(Array.isArray(imported?.semanticOwnershipRegions) ? imported.semanticOwnershipRegions : []),
+    ...(Array.isArray(imported?.semanticIndex?.ownershipRegions) ? imported.semanticIndex.ownershipRegions : []),
+    ...(Array.isArray(imported?.universalAst?.ownershipRegions) ? imported.universalAst.ownershipRegions : []),
+    ...(Array.isArray(imported?.metadata?.ownershipRegions) ? imported.metadata.ownershipRegions : [])
+  ].filter((region) => region && typeof region === 'object');
+}
+
+function semanticOwnershipRegionForImportedSymbol(regions, symbol, generatedRegion) {
+  const metadata = symbol?.metadata ?? {};
+  return regions.find((region) => metadata.ownershipRegionId && region.id === metadata.ownershipRegionId)
+    ?? regions.find((region) => metadata.ownershipRegionKey && region.key === metadata.ownershipRegionKey)
+    ?? regions.find((region) => generatedRegion.id && region.id === generatedRegion.id)
+    ?? regions.find((region) => generatedRegion.key && region.key === generatedRegion.key)
+    ?? regions.find((region) => symbol.id && region.symbolId === symbol.id)
+    ?? regions.find((region) => symbol.name && region.symbolName === symbol.name && region.sourcePath === generatedRegion.sourcePath);
+}
+
+function normalizeImportedOwnershipRegion(imported, region, index, options) {
+  const symbol = {
+    id: region.symbolId ?? region.id ?? region.key ?? `ownership_region_${index + 1}`,
+    name: region.symbolName ?? region.name ?? region.key ?? region.id,
+    kind: region.symbolKind,
+    language: region.language ?? imported?.language,
+    nativeAstNodeId: region.nativeAstNodeId,
+    definitionSpan: region.sourceSpan,
+    metadata: {
+      ownershipRegionId: region.id,
+      ownershipRegionKey: region.key,
+      ownershipRegionKind: region.regionKind
+    }
+  };
+  return mergeSemanticOwnershipRegion(
+    semanticOwnershipRegionForSymbol(imported, symbol, undefined, undefined, options),
+    region
+  );
+}
+
+function mergeSemanticOwnershipRegion(generatedRegion, importedRegion) {
+  if (!importedRegion) return generatedRegion;
+  return {
+    ...generatedRegion,
+    ...importedRegion,
+    id: importedRegion.id ?? generatedRegion.id,
+    key: importedRegion.key ?? generatedRegion.key,
+    regionKind: importedRegion.regionKind ?? generatedRegion.regionKind,
+    granularity: importedRegion.granularity ?? generatedRegion.granularity,
+    language: importedRegion.language ?? generatedRegion.language,
+    sourcePath: importedRegion.sourcePath ?? generatedRegion.sourcePath,
+    sourceHash: importedRegion.sourceHash ?? generatedRegion.sourceHash,
+    symbolId: importedRegion.symbolId ?? generatedRegion.symbolId,
+    symbolName: importedRegion.symbolName ?? generatedRegion.symbolName,
+    symbolKind: importedRegion.symbolKind ?? generatedRegion.symbolKind,
+    nativeAstNodeId: importedRegion.nativeAstNodeId ?? generatedRegion.nativeAstNodeId,
+    sourceSpan: importedRegion.sourceSpan ?? generatedRegion.sourceSpan,
+    precision: importedRegion.precision ?? generatedRegion.precision,
+    mergePolicy: importedRegion.mergePolicy ?? generatedRegion.mergePolicy,
+    metadata: {
+      ...generatedRegion.metadata,
+      ...importedRegion.metadata,
+      semanticRegionTaxonomy: true
+    }
+  };
+}
+
 function semanticImportEntryReadiness(imported) {
   const readiness = imported?.metadata?.semanticMergeReadiness
     ?? imported?.metadata?.nativeImportLossSummary?.semanticMergeReadiness
@@ -105,4 +249,4 @@ function summarizeSemanticFacts(facts) {
   return { byPredicate, predicates: Object.keys(byPredicate).sort() };
 }
 
-export { semanticImportSidecarEntry };
+export { semanticImportSidecarEntry, semanticImportSidecarQualityRecord };

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

@@ -7,9 +7,8 @@ import type {
 } from '@shapeshift-labs/frontier-lang-kernel';
 import type { NativeImportRegionTaxonomyKind, NativeImportTaxonomyKind } from './index.js';
 import type { SemanticImportImpactSummary } from './semantic-import-impact-types.js';
-import type { SemanticImportSidecarAdmission, SemanticImportSidecarQuality } from './semantic-import-sidecar-admission-types.js';
+import type { SemanticImportSidecarAdmission, SemanticImportSidecarQuality, SemanticImportSidecarQualityRecord } 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;
@@ -28,7 +27,6 @@ export interface SemanticImportOwnershipRegion {
   readonly mergePolicy?: string;
   readonly metadata?: Record<string, unknown>;
 }
-
 export interface SemanticImportSidecarSymbol {
   readonly id: string;
   readonly name?: string;
@@ -44,7 +42,6 @@ export interface SemanticImportSidecarSymbol {
   readonly ownershipRegionKind?: NativeImportRegionTaxonomyKind;
   readonly readiness: SemanticMergeReadiness;
 }
-
 export interface SemanticImportRegionTaxonomySummary {
   readonly kinds: readonly NativeImportRegionTaxonomyKind[];
   readonly presentKinds: readonly NativeImportRegionTaxonomyKind[];
@@ -52,12 +49,12 @@ export interface SemanticImportRegionTaxonomySummary {
   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 operation: string;
   readonly sourcePath?: string;
   readonly sourceHash?: string;
   readonly sourceSpan?: SourceSpan;
@@ -70,7 +67,6 @@ export interface SemanticImportPatchHint {
     readonly requiresSourceMap: boolean;
   };
 }
-
 export interface SemanticImportSidecarImportEntry {
   readonly id: string;
   readonly language?: FrontierSourceLanguage | string;
@@ -93,11 +89,17 @@ export interface SemanticImportSidecarImportEntry {
   readonly paradigmSemantics: SemanticImportSidecarParadigmSemanticsSummary;
   readonly dependencyRelationCount: number;
   readonly dependencyPredicates: readonly string[];
+  readonly semanticFactCount?: number;
+  readonly semanticFactPredicates?: readonly string[];
+  readonly semanticFactSummary?: Readonly<Record<string, number>>;
+  readonly patchHintCount?: number;
+  readonly patchHintOperations?: readonly string[];
+  readonly patchHints?: readonly SemanticImportPatchHint[];
   readonly readiness: SemanticMergeReadiness;
   readonly emptySemanticIndex: boolean;
+  readonly qualityRecord: SemanticImportSidecarQualityRecord;
   readonly regionTaxonomy?: SemanticImportRegionTaxonomySummary;
 }
-
 export interface SemanticImportSidecarSourcePreservationRecord {
   readonly id: string;
   readonly level: SourcePreservationLevel;
@@ -115,7 +117,6 @@ export interface SemanticImportSidecarSourcePreservationRecord {
   readonly evidenceIds: readonly string[];
   readonly reasons: readonly string[];
 }
-
 export interface SemanticImportSidecarUniversalAstLayerSummary {
   readonly total: number;
   readonly names: readonly string[];
@@ -123,7 +124,6 @@ export interface SemanticImportSidecarUniversalAstLayerSummary {
   readonly byName: Readonly<Record<string, number>>;
   readonly empty: boolean;
 }
-
 export interface SemanticImportSidecarProofSpecSummary {
   readonly total: number;
   readonly ids: readonly string[];
@@ -152,7 +152,6 @@ export interface SemanticImportSidecarProofSpecSummary {
   readonly byArtifactKind: Readonly<Record<string, number>>;
   readonly empty: boolean;
 }
-
 export interface SemanticImportSidecarParadigmSemanticsSummary {
   readonly total: number;
   readonly ids: readonly string[];
@@ -188,7 +187,6 @@ export interface SemanticImportSidecarParadigmSemanticsSummary {
   readonly hasLowering: boolean;
   readonly empty: boolean;
 }
-
 export interface SemanticImportDependencySummary {
   readonly total: number;
   readonly calls: number;
@@ -205,7 +203,6 @@ export interface SemanticImportDependencySummary {
   readonly sourceSymbolIds: readonly string[];
   readonly targetSymbolIds: readonly string[];
 }
-
 export interface SemanticImportSidecar {
   readonly kind: 'frontier.lang.semanticImportSidecar';
   readonly version: 1;
@@ -287,12 +284,18 @@ export interface SemanticImportSidecar {
     readonly semanticImpactRequiredVerificationSteps: number;
     readonly patchHints: number;
     readonly evidenceWarnings: number;
+    readonly semanticImportExpected: boolean;
+    readonly semanticImportExpectedEmpty: boolean;
+    readonly semanticImportExpectedSatisfied: boolean;
+    readonly semanticImportExpectedMissingReasonCodes: readonly string[];
+    readonly semanticImportRecordClassification: string;
+    readonly semanticImportRecordReasonCode: string;
+    readonly semanticImportRecordAction: string;
     readonly readiness: SemanticMergeReadiness;
     readonly emptySemanticIndex: boolean;
   };
   readonly metadata?: Record<string, unknown>;
 }
-
 export interface SemanticImportSidecarOptions {
   readonly id?: string;
   readonly generatedAt?: number;
@@ -300,5 +303,7 @@ export interface SemanticImportSidecarOptions {
   readonly targetPath?: string;
   readonly expected?: boolean;
   readonly semanticImportExpected?: boolean;
+  readonly expectedEmpty?: boolean;
+  readonly semanticImportExpectedEmpty?: boolean;
   readonly metadata?: Record<string, unknown>;
 }

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

@@ -0,0 +1,55 @@
+import { uniqueStrings } from './native-import-utils.js';
+
+export function sourcePreservationInspectionTags(input) {
+  return uniqueStrings([
+    input.compilerRecord,
+    input.level,
+    input.precision,
+    input.exactSource ? 'exact-source-text' : undefined,
+    input.sourceMapOrigin,
+    input.generatedPath ? 'generated-span' : undefined,
+    input.semanticSymbolId ? 'semantic-symbol' : undefined,
+    input.ownershipRegionKind ? `region:${input.ownershipRegionKind}` : undefined
+  ]);
+}
+
+export function sourcePreservationQueryKeys(input) {
+  return uniqueStrings([
+    input.compilerRecord ? `compiler-record:${input.compilerRecord}` : undefined,
+    input.level ? `level:${input.level}` : undefined,
+    input.precision ? `precision:${input.precision}` : undefined,
+    input.sourcePath ? `source:${input.sourcePath}` : undefined,
+    input.generatedPath ? `generated:${input.generatedPath}` : undefined,
+    input.sourceMapOrigin ? `source-map-origin:${input.sourceMapOrigin}` : undefined,
+    input.ownershipRegionKind ? `region-kind:${input.ownershipRegionKind}` : undefined
+  ]);
+}
+
+export function compactSpan(span) {
+  if (!span) return undefined;
+  return {
+    sourceId: span.sourceId,
+    path: span.path,
+    targetPath: span.targetPath,
+    targetHash: span.targetHash,
+    start: span.start,
+    end: span.end,
+    startLine: span.startLine,
+    startColumn: span.startColumn,
+    endLine: span.endLine,
+    endColumn: span.endColumn,
+    generatedName: span.generatedName
+  };
+}
+
+export function sumCountObjects(objects) {
+  const result = {};
+  for (const object of objects ?? []) {
+    for (const [key, value] of Object.entries(object ?? {})) {
+      const count = Number(value);
+      if (!Number.isFinite(count)) continue;
+      result[key] = (result[key] ?? 0) + count;
+    }
+  }
+  return result;
+}

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

@@ -1,5 +1,6 @@
 import { createSourcePreservationRecord, explainSourcePreservation } from '@shapeshift-labs/frontier-lang-kernel';
 import { countBy, idFragment, uniqueRecordsById, uniqueStrings } from './native-import-utils.js';
+import { compactSpan, sourcePreservationInspectionTags, sourcePreservationQueryKeys, sumCountObjects } from './semantic-import-source-preservation-utils.js';
 
 function createKernelSourcePreservationRecords(input) {
   const records = [];
@@ -40,7 +41,25 @@ function createKernelSourcePreservationRecords(input) {
         directives: input.sourcePreservation.summary?.directives ?? 0,
         comments: input.sourcePreservation.summary?.comments ?? 0,
         whitespace: input.sourcePreservation.summary?.whitespace ?? 0,
-        truncated: input.sourcePreservation.summary?.truncated === true
+        truncated: input.sourcePreservation.summary?.truncated === true,
+        triviaByKind: input.sourcePreservation.summary?.triviaByKind ?? countBy((input.sourcePreservation.trivia ?? []).map((entry) => entry.kind ?? 'unknown')),
+        directivesByKind: input.sourcePreservation.summary?.directivesByKind ?? countBy((input.sourcePreservation.directives ?? []).map((entry) => entry.kind ?? 'directive')),
+        directiveKinds: input.sourcePreservation.summary?.directiveKinds ?? uniqueStrings((input.sourcePreservation.directives ?? []).map((entry) => entry.kind ?? 'directive')),
+        commentSpanIds: input.sourcePreservation.summary?.commentSpanIds ?? (input.sourcePreservation.trivia ?? []).filter((entry) => entry.kind === 'comment').map((entry) => entry.id).filter(Boolean),
+        directiveSpanIds: input.sourcePreservation.summary?.directiveSpanIds ?? (input.sourcePreservation.directives ?? []).map((entry) => entry.id).filter(Boolean),
+        inspectionTags: sourcePreservationInspectionTags({
+          compilerRecord: 'nativeSourcePreservation',
+          level: hashMismatch ? 'blocked' : exactSource ? 'exact' : 'estimated',
+          precision: exactSource ? 'exact' : 'estimated',
+          sourcePath: input.sourcePath,
+          exactSource
+        }),
+        queryKeys: sourcePreservationQueryKeys({
+          compilerRecord: 'nativeSourcePreservation',
+          level: hashMismatch ? 'blocked' : exactSource ? 'exact' : 'estimated',
+          precision: exactSource ? 'exact' : 'estimated',
+          sourcePath: input.sourcePath
+        })
       }
     }));
   }
@@ -59,7 +78,8 @@ function createKernelSourcePreservationRecords(input) {
           language: input.language,
           semanticIndexId: input.semanticIndex?.id,
           sourceMapId: sourceMap.id,
-          sourceMapMappingId: mapping.id
+          sourceMapMappingId: mapping.id,
+          ...sourceMapMappingInspectionMetadata(input, sourceMap, mapping)
         }
       }));
     }
@@ -71,17 +91,31 @@ function createKernelSourcePreservationRecords(input) {
 function summarizeKernelSourcePreservationRecords(records) {
   const compactRecords = records.map(compactKernelSourcePreservationRecord);
   const byLevel = countBy(compactRecords.map((record) => record.level ?? 'unknown'));
+  const sourceMapRecords = compactRecords.filter((record) => record.compilerRecord === 'sourceMapMapping' || record.sourceMapMappingId);
   return {
     total: compactRecords.length,
     ids: compactRecords.map((record) => record.id).filter(Boolean),
     byLevel,
+    byPrecision: countBy(compactRecords.map((record) => record.precision ?? 'unknown')),
+    byCompilerRecord: countBy(compactRecords.map((record) => record.compilerRecord ?? 'unknown')),
+    bySourceMapOrigin: countBy(sourceMapRecords.map((record) => record.sourceMapOrigin ?? 'native-import')),
+    byOwnershipRegionKind: countBy(compactRecords.map((record) => record.ownershipRegionKind).filter(Boolean)),
     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)),
+    generatedPaths: uniqueStrings(compactRecords.map((record) => record.generatedPath).filter(Boolean)),
+    generatedNames: uniqueStrings(compactRecords.map((record) => record.generatedName).filter(Boolean)),
     sourceMapIds: uniqueStrings(compactRecords.map((record) => record.sourceMapId).filter(Boolean)),
     sourceMapMappingIds: uniqueStrings(compactRecords.map((record) => record.sourceMapMappingId).filter(Boolean)),
+    declarationMappingIds: uniqueStrings(sourceMapRecords.filter((record) => record.level === 'declaration' || record.precision === 'declaration').map((record) => record.sourceMapMappingId).filter(Boolean)),
+    generatedSpanMappingIds: uniqueStrings(sourceMapRecords.filter((record) => record.generatedRange || record.generatedPath).map((record) => record.sourceMapMappingId).filter(Boolean)),
+    semanticSymbolIds: uniqueStrings(compactRecords.map((record) => record.semanticSymbolId).filter(Boolean)),
+    semanticOccurrenceIds: uniqueStrings(compactRecords.map((record) => record.semanticOccurrenceId).filter(Boolean)),
+    nativeAstNodeIds: uniqueStrings(compactRecords.map((record) => record.nativeAstNodeId).filter(Boolean)),
+    ownershipRegionIds: uniqueStrings(compactRecords.map((record) => record.ownershipRegionId).filter(Boolean)),
+    queryKeys: uniqueStrings(compactRecords.flatMap((record) => record.queryKeys ?? [])),
     records: compactRecords
   };
 }
@@ -107,8 +141,11 @@ function compactKernelSourcePreservationRecord(record) {
     id: record.id,
     level: record.level,
     precision: record.precision,
+    compilerRecord: record.metadata?.compilerRecord,
+    preservation: record.metadata?.preservation ?? record.level,
     sourceMapId: record.sourceMapId,
     sourceMapMappingId: record.sourceMapMappingId,
+    sourceMapOrigin: record.metadata?.sourceMapOrigin,
     semanticNodeId: record.semanticNodeId,
     nativeSourceId: record.nativeSourceId,
     nativeAstNodeId: record.nativeAstNodeId,
@@ -116,9 +153,21 @@ function compactKernelSourcePreservationRecord(record) {
     semanticOccurrenceId: record.semanticOccurrenceId,
     sourcePath: record.sourceSpan?.path,
     generatedPath: record.generatedSpan?.path ?? record.generatedSpan?.targetPath,
+    generatedName: record.generatedSpan?.generatedName ?? record.metadata?.generatedName,
+    sourceRange: compactSpan(record.sourceSpan),
+    generatedRange: compactSpan(record.generatedSpan),
+    target: record.generatedSpan?.target?.language ?? record.generatedSpan?.target ?? record.metadata?.target,
+    targetPath: record.generatedSpan?.targetPath ?? record.metadata?.targetPath,
+    ownershipRegionId: record.metadata?.ownershipRegionId,
+    ownershipRegionKey: record.metadata?.ownershipRegionKey,
+    ownershipRegionKind: record.metadata?.ownershipRegionKind,
+    declarationKind: record.metadata?.declarationKind,
+    semanticKind: record.metadata?.semanticKind,
     lossIds: record.lossIds ?? [],
     evidenceIds: record.evidenceIds ?? [],
-    reasons: record.reasons ?? []
+    reasons: record.reasons ?? [],
+    inspectionTags: record.metadata?.inspectionTags ?? [],
+    queryKeys: record.metadata?.queryKeys ?? []
   };
 }
 
@@ -141,6 +190,11 @@ function summarizeImportSourcePreservation(importResult, imports) {
     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),
+    triviaByKind: sumCountObjects(compactRecords.map((record) => record.triviaByKind)),
+    directivesByKind: sumCountObjects(compactRecords.map((record) => record.directivesByKind)),
+    directiveKinds: uniqueStrings(compactRecords.flatMap((record) => record.directiveKinds ?? [])),
+    commentSpanIds: uniqueStrings(compactRecords.flatMap((record) => record.commentSpanIds ?? [])),
+    directiveSpanIds: uniqueStrings(compactRecords.flatMap((record) => record.directiveSpanIds ?? [])),
     truncated: compactRecords.some((record) => record.truncated),
     records: compactRecords
   };
@@ -185,10 +239,51 @@ function compactSourcePreservationRecord(record) {
     directives: record.summary?.directives ?? record.directives?.length ?? 0,
     comments: record.summary?.comments ?? 0,
     whitespace: record.summary?.whitespace ?? 0,
+    triviaByKind: record.summary?.triviaByKind ?? countBy((record.trivia ?? []).map((entry) => entry.kind ?? 'unknown')),
+    directivesByKind: record.summary?.directivesByKind ?? countBy((record.directives ?? []).map((entry) => entry.kind ?? 'directive')),
+    directiveKinds: record.summary?.directiveKinds ?? uniqueStrings((record.directives ?? []).map((entry) => entry.kind ?? 'directive')),
+    commentSpanIds: record.summary?.commentSpanIds ?? (record.trivia ?? []).filter((entry) => entry.kind === 'comment').map((entry) => entry.id).filter(Boolean),
+    directiveSpanIds: record.summary?.directiveSpanIds ?? (record.directives ?? []).map((entry) => entry.id).filter(Boolean),
     truncated: record.summary?.truncated === true
   };
 }
 
+function sourceMapMappingInspectionMetadata(input, sourceMap, mapping) {
+  const sourcePath = mapping.sourceSpan?.path ?? sourceMap.sourcePath ?? input.sourcePath;
+  const generatedPath = mapping.generatedSpan?.targetPath ?? mapping.generatedSpan?.path ?? sourceMap.targetPath;
+  const generatedName = mapping.generatedName ?? mapping.generatedSpan?.generatedName;
+  const origin = mapping.metadata?.sourceMapOrigin ?? (mapping.generatedSpan ? 'generated' : 'native-import');
+  const base = {
+    compilerRecord: 'sourceMapMapping',
+    level: mapping.preservation,
+    precision: mapping.precision,
+    sourcePath,
+    generatedPath,
+    sourceMapOrigin: origin,
+    ownershipRegionKind: mapping.ownershipRegionKind,
+    semanticSymbolId: mapping.semanticSymbolId
+  };
+  return {
+    preservation: mapping.preservation,
+    precision: mapping.precision,
+    sourceMapOrigin: origin,
+    sourcePath,
+    generatedPath,
+    targetPath: generatedPath,
+    generatedName,
+    sourceRange: compactSpan(mapping.sourceSpan),
+    generatedRange: compactSpan(mapping.generatedSpan),
+    target: mapping.target?.language ?? mapping.generatedSpan?.target?.language ?? mapping.target ?? mapping.generatedSpan?.target,
+    ownershipRegionId: mapping.ownershipRegionId,
+    ownershipRegionKey: mapping.ownershipRegionKey,
+    ownershipRegionKind: mapping.ownershipRegionKind,
+    declarationKind: mapping.metadata?.declarationKind,
+    semanticKind: mapping.metadata?.semanticKind,
+    inspectionTags: sourcePreservationInspectionTags(base),
+    queryKeys: sourcePreservationQueryKeys(base)
+  };
+}
+
 export {
   collectKernelSourcePreservationFromImport,
   createKernelSourcePreservationRecords,

package/package.json

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