@shapeshift-labs/frontier-lang-compiler 0.2.77 → 0.2.79

package/README.md

@@ -422,6 +422,22 @@ console.log(targetChange.metadata.semanticEquivalenceClaim); // false
 
 Bidirectional target-change records are merge-admission evidence, not transpiler proof. They keep target diffs, source anchor matches, optional lineage resolutions, source patch-bundle records, semantic history records, evidence IDs, readiness, and reason codes. They always keep `autoMergeClaim: false` and `semanticEquivalenceClaim: false`; unmatched or deleted anchors block the source-port route, while matched and ambiguous anchors still require human or verifier review.
 
+When the target source came from a Frontier/native projection, pass the generated-output `sourceMaps` back into `createBidirectionalTargetChangeRecord`. The record will match target changed regions by generated span or generated name, emit `sourceMapLinks`, include `sourceMapBackedMatches` in the summary/evidence, and carry source-map mapping IDs into the source patch bundle index:
+
+```js
+const sourceMapBacked = createBidirectionalTargetChangeRecord({
+  source,
+  targetLanguage: 'rust',
+  targetPath: 'src/counter.rs',
+  baseTarget,
+  editedTarget,
+  sourceMaps: [projection.sourceMap]
+});
+
+console.log(sourceMapBacked.summary.sourceMapBackedMatches);
+console.log(sourceMapBacked.sourcePatchBundle.index.sourceMapMappingIds);
+```
+
 Store worker outputs as compact semantic history records when a coordinator needs to compare distributed changes without merging whole files:
 
 ```js

package/bench/smoke.mjs

@@ -116,6 +116,7 @@ console.log(JSON.stringify({
   semanticLineageInferenceDurationMs: Number(sourceChangeMetrics.semanticLineageInferenceDurationMs.toFixed(2)),
   bidirectionalTargetChanges: sourceChangeMetrics.bidirectionalTargetChanges,
   bidirectionalTargetChangeMatches: sourceChangeMetrics.bidirectionalTargetChangeMatches,
+  bidirectionalTargetChangeSourceMapBacked: sourceChangeMetrics.bidirectionalTargetChangeSourceMapBacked,
   bidirectionalTargetChangeBlocked: sourceChangeMetrics.bidirectionalTargetChangeBlocked,
   bidirectionalTargetChangeDurationMs: Number(sourceChangeMetrics.bidirectionalTargetChangeDurationMs.toFixed(2)),
   externalSemanticImports: sourceChangeMetrics.externalSemanticImports,

package/bench/source-change-suite.mjs

@@ -112,6 +112,8 @@ function measureBidirectionalTargetChanges() {
     sourcePath: 'src/bidirectional-source.ts',
     sourceText: 'export function advance(frame: number): number { return frame + 1; }\n'
   });
+  const sourceSymbol = source.semanticIndex.symbols.find((symbol) => symbol.name === 'advance');
+  const sourceMapping = source.sourceMaps[0].mappings.find((mapping) => mapping.semanticSymbolId === sourceSymbol.id);
   const lineage = [createSemanticLineageEvent({
     eventKind: 'moved',
     from: { key: 'source#src/bidirectional-source.ts#body#advance', symbolName: 'advance' },
@@ -134,18 +136,45 @@ function measureBidirectionalTargetChanges() {
         sourcePath: `src/bidirectional-${index}.rs`,
         sourceText: `pub fn advance(frame: i32, delta: i32) -> i32 { frame + delta + ${index} }\n`
       },
-      sourceAnchorMappings: [{ targetSymbolName: 'advance', sourceSymbolName: 'advance' }],
+      ...(index % 2 === 0
+        ? { sourceMaps: [rustSourceMap(source, sourceSymbol, sourceMapping, index)] }
+        : { sourceAnchorMappings: [{ targetSymbolName: 'advance', sourceSymbolName: 'advance' }] }),
       lineage: index % 4 === 0 ? lineage : []
     }));
   }
   return {
     bidirectionalTargetChanges: records.length,
     bidirectionalTargetChangeMatches: records.reduce((sum, record) => sum + record.summary.sourceAnchorMatches, 0),
+    bidirectionalTargetChangeSourceMapBacked: records.reduce((sum, record) => sum + record.summary.sourceMapBackedMatches, 0),
     bidirectionalTargetChangeBlocked: records.filter((record) => record.readiness === 'blocked').length,
     bidirectionalTargetChangeDurationMs: performance.now() - start
   };
 }
 
+function rustSourceMap(source, sourceSymbol, sourceMapping, index) {
+  const targetPath = `src/bidirectional-${index}.rs`;
+  return {
+    kind: 'frontier.lang.sourceMap',
+    version: 1,
+    id: `bench_source_map_bidirectional_${index}`,
+    sourcePath: source.sourcePath,
+    sourceHash: source.nativeSource.sourceHash,
+    target: 'rust',
+    targetPath,
+    mappings: [{
+      id: `bench_map_advance_${index}`,
+      semanticSymbolId: sourceSymbol.id,
+      nativeAstNodeId: sourceSymbol.nativeAstNodeId,
+      sourceSpan: sourceMapping.sourceSpan,
+      generatedSpan: { path: targetPath, target: 'rust', targetPath, startLine: 1, startColumn: 1, endLine: 1, endColumn: 80, generatedName: 'advance' },
+      target: 'rust',
+      generatedName: 'advance',
+      precision: 'declaration',
+      preservation: 'declaration'
+    }]
+  };
+}
+
 function measureExternalSemanticImports() {
   const externalSemanticStart = performance.now();
   const externalSemanticImports = [];

package/dist/declarations/bidirectional-target-change.d.ts

@@ -2,6 +2,8 @@ import type {
   EvidenceRecord,
   FrontierSourceLanguage,
   SemanticMergeReadiness,
+  SourceMapMappingRecord,
+  SourceMapRecord,
   SourceSpan
 } from '@shapeshift-labs/frontier-lang-kernel';
 import type { ImportNativeSourceOptions, NativeSourceImportResult } from './import-adapter-core.js';
@@ -27,6 +29,26 @@ export interface BidirectionalTargetChangeSourceAnchorMapping {
   readonly sourceSymbolId?: string;
 }
 
+export interface BidirectionalTargetChangeSourceMapLink {
+  readonly id: string;
+  readonly sourceMapId?: string;
+  readonly sourceMapMappingId?: string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly targetPath?: string;
+  readonly targetHash?: string;
+  readonly semanticSymbolId?: string;
+  readonly semanticOccurrenceId?: string;
+  readonly semanticNodeId?: string;
+  readonly nativeSourceId?: string;
+  readonly nativeAstNodeId?: string;
+  readonly precision?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly generatedSpan?: SourceMapMappingRecord['generatedSpan'];
+  readonly regionKey?: string;
+  readonly regionKind?: string;
+}
+
 export interface BidirectionalTargetChangeAnchor {
   readonly id?: string;
   readonly key?: string;
@@ -47,6 +69,7 @@ export interface BidirectionalTargetChangeSourceAnchorMatch {
   readonly targetRegion: Partial<NativeSourceChangeRegion>;
   readonly sourceAnchors: readonly BidirectionalTargetChangeAnchor[];
   readonly lineageResolutions: readonly SemanticLineageResolution[];
+  readonly sourceMapLinks: readonly BidirectionalTargetChangeSourceMapLink[];
   readonly status: BidirectionalTargetChangeAnchorStatus;
   readonly confidence?: number;
   readonly reasonCodes: readonly string[];
@@ -77,6 +100,11 @@ export interface CreateBidirectionalTargetChangeRecordOptions {
   readonly after?: NativeSourceImportResult | ImportNativeSourceOptions;
   readonly sourceAnchorMappings?: readonly BidirectionalTargetChangeSourceAnchorMapping[];
   readonly anchorMappings?: readonly BidirectionalTargetChangeSourceAnchorMapping[];
+  readonly sourceMaps?: readonly SourceMapRecord[];
+  readonly projectionSourceMaps?: readonly SourceMapRecord[];
+  readonly targetSourceMaps?: readonly SourceMapRecord[];
+  readonly targetProjectionSourceMaps?: readonly SourceMapRecord[];
+  readonly targetCompileResult?: { readonly sourceMaps?: readonly SourceMapRecord[]; readonly sourceMap?: SourceMapRecord };
   readonly lineage?: readonly SemanticLineageEvent[];
   readonly lineageEvents?: readonly SemanticLineageEvent[];
   readonly lineageMap?: unknown;
@@ -114,6 +142,7 @@ export interface BidirectionalTargetChangeRecord {
     readonly unmatchedTargetRegions: number;
     readonly deletedSourceAnchors: number;
     readonly sourceChangedRegions: number;
+    readonly sourceMapBackedMatches: number;
   };
   readonly metadata: {
     readonly autoMergeClaim: false;

package/dist/declarations/semantic-history.d.ts

@@ -6,7 +6,7 @@ import type {
   SourceSpan
 } from '@shapeshift-labs/frontier-lang-kernel';
 import type { SemanticImportOwnershipRegion } from './semantic-sidecar.js';
-import type { CreateSemanticLineageEventInput, SemanticLineageEvent } from './semantic-lineage.js';
+import type { CreateSemanticLineageEventInput, SemanticAnchor, SemanticLineageEvent, SemanticLineageMap, SemanticLineageResolution } from './semantic-lineage.js';
 
 import type { SemanticHistoryAdmissionStatus, SemanticHistoryReviewerStatus, SemanticHistoryReplayLinkKind, SemanticHistoryOverlapKind, SemanticHistoryConflictReason, SemanticHistoryClaimKind, SemanticHistoryClaimStatus, SemanticHistoryProofAttemptStatus, SemanticHistoryMergeDecisionStatus, SemanticHistoryActorRef, SemanticHistoryRecordSourceRef, SemanticHistorySourceRef, SemanticHistoryOwnershipRegionRef, SemanticHistoryCandidateRef, SemanticHistoryClaimRecord, SemanticHistoryImportedParserEvidenceRecord, SemanticHistoryProofAttemptRecord, SemanticHistoryPatchAncestryRecord, SemanticHistoryMergeDecisionRecord, SemanticHistoryClaimInput, SemanticHistoryImportedParserEvidenceInput, SemanticHistoryProofAttemptInput, SemanticHistoryPatchAncestryInput, SemanticHistoryMergeDecisionInput, SemanticHistoryReviewerState, SemanticHistoryAdmissionState, SemanticHistoryReplayLink, SemanticHistoryRecordIndex } from './semantic-history-records.js';
 export type { SemanticHistoryAdmissionStatus, SemanticHistoryReviewerStatus, SemanticHistoryReplayLinkKind, SemanticHistoryOverlapKind, SemanticHistoryConflictReason, SemanticHistoryClaimKind, SemanticHistoryClaimStatus, SemanticHistoryProofAttemptStatus, SemanticHistoryMergeDecisionStatus, SemanticHistoryActorRef, SemanticHistoryRecordSourceRef, SemanticHistorySourceRef, SemanticHistoryOwnershipRegionRef, SemanticHistoryCandidateRef, SemanticHistoryClaimRecord, SemanticHistoryImportedParserEvidenceRecord, SemanticHistoryProofAttemptRecord, SemanticHistoryPatchAncestryRecord, SemanticHistoryMergeDecisionRecord, SemanticHistoryClaimInput, SemanticHistoryImportedParserEvidenceInput, SemanticHistoryProofAttemptInput, SemanticHistoryPatchAncestryInput, SemanticHistoryMergeDecisionInput, SemanticHistoryReviewerState, SemanticHistoryAdmissionState, SemanticHistoryReplayLink, SemanticHistoryRecordIndex } from './semantic-history-records.js';
@@ -138,6 +138,51 @@ export interface SemanticHistoryOverlapRecord {
   readonly reviewer: { readonly left?: SemanticHistoryReviewerStatus; readonly right?: SemanticHistoryReviewerStatus };
 }
 
+export type SemanticHistoryLineageAnchorSetKind = 'active' | 'candidate' | 'inactive' | 'deleted' | 'unresolved' | 'blocked';
+
+export interface SemanticHistoryLineageAnchorRecord extends Pick<SemanticAnchor, 'key' | 'id' | 'kind' | 'language' | 'sourcePath' | 'symbolId' | 'symbolName'> {
+  readonly status: string;
+  readonly resolutionId: string;
+  readonly reasonCodes: readonly string[];
+}
+
+export type SemanticHistoryLineageAnchorInventory = Readonly<Record<SemanticHistoryLineageAnchorSetKind, readonly SemanticHistoryLineageAnchorRecord[]>>;
+
+export interface SemanticHistoryRecordLineageResolution {
+  readonly kind: 'frontier.lang.semanticHistoryRecordLineageResolution';
+  readonly version: 1;
+  readonly id: string;
+  readonly stableId: string;
+  readonly hash: string;
+  readonly sourceRecordId?: string;
+  readonly sourceRecordStableId?: string;
+  readonly sourceRecordHash?: string;
+  readonly generatedAt: number | string;
+  readonly resolutions: readonly SemanticLineageResolution[];
+  readonly anchorInventory: SemanticHistoryLineageAnchorInventory;
+  readonly resolvedRecord: SemanticHistoryRecord;
+  readonly summary: Record<string, unknown> & {
+    readonly anchorCount: number;
+    readonly currentAnchorKeys: readonly string[];
+    readonly ownershipKeys: readonly string[];
+    readonly conflictKeys: readonly string[];
+    readonly activeAnchorKeys: readonly string[];
+    readonly candidateAnchorKeys: readonly string[];
+    readonly inactiveAnchorKeys: readonly string[];
+    readonly deletedAnchorKeys: readonly string[];
+    readonly unresolvedAnchorKeys: readonly string[];
+    readonly blockedAnchorKeys: readonly string[];
+    readonly reasonCodes: readonly string[];
+  };
+  readonly admission: {
+    readonly readiness: SemanticMergeReadiness | string;
+    readonly reviewRequired: boolean;
+    readonly autoMergeClaim: false;
+    readonly semanticEquivalenceClaim: false;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+
 export declare const SemanticHistoryAdmissionStatuses: readonly SemanticHistoryAdmissionStatus[];
 export declare const SemanticHistoryReviewerStatuses: readonly SemanticHistoryReviewerStatus[];
 export declare const SemanticHistoryOverlapKinds: readonly SemanticHistoryOverlapKind[];
@@ -146,3 +191,5 @@ export declare function createSemanticHistoryRecord(input?: CreateSemanticHistor
 export declare function querySemanticHistoryRecordOverlaps(records: SemanticHistoryRecord | readonly SemanticHistoryRecord[], options?: SemanticHistoryOverlapQueryOptions): readonly SemanticHistoryOverlapRecord[];
 export declare function semanticHistoryRecordsOverlap(left: SemanticHistoryRecord, right: SemanticHistoryRecord, options?: SemanticHistoryOverlapQueryOptions): boolean;
 export declare function semanticHistoryRecordsConflict(left: SemanticHistoryRecord, right: SemanticHistoryRecord, options?: SemanticHistoryOverlapQueryOptions): boolean;
+export declare function resolveSemanticHistoryRecordLineage(record: SemanticHistoryRecord, eventsOrMap?: SemanticLineageMap | readonly CreateSemanticLineageEventInput[], options?: { readonly id?: string; readonly generatedAt?: number | string; readonly maxDepth?: number; readonly keepDeletedAnchors?: boolean; readonly keepCandidateAnchors?: boolean; readonly keepBlockedAnchors?: boolean; readonly keepUnresolvedAnchors?: boolean; readonly metadata?: Record<string, unknown> }): SemanticHistoryRecordLineageResolution;
+export declare function resolveSemanticHistoryRecordsLineage(records: readonly SemanticHistoryRecord[] | SemanticHistoryRecord, eventsOrMap?: SemanticLineageMap | readonly CreateSemanticLineageEventInput[], options?: { readonly generatedAt?: number | string; readonly maxDepth?: number; readonly keepDeletedAnchors?: boolean; readonly keepCandidateAnchors?: boolean; readonly keepBlockedAnchors?: boolean; readonly keepUnresolvedAnchors?: boolean; readonly metadata?: Record<string, unknown> }): readonly SemanticHistoryRecordLineageResolution[];

package/dist/index.js

@@ -73,6 +73,7 @@ export { queryUniversalConversionPlan } from './internal/index-impl/queryUnivers
 export { createSemanticAnchor, createSemanticLineageEvent, createSemanticLineageMap, querySemanticLineageEvents, SemanticLineageEventKinds } from './internal/index-impl/semanticLineageRecords.js';
 export { resolveSemanticLineage, resolveSemanticLineageBatch, SemanticLineageResolutionStatuses } from './internal/index-impl/semanticLineageResolutionRecords.js';
 export { createSemanticHistoryRecord, querySemanticHistoryRecordOverlaps, SemanticHistoryAdmissionStatuses, SemanticHistoryConflictReasons, SemanticHistoryOverlapKinds, SemanticHistoryReviewerStatuses, semanticHistoryRecordsConflict, semanticHistoryRecordsOverlap } from './internal/index-impl/semanticHistoryRecords.js';
+export { resolveSemanticHistoryRecordLineage, resolveSemanticHistoryRecordsLineage } from './internal/index-impl/semanticHistoryLineageResolution.js';
 export { readSemanticSliceJson } from './internal/index-impl/readSemanticSliceJson.js';
 export { readUniversalAstJson } from './internal/index-impl/readUniversalAstJson.js';
 export { renderTargetAst } from './internal/index-impl/renderTargetAst.js';

package/dist/internal/index-impl/bidirectionalTargetChangeRecordInternals.js

@@ -8,13 +8,14 @@ import { resolveSemanticLineage } from './semanticLineageResolutionRecords.js';
 
 export function matchTargetRegion(context) {
   const explicit = explicitMappingForRegion(context.region, context.mappings);
-  const candidateAnchors = explicit
-    ? sourceAnchorsForMapping(explicit, context.sourceAnchors)
-    : sourceAnchorsByName(context.region, context.sourceAnchors);
+  const mapped = explicit ? { anchors: sourceAnchorsForMapping(explicit, context.sourceAnchors), links: [] }
+    : sourceMapAnchorsForRegion(context.region, context.sourceMaps, context.sourceAnchors);
+  const candidateAnchors = mapped.anchors.length ? mapped.anchors : sourceAnchorsByName(context.region, context.sourceAnchors);
   const resolvedAnchors = candidateAnchors.flatMap((anchor) => resolveAnchor(anchor, context.lineage));
   const status = matchStatus(candidateAnchors, resolvedAnchors);
   const reasonCodes = uniqueStrings([
-    explicit ? 'explicit-anchor-mapping' : 'inferred-by-symbol-name',
+    explicit ? 'explicit-anchor-mapping' : mapped.links.length ? 'source-map-generated-anchor' : 'inferred-by-symbol-name',
+    mapped.links.length ? 'mapped-by-generated-source-map' : undefined,
     status === 'unmatched' ? 'source-anchor-not-found' : undefined,
     status === 'ambiguous' ? 'source-anchor-ambiguous' : undefined,
     status === 'deleted' ? 'source-anchor-deleted' : undefined,
@@ -27,8 +28,9 @@ export function matchTargetRegion(context) {
     targetRegion: compactRegion(context.region),
     sourceAnchors: resolvedAnchors.map((entry) => entry.anchor),
     lineageResolutions: uniqueRecordsById(resolvedAnchors.map((entry) => entry.resolution).filter(Boolean)),
+    sourceMapLinks: mapped.links,
     status,
-    confidence: status === 'matched' && explicit ? 0.8 : status === 'matched' ? 0.58 : undefined,
+    confidence: status === 'matched' && explicit ? 0.8 : status === 'matched' && mapped.links.length ? 0.72 : status === 'matched' ? 0.58 : undefined,
     reasonCodes,
     reviewRequired: true,
     autoMergeClaim: false,
@@ -37,6 +39,7 @@ export function matchTargetRegion(context) {
       context.region.conflictKey,
       context.region.key,
       ...resolvedAnchors.map((entry) => entry.anchor?.key),
+      ...mapped.links.map((link) => link.sourceMapMappingId && `source-map:${link.sourceMapMappingId}`),
       status === 'unmatched' ? `target:${context.region.sourcePath ?? context.region.language ?? 'unknown'}` : undefined
     ])
   };
@@ -65,6 +68,7 @@ export function sourceRegionsForMatch(match, readiness) {
     symbolId: anchor?.symbolId,
     symbolName: anchor?.symbolName,
     sourceSpan: anchor?.sourceSpan,
+    sourceMapLinks: match.sourceMapLinks,
     admission: {
       readiness,
       action: 'review-port-from-target-change',
@@ -75,6 +79,7 @@ export function sourceRegionsForMatch(match, readiness) {
       bidirectionalTargetChange: {
         matchId: match.id,
         targetRegion: match.targetRegion,
+        sourceMapLinkIds: match.sourceMapLinks.map((link) => link.id),
         lineageResolutionIds: match.lineageResolutions.map((resolution) => resolution.id),
         reviewRequired: true,
         autoMergeClaim: false,
@@ -97,6 +102,8 @@ export function createBidirectionalEvidence(context) {
       targetChangeSetId: context.targetChangeSet.id,
       targetPatchId: context.targetChangeSet.patch?.id,
       sourceAnchorMatchIds: context.sourceAnchorMatches.map((match) => match.id),
+      sourceMapBackedMatches: context.sourceAnchorMatches.filter((match) => match.sourceMapLinks.length > 0).length,
+      sourceMapLinkIds: context.sourceAnchorMatches.flatMap((match) => match.sourceMapLinks.map((link) => link.id)),
       readiness: context.readiness,
       reasons: context.reasons,
       autoMergeClaim: false,
@@ -105,6 +112,77 @@ export function createBidirectionalEvidence(context) {
   };
 }
 
+function sourceMapAnchorsForRegion(region, sourceMaps, sourceAnchors) {
+  const links = [];
+  const anchors = [];
+  for (const sourceMap of sourceMaps ?? []) {
+    for (const mapping of sourceMap?.mappings ?? []) {
+      if (!mappingMatchesTargetRegion(mapping, sourceMap, region)) continue;
+      const link = sourceMapLinkForMapping(sourceMap, mapping);
+      links.push(link);
+      anchors.push(...anchorsForSourceMapMapping(mapping, link, sourceAnchors));
+    }
+  }
+  return { anchors: uniqueRecordsById(anchors), links: uniqueRecordsById(links) };
+}
+
+function anchorsForSourceMapMapping(mapping, link, sourceAnchors) {
+  const matches = sourceAnchors.filter((anchor) =>
+    (mapping.semanticSymbolId && anchor.symbolId === mapping.semanticSymbolId)
+    || (mapping.semanticNodeId && anchor.id === mapping.semanticNodeId)
+    || (mapping.nativeAstNodeId && anchor.metadata?.nativeAstNodeId === mapping.nativeAstNodeId)
+    || (mapping.ownershipRegionKey && anchor.key === mapping.ownershipRegionKey)
+  );
+  if (matches.length) return matches;
+  return [compactRecord({
+    id: mapping.semanticSymbolId ?? mapping.semanticNodeId ?? mapping.nativeAstNodeId ?? link.id,
+    key: mapping.ownershipRegionKey ?? mapping.semanticSymbolId ?? mapping.semanticNodeId ?? link.id,
+    kind: mapping.ownershipRegionKind ?? 'source-map',
+    language: link.sourceSpan?.language,
+    sourcePath: link.sourcePath,
+    sourceHash: link.sourceHash,
+    symbolId: mapping.semanticSymbolId,
+    symbolName: mapping.generatedName ?? mapping.generatedSpan?.generatedName,
+    sourceSpan: mapping.sourceSpan,
+    metadata: { sourceMapId: link.sourceMapId, sourceMapMappingId: link.sourceMapMappingId }
+  })];
+}
+
+function mappingMatchesTargetRegion(mapping, sourceMap, region) {
+  if (!targetPathMatches(mapping, sourceMap, region)) return false;
+  if (mapping.generatedName && namesForRegion(region).includes(mapping.generatedName)) return true;
+  if (mapping.generatedSpan?.generatedName && namesForRegion(region).includes(mapping.generatedSpan.generatedName)) return true;
+  return spansOverlap(mapping.generatedSpan, region.sourceSpan);
+}
+
+function targetPathMatches(mapping, sourceMap, region) {
+  const targetPaths = uniqueStrings([mapping.generatedSpan?.targetPath, mapping.generatedSpan?.path, sourceMap?.targetPath]);
+  const regionPath = region.sourcePath ?? region.sourceSpan?.path;
+  return !regionPath || targetPaths.length === 0 || targetPaths.includes(regionPath);
+}
+
+function sourceMapLinkForMapping(sourceMap, mapping) {
+  return compactRecord({
+    id: `source_map_link_${idFragment(sourceMap?.id ?? 'map')}_${idFragment(mapping.id ?? mapping.semanticSymbolId ?? 'mapping')}`,
+    sourceMapId: sourceMap?.id,
+    sourceMapMappingId: mapping.id,
+    sourcePath: mapping.sourceSpan?.path ?? sourceMap?.sourcePath,
+    sourceHash: mapping.sourceSpan?.sourceId ?? sourceMap?.sourceHash,
+    targetPath: mapping.generatedSpan?.targetPath ?? sourceMap?.targetPath,
+    targetHash: mapping.generatedSpan?.targetHash ?? sourceMap?.targetHash,
+    semanticSymbolId: mapping.semanticSymbolId,
+    semanticOccurrenceId: mapping.semanticOccurrenceId,
+    semanticNodeId: mapping.semanticNodeId,
+    nativeSourceId: mapping.nativeSourceId,
+    nativeAstNodeId: mapping.nativeAstNodeId,
+    precision: mapping.precision,
+    sourceSpan: mapping.sourceSpan,
+    generatedSpan: mapping.generatedSpan,
+    regionKey: mapping.ownershipRegionKey,
+    regionKind: mapping.ownershipRegionKind
+  });
+}
+
 export function anchorsFromSourceSidecar(sidecar, source) {
   return uniqueRecordsById((sidecar.ownershipRegions ?? []).map((region) => compactRecord({
     id: region.id,
@@ -148,11 +226,15 @@ function sourceAnchorsForMapping(mapping, sourceAnchors) {
 }
 
 function sourceAnchorsByName(region, sourceAnchors) {
-  const names = uniqueStrings([region.symbolName, region.name, region.metadata?.changedRegionProjection?.region?.symbolName]);
+  const names = namesForRegion(region);
   if (names.length === 0) return [];
   return sourceAnchors.filter((anchor) => names.includes(anchor.symbolName));
 }
 
+function namesForRegion(region) {
+  return uniqueStrings([region.symbolName, region.name, region.metadata?.changedRegionProjection?.region?.symbolName]);
+}
+
 function resolveAnchor(anchor, lineage) {
   if (!anchor) return [];
   const resolution = array(lineage).length ? resolveSemanticLineage(lineage, { anchorKey: anchor.key }) : undefined;
@@ -189,6 +271,23 @@ function compactRegion(region) {
   });
 }
 
+function spansOverlap(left, right) {
+  if (!left || !right) return false;
+  if (!sourcePathsCompatible(left, right)) return false;
+  const leftStart = Number(left.startLine ?? 0);
+  const leftEnd = Number(left.endLine ?? left.startLine ?? 0);
+  const rightStart = Number(right.startLine ?? 0);
+  const rightEnd = Number(right.endLine ?? right.startLine ?? 0);
+  if (!leftStart || !rightStart) return false;
+  return leftStart <= rightEnd && rightStart <= leftEnd;
+}
+
+function sourcePathsCompatible(left, right) {
+  const leftPath = left.targetPath ?? left.path;
+  const rightPath = right.targetPath ?? right.path;
+  return !leftPath || !rightPath || leftPath === rightPath;
+}
+
 function array(value) {
   return value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
 }

package/dist/internal/index-impl/createBidirectionalTargetChangeRecord.js

@@ -1,5 +1,6 @@
 import {
   idFragment,
+  uniqueRecordsById,
   uniqueStrings
 } from '../../native-import-utils.js';
 import { createSemanticImportSidecar } from './createSemanticImportSidecar.js';
@@ -45,6 +46,14 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
   }) : undefined;
   const sourceAnchors = sourceSidecar ? anchorsFromSourceSidecar(sourceSidecar, source) : [];
   const mappings = array(input.sourceAnchorMappings ?? input.anchorMappings);
+  const sourceMaps = uniqueRecordsById([
+    ...array(input.sourceMaps),
+    ...array(input.projectionSourceMaps),
+    ...array(input.targetSourceMaps),
+    ...array(input.targetProjectionSourceMaps),
+    ...array(input.targetCompileResult?.sourceMaps),
+    input.targetCompileResult?.sourceMap
+  ]);
   const lineage = input.lineage ?? input.lineageEvents ?? input.lineageMap ?? [];
   const sourceAnchorMatches = targetChangeSet.changedRegions.map((region, index) => matchTargetRegion({
     id,
@@ -53,6 +62,7 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
     source,
     sourceAnchors,
     mappings,
+    sourceMaps,
     lineage
   }));
   const readiness = classifyBidirectionalReadiness(targetChangeSet, source, sourceAnchorMatches);
@@ -86,7 +96,8 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
       projectionOnly: true,
       targetChangeSetId: targetChangeSet.id,
       targetPatchId: targetChangeSet.patch?.id,
-      targetMergeCandidateId: targetChangeSet.mergeCandidate?.id
+      targetMergeCandidateId: targetChangeSet.mergeCandidate?.id,
+      sourceMapBackprojection: summarizeSourceMapBackprojection(sourceAnchorMatches)
     }
   }, {
     id: input.sourcePatchBundleId ?? `semantic_patch_bundle_${idFragment(id)}_source_port`,
@@ -127,6 +138,7 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
       bidirectionalTargetChangeId: id,
       sourcePatchBundleId: sourcePatchBundle.id,
       targetChangeSetId: targetChangeSet.id,
+      sourceMapBackprojection: summarizeSourceMapBackprojection(sourceAnchorMatches),
       autoMergeClaim: false,
       semanticEquivalenceClaim: false
     }
@@ -153,7 +165,8 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
       ambiguousMatches: sourceAnchorMatches.filter((match) => match.status === 'ambiguous').length,
       unmatchedTargetRegions: sourceAnchorMatches.filter((match) => match.status === 'unmatched').length,
       deletedSourceAnchors: sourceAnchorMatches.filter((match) => match.status === 'deleted').length,
-      sourceChangedRegions: sourceChangedRegions.length
+      sourceChangedRegions: sourceChangedRegions.length,
+      sourceMapBackedMatches: sourceAnchorMatches.filter((match) => match.sourceMapLinks.length > 0).length
     },
     metadata: {
       autoMergeClaim: false,
@@ -164,6 +177,16 @@ export function createBidirectionalTargetChangeRecord(input = {}, options = {})
   };
 }
 
+function summarizeSourceMapBackprojection(matches) {
+  const links = matches.flatMap((match) => match.sourceMapLinks ?? []);
+  return {
+    sourceMapBackedMatches: matches.filter((match) => (match.sourceMapLinks ?? []).length > 0).length,
+    sourceMapLinks: links.length,
+    sourceMapIds: uniqueStrings(links.map((link) => link.sourceMapId)),
+    sourceMapMappingIds: uniqueStrings(links.map((link) => link.sourceMapMappingId))
+  };
+}
+
 function array(value) {
   return value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
 }

package/dist/internal/index-impl/semanticHistoryLineageResolution.js

@@ -0,0 +1,256 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { idFragment, uniqueStrings as uniqueRawStrings } from '../../native-import-utils.js';
+import { resolveSemanticLineage } from './semanticLineageResolutionRecords.js';
+
+export function resolveSemanticHistoryRecordLineage(record = {}, eventsOrMap = [], options = {}) {
+  const generatedAt = options.generatedAt ?? Date.now();
+  const sourceIndex = record.index ?? {};
+  const anchorKeys = uniqueStrings([
+    ...array(sourceIndex.semanticAnchorKeys),
+    ...array(sourceIndex.ownershipKeys),
+    ...array(sourceIndex.conflictKeys)
+  ]);
+  const resolutions = anchorKeys.map((anchorKey) => resolveSemanticLineage(eventsOrMap, {
+    anchorKey,
+    generatedAt
+  }, { maxDepth: options.maxDepth }));
+  const byAnchorKey = new Map(resolutions.map((resolution) => [resolution.query.anchorKey, resolution]));
+  const resolvedIndex = {
+    ...sourceIndex,
+    ownershipKeys: resolveIndexKeys(sourceIndex.ownershipKeys, byAnchorKey, options),
+    conflictKeys: resolveIndexKeys(sourceIndex.conflictKeys, byAnchorKey, options),
+    semanticAnchorKeys: resolveIndexKeys(sourceIndex.semanticAnchorKeys, byAnchorKey, options),
+    sourcePaths: uniqueStrings([
+      ...array(sourceIndex.sourcePaths),
+      ...resolutions.flatMap((resolution) => resolution.currentAnchors.map((anchor) => anchor.sourcePath))
+    ]),
+    lineageEventIds: uniqueStrings([
+      ...array(sourceIndex.lineageEventIds),
+      ...resolutions.flatMap((resolution) => resolution.traversedEventIds)
+    ]),
+    semanticLineageKinds: uniqueStrings([
+      ...array(sourceIndex.semanticLineageKinds),
+      ...resolutions.flatMap((resolution) => resolution.lineageEventKinds)
+    ]),
+    crdtOperationIds: uniqueStrings([
+      ...array(sourceIndex.crdtOperationIds),
+      ...resolutions.flatMap((resolution) => resolution.crdtOperationIds)
+    ]),
+    crdtHeads: uniqueStrings([
+      ...array(sourceIndex.crdtHeads),
+      ...resolutions.flatMap((resolution) => resolution.crdtHeads)
+    ]),
+    evidenceIds: uniqueStrings([
+      ...array(sourceIndex.evidenceIds),
+      ...resolutions.flatMap((resolution) => resolution.evidenceIds)
+    ]),
+    proofIds: uniqueStrings([
+      ...array(sourceIndex.proofIds),
+      ...resolutions.flatMap((resolution) => resolution.proofIds)
+    ])
+  };
+  const anchorInventory = createAnchorInventory(resolutions);
+  const summary = summarizeSemanticHistoryLineageResolutions(resolutions, resolvedIndex, anchorInventory);
+  const readiness = summary.cycle > 0 || summary.maxDepth > 0 ? 'blocked' : summary.resolved > 0 || summary.ambiguous > 0 || summary.deleted > 0 || summary.recreated > 0 ? 'needs-review' : 'ready';
+  const resolutionCore = {
+    kind: 'frontier.lang.semanticHistoryRecordLineageResolution',
+    version: 1,
+    sourceRecordId: record.id,
+    sourceRecordStableId: record.stableId,
+    sourceRecordHash: record.hash,
+    generatedAt,
+    resolutions,
+    anchorInventory,
+    summary,
+    admission: {
+      readiness,
+      reviewRequired: readiness !== 'ready',
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    },
+    metadata: compactRecord(options.metadata)
+  };
+  const hash = hashSemanticValue(resolutionCore);
+  const id = options.id ?? `semantic_history_lineage_resolution_${idFragment(firstString(record.id, record.stableId, hash))}`;
+  const resolvedRecord = createResolvedHistoryRecord(record, resolvedIndex, { id, hash, generatedAt, summary, readiness });
+  return {
+    ...resolutionCore,
+    id,
+    stableId: `semantic_history_lineage_resolution_${idFragment(hash)}`,
+    hash,
+    resolvedRecord
+  };
+}
+
+export function resolveSemanticHistoryRecordsLineage(records = [], eventsOrMap = [], options = {}) {
+  return array(records).map((record) => resolveSemanticHistoryRecordLineage(record, eventsOrMap, options));
+}
+
+function createResolvedHistoryRecord(record, index, resolution) {
+  const core = {
+    ...record,
+    id: `${record.id ?? 'semantic_history'}#lineage-resolved`,
+    index,
+    metadata: {
+      ...(record.metadata ?? {}),
+      semanticHistoryLineageResolution: {
+        id: resolution.id,
+        sourceRecordId: record.id,
+        sourceRecordHash: record.hash,
+        readiness: resolution.readiness,
+        summary: resolution.summary,
+        anchorSummary: {
+          activeAnchorKeys: resolution.summary.activeAnchorKeys,
+          candidateAnchorKeys: resolution.summary.candidateAnchorKeys,
+          inactiveAnchorKeys: resolution.summary.inactiveAnchorKeys,
+          blockedAnchorKeys: resolution.summary.blockedAnchorKeys
+        },
+        autoMergeClaim: false,
+        semanticEquivalenceClaim: false
+      }
+    }
+  };
+  const stableCore = { ...core };
+  delete stableCore.hash;
+  delete stableCore.stableId;
+  const hash = hashSemanticValue(stableCore);
+  return {
+    ...core,
+    stableId: `semantic_history_${idFragment(hash)}`,
+    hash
+  };
+}
+
+function resolveIndexKeys(values, resolutions, options) {
+  return uniqueStrings(array(values).flatMap((value) => {
+    const key = String(value);
+    const resolution = resolutions.get(key);
+    if (!resolution) return [key];
+    if (resolution.status === 'deleted' && options.keepDeletedAnchors !== true) return [];
+    if (resolution.status === 'cycle' && options.keepBlockedAnchors !== true) return [];
+    if (resolution.status === 'max-depth' && options.keepBlockedAnchors !== true) return [];
+    if (resolution.status === 'not-found' && options.keepUnresolvedAnchors !== true) return [];
+    if (resolution.status === 'ambiguous' && options.keepCandidateAnchors === false) return [];
+    const current = resolution.currentAnchors.map((anchor) => anchor.key).filter(Boolean);
+    return current.length ? current : [key];
+  }));
+}
+
+function summarizeSemanticHistoryLineageResolutions(resolutions, index, anchorInventory) {
+  const byStatus = {};
+  for (const resolution of resolutions) byStatus[resolution.status] = (byStatus[resolution.status] ?? 0) + 1;
+  return {
+    anchorCount: resolutions.length,
+    unchanged: byStatus.unchanged ?? 0,
+    resolved: byStatus.resolved ?? 0,
+    ambiguous: byStatus.ambiguous ?? 0,
+    deleted: byStatus.deleted ?? 0,
+    recreated: byStatus.recreated ?? 0,
+    cycle: byStatus.cycle ?? 0,
+    maxDepth: byStatus['max-depth'] ?? 0,
+    notFound: byStatus['not-found'] ?? 0,
+    currentAnchorKeys: uniqueStrings(index.semanticAnchorKeys),
+    ownershipKeys: uniqueStrings(index.ownershipKeys),
+    conflictKeys: uniqueStrings(index.conflictKeys),
+    sourcePaths: uniqueStrings(index.sourcePaths),
+    activeAnchorKeys: uniqueStrings(anchorInventory.active.map((anchor) => anchor.key)),
+    candidateAnchorKeys: uniqueStrings(anchorInventory.candidate.map((anchor) => anchor.key)),
+    inactiveAnchorKeys: uniqueStrings(anchorInventory.inactive.map((anchor) => anchor.key)),
+    deletedAnchorKeys: uniqueStrings(anchorInventory.deleted.map((anchor) => anchor.key)),
+    unresolvedAnchorKeys: uniqueStrings(anchorInventory.unresolved.map((anchor) => anchor.key)),
+    blockedAnchorKeys: uniqueStrings(anchorInventory.blocked.map((anchor) => anchor.key)),
+    traversedEventIds: uniqueStrings(resolutions.flatMap((resolution) => resolution.traversedEventIds)),
+    terminalEventIds: uniqueStrings(resolutions.flatMap((resolution) => resolution.terminalEventIds)),
+    reasonCodes: uniqueStrings(resolutions.flatMap((resolution) => resolution.reasonCodes))
+  };
+}
+
+function createAnchorInventory(resolutions) {
+  const inventory = {
+    active: [],
+    candidate: [],
+    inactive: [],
+    deleted: [],
+    unresolved: [],
+    blocked: []
+  };
+  for (const resolution of resolutions) {
+    const start = anchorEntry(resolution.startAnchor ?? queryAnchor(resolution), resolution);
+    const current = resolution.currentAnchors.map((anchor) => anchorEntry(anchor, resolution));
+    if (resolution.status === 'ambiguous') {
+      inventory.candidate.push(...current);
+      if (start) inventory.inactive.push(start);
+      continue;
+    }
+    if (resolution.status === 'deleted') {
+      if (start) {
+        inventory.inactive.push(start);
+        inventory.deleted.push(start);
+      }
+      continue;
+    }
+    if (resolution.status === 'cycle' || resolution.status === 'max-depth') {
+      if (start) {
+        inventory.inactive.push(start);
+        inventory.blocked.push(start);
+      }
+      continue;
+    }
+    if (resolution.status === 'not-found') {
+      if (start) {
+        inventory.inactive.push(start);
+        inventory.unresolved.push(start);
+      }
+      continue;
+    }
+    inventory.active.push(...current);
+  }
+  return {
+    active: uniqueAnchorEntries(inventory.active),
+    candidate: uniqueAnchorEntries(inventory.candidate),
+    inactive: uniqueAnchorEntries(inventory.inactive),
+    deleted: uniqueAnchorEntries(inventory.deleted),
+    unresolved: uniqueAnchorEntries(inventory.unresolved),
+    blocked: uniqueAnchorEntries(inventory.blocked)
+  };
+}
+
+function anchorEntry(anchor, resolution) {
+  if (!anchor) return undefined;
+  return compactRecord({
+    key: anchor.key,
+    id: anchor.id,
+    kind: anchor.kind,
+    language: anchor.language,
+    sourcePath: anchor.sourcePath,
+    symbolId: anchor.symbolId,
+    symbolName: anchor.symbolName,
+    status: resolution.status,
+    resolutionId: resolution.id,
+    reasonCodes: uniqueStrings(resolution.reasonCodes)
+  });
+}
+
+function queryAnchor(resolution) {
+  return compactRecord({
+    key: resolution.query?.anchorKey,
+    id: resolution.query?.anchorId,
+    sourcePath: resolution.query?.sourcePath,
+    symbolName: resolution.query?.symbolName
+  });
+}
+
+function uniqueAnchorEntries(entries) {
+  const seen = new Set();
+  return entries.filter(Boolean).filter((entry) => {
+    const key = entry.key ?? entry.id ?? `${entry.sourcePath ?? ''}:${entry.symbolName ?? ''}`;
+    if (!key || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function array(value) { return value === undefined || value === null ? [] : Array.isArray(value) ? value : [value]; }
+function uniqueStrings(values) { return uniqueRawStrings(array(values).map((value) => String(value ?? '')).filter(Boolean)); }
+function firstString(...values) { return values.map((value) => value === undefined || value === null ? '' : String(value)).find(Boolean); }
+function compactRecord(value) { return Object.fromEntries(Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined)); }

package/package.json

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