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

package/README.md

@@ -383,6 +383,45 @@ console.log(querySemanticPatchBundleRecords([bundle], { sourcePath: 'src/runtime
 
 Semantic patch bundle records keep compact refs and query indexes for base/target/source hashes, source paths, changed region keys, conflict keys, source-map IDs, evidence IDs, proof IDs, history IDs, readiness, and admission status. They intentionally omit `before`/`after` import payloads and source text; use the original diff result when a worker needs to re-read or re-project source.
 
+Map an edited target-language file back to source-language semantic anchors for review. This is the reverse direction a swarm needs when a worker changes generated Rust/Python/etc. and the coordinator wants source-port evidence:
+
+```js
+import {
+  createBidirectionalTargetChangeRecord,
+  importNativeSource
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const source = importNativeSource({
+  language: 'typescript',
+  sourcePath: 'src/counter.ts',
+  sourceText: 'export function add(count: number) { return count + 1; }\n'
+});
+
+const targetChange = createBidirectionalTargetChangeRecord({
+  source,
+  targetLanguage: 'rust',
+  targetPath: 'src/counter.rs',
+  baseTarget: {
+    language: 'rust',
+    sourcePath: 'src/counter.rs',
+    sourceText: 'pub fn add(count: i32) -> i32 { count + 1 }\n'
+  },
+  editedTarget: {
+    language: 'rust',
+    sourcePath: 'src/counter.rs',
+    sourceText: 'pub fn add(count: i32, step: i32) -> i32 { count + step }\n'
+  },
+  sourceAnchorMappings: [{ targetSymbolName: 'add', sourceSymbolName: 'add' }]
+});
+
+console.log(targetChange.sourceAnchorMatches[0].status); // "matched"
+console.log(targetChange.sourcePatchBundle.admission.reviewRequired); // true
+console.log(targetChange.historyRecord.index.ownershipKeys);
+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.
+
 Store worker outputs as compact semantic history records when a coordinator needs to compare distributed changes without merging whole files:
 
 ```js
@@ -448,6 +487,38 @@ console.log(resolution.currentAnchors[0].key); // current semantic anchor
 console.log(resolution.traversedEventIds); // compact history path
 ```
 
+Infer conservative lineage events from two native imports when a file was moved,
+a parser reports a rename, or an anchor disappeared:
+
+```js
+import {
+  importNativeSource,
+  inferSemanticLineageEvents
+} from '@shapeshift-labs/frontier-lang-compiler';
+
+const before = importNativeSource({
+  language: 'typescript',
+  sourcePath: 'src/runtime.ts',
+  sourceText: 'export function step(value) { return value + 1; }\n'
+});
+const after = importNativeSource({
+  language: 'typescript',
+  sourcePath: 'src/runtime-core.ts',
+  sourceText: 'export function step(value) { return value + 1; }\n'
+});
+
+const inference = inferSemanticLineageEvents({ before, after });
+
+console.log(inference.summary.moved); // 1
+console.log(inference.events[0].metadata.autoMergeClaim); // false
+console.log(inference.lineageMap.byAnchorKey); // old/current anchor index
+```
+
+The inference API is intentionally conservative. Ambiguous matches are reported
+as blocked, additions are kept separate from recreated lineage, and inferred
+events always require review; richer parser adapters can improve confidence by
+supplying stable signature hashes and source-map spans.
+
 Resolver output is merge-admission evidence: it helps a swarm compare old worker bundles against current semantic anchors after code moved, split, or was deleted. It is not proof that the projected code is correct or semantically equivalent; admission still needs tests, source evidence, review status, and conflict scoring.
 
 Extract a surgical semantic slice when a worker only needs one symbol, region, native AST node, or source path:

package/bench/smoke.mjs

@@ -110,6 +110,14 @@ console.log(JSON.stringify({
   changedRegionProjections: sourceChangeMetrics.changedRegionProjections,
   changedRegionProjectionSourceMapLinks: sourceChangeMetrics.changedRegionProjectionSourceMapLinks,
   changeProjectionDurationMs: Number(sourceChangeMetrics.changeProjectionDurationMs.toFixed(2)),
+  semanticLineageInferences: sourceChangeMetrics.semanticLineageInferences,
+  semanticLineageEvents: sourceChangeMetrics.semanticLineageEvents,
+  semanticLineageDeleted: sourceChangeMetrics.semanticLineageDeleted,
+  semanticLineageInferenceDurationMs: Number(sourceChangeMetrics.semanticLineageInferenceDurationMs.toFixed(2)),
+  bidirectionalTargetChanges: sourceChangeMetrics.bidirectionalTargetChanges,
+  bidirectionalTargetChangeMatches: sourceChangeMetrics.bidirectionalTargetChangeMatches,
+  bidirectionalTargetChangeBlocked: sourceChangeMetrics.bidirectionalTargetChangeBlocked,
+  bidirectionalTargetChangeDurationMs: Number(sourceChangeMetrics.bidirectionalTargetChangeDurationMs.toFixed(2)),
   externalSemanticImports: sourceChangeMetrics.externalSemanticImports,
   externalSemanticSymbols: sourceChangeMetrics.externalSemanticSymbols,
   externalSemanticMappings: sourceChangeMetrics.externalSemanticMappings,

package/bench/source-change-suite.mjs

@@ -1,7 +1,10 @@
 import { performance } from 'node:perf_hooks';
 import {
+  createBidirectionalTargetChangeRecord,
   createSemanticImportSidecar,
+  createSemanticLineageEvent,
   diffNativeSources,
+  inferSemanticLineageEvents,
   importExternalSemanticIndex,
   importNativeSource
 } from '../dist/index.js';
@@ -10,6 +13,8 @@ export function measureSourceChangeSuites() {
   return {
     ...measureRegionScan(),
     ...measureChangeProjection(),
+    ...measureSemanticLineageInference(),
+    ...measureBidirectionalTargetChanges(),
     ...measureExternalSemanticImports()
   };
 }
@@ -72,6 +77,75 @@ function measureChangeProjection() {
   };
 }
 
+function measureSemanticLineageInference() {
+  const start = performance.now();
+  const inferences = [];
+  for (let index = 0; index < 80; index += 1) {
+    inferences.push(inferSemanticLineageEvents({
+      id: `bench_semantic_lineage_inference_${index}`,
+      before: {
+        language: 'typescript',
+        sourcePath: `src/lineage-before-${index}.ts`,
+        sourceText: `export function lineageBench${index}(value) { return value + ${index}; }\n`
+      },
+      after: {
+        language: 'typescript',
+        sourcePath: index % 5 === 0 ? `src/lineage-before-${index}.ts` : `src/lineage-after-${index}.ts`,
+        sourceText: index % 6 === 0
+          ? `export const lineageBenchDeleted${index} = true;\n`
+          : `export function lineageBench${index}(value) { return value + ${index}; }\n`
+      }
+    }));
+  }
+  return {
+    semanticLineageInferences: inferences.length,
+    semanticLineageEvents: inferences.reduce((sum, inference) => sum + inference.events.length, 0),
+    semanticLineageDeleted: inferences.reduce((sum, inference) => sum + inference.summary.deleted, 0),
+    semanticLineageInferenceDurationMs: performance.now() - start
+  };
+}
+
+function measureBidirectionalTargetChanges() {
+  const start = performance.now();
+  const source = importNativeSource({
+    language: 'typescript',
+    sourcePath: 'src/bidirectional-source.ts',
+    sourceText: 'export function advance(frame: number): number { return frame + 1; }\n'
+  });
+  const lineage = [createSemanticLineageEvent({
+    eventKind: 'moved',
+    from: { key: 'source#src/bidirectional-source.ts#body#advance', symbolName: 'advance' },
+    to: { key: 'source#src/runtime-core.ts#body#advanceFrame', symbolName: 'advanceFrame' }
+  })];
+  const records = [];
+  for (let index = 0; index < 60; index += 1) {
+    records.push(createBidirectionalTargetChangeRecord({
+      id: `bench_bidirectional_target_change_${index}`,
+      source,
+      targetLanguage: 'rust',
+      targetPath: `src/bidirectional-${index}.rs`,
+      baseTarget: {
+        language: 'rust',
+        sourcePath: `src/bidirectional-${index}.rs`,
+        sourceText: `pub fn advance(frame: i32) -> i32 { frame + ${index} }\n`
+      },
+      editedTarget: {
+        language: 'rust',
+        sourcePath: `src/bidirectional-${index}.rs`,
+        sourceText: `pub fn advance(frame: i32, delta: i32) -> i32 { frame + delta + ${index} }\n`
+      },
+      sourceAnchorMappings: [{ targetSymbolName: 'advance', sourceSymbolName: 'advance' }],
+      lineage: index % 4 === 0 ? lineage : []
+    }));
+  }
+  return {
+    bidirectionalTargetChanges: records.length,
+    bidirectionalTargetChangeMatches: records.reduce((sum, record) => sum + record.summary.sourceAnchorMatches, 0),
+    bidirectionalTargetChangeBlocked: records.filter((record) => record.readiness === 'blocked').length,
+    bidirectionalTargetChangeDurationMs: performance.now() - start
+  };
+}
+
 function measureExternalSemanticImports() {
   const externalSemanticStart = performance.now();
   const externalSemanticImports = [];

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

@@ -0,0 +1,129 @@
+import type {
+  EvidenceRecord,
+  FrontierSourceLanguage,
+  SemanticMergeReadiness,
+  SourceSpan
+} from '@shapeshift-labs/frontier-lang-kernel';
+import type { ImportNativeSourceOptions, NativeSourceImportResult } from './import-adapter-core.js';
+import type { NativeSourceChangeRegion, NativeSourceChangeSet } from './native-diff.js';
+import type { SemanticHistoryRecord } from './semantic-history.js';
+import type { SemanticLineageEvent, SemanticLineageResolution } from './semantic-lineage.js';
+import type { SemanticPatchBundleRecord } from './semantic-patch-bundle.js';
+
+export type BidirectionalTargetChangeAnchorStatus = 'matched' | 'unmatched' | 'ambiguous' | 'deleted' | string;
+
+export interface BidirectionalTargetChangeSourceAnchorMapping {
+  readonly targetAnchorKey?: string;
+  readonly targetRegionKey?: string;
+  readonly targetConflictKey?: string;
+  readonly targetKey?: string;
+  readonly targetSymbolName?: string;
+  readonly targetSymbolId?: string;
+  readonly sourceAnchorKey?: string;
+  readonly sourceRegionKey?: string;
+  readonly sourceConflictKey?: string;
+  readonly sourceKey?: string;
+  readonly sourceSymbolName?: string;
+  readonly sourceSymbolId?: string;
+}
+
+export interface BidirectionalTargetChangeAnchor {
+  readonly id?: string;
+  readonly key?: string;
+  readonly kind?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly symbolId?: string;
+  readonly symbolName?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface BidirectionalTargetChangeSourceAnchorMatch {
+  readonly kind: 'frontier.lang.bidirectionalTargetChangeSourceAnchorMatch';
+  readonly version: 1;
+  readonly id: string;
+  readonly targetRegion: Partial<NativeSourceChangeRegion>;
+  readonly sourceAnchors: readonly BidirectionalTargetChangeAnchor[];
+  readonly lineageResolutions: readonly SemanticLineageResolution[];
+  readonly status: BidirectionalTargetChangeAnchorStatus;
+  readonly confidence?: number;
+  readonly reasonCodes: readonly string[];
+  readonly reviewRequired: true;
+  readonly autoMergeClaim: false;
+  readonly semanticEquivalenceClaim: false;
+  readonly conflictKeys: readonly string[];
+}
+
+export interface CreateBidirectionalTargetChangeRecordOptions {
+  readonly id?: string;
+  readonly source?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly sourceImport?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly baseSource?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly sourceLanguage?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceParser?: string;
+  readonly targetChangeSet?: NativeSourceChangeSet;
+  readonly targetChangeSetId?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly targetLanguage?: FrontierSourceLanguage | string;
+  readonly targetPath?: string;
+  readonly baseTarget?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly beforeTarget?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly before?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly editedTarget?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly afterTarget?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly after?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly sourceAnchorMappings?: readonly BidirectionalTargetChangeSourceAnchorMapping[];
+  readonly anchorMappings?: readonly BidirectionalTargetChangeSourceAnchorMapping[];
+  readonly lineage?: readonly SemanticLineageEvent[];
+  readonly lineageEvents?: readonly SemanticLineageEvent[];
+  readonly lineageMap?: unknown;
+  readonly targetEvidenceId?: string;
+  readonly targetPatchId?: string;
+  readonly targetMergeCandidateId?: string;
+  readonly sourceRegionPrefix?: string;
+  readonly sourcePatchBundleId?: string;
+  readonly historyRecordId?: string;
+  readonly evidenceId?: string;
+  readonly generatedAt?: number | string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface BidirectionalTargetChangeRecord {
+  readonly kind: 'frontier.lang.bidirectionalTargetChangeRecord';
+  readonly version: 1;
+  readonly id: string;
+  readonly sourceLanguage?: FrontierSourceLanguage | string;
+  readonly targetLanguage?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly targetPath?: string;
+  readonly sourceImport?: NativeSourceImportResult;
+  readonly targetChangeSet: NativeSourceChangeSet;
+  readonly sourceAnchorMatches: readonly BidirectionalTargetChangeSourceAnchorMatch[];
+  readonly sourcePatchBundle: SemanticPatchBundleRecord;
+  readonly historyRecord: SemanticHistoryRecord;
+  readonly evidence: readonly EvidenceRecord[];
+  readonly readiness: SemanticMergeReadiness | string;
+  readonly reasons: readonly string[];
+  readonly summary: {
+    readonly targetChangedRegions: number;
+    readonly sourceAnchorMatches: number;
+    readonly ambiguousMatches: number;
+    readonly unmatchedTargetRegions: number;
+    readonly deletedSourceAnchors: number;
+    readonly sourceChangedRegions: number;
+  };
+  readonly metadata: {
+    readonly autoMergeClaim: false;
+    readonly semanticEquivalenceClaim: false;
+    readonly reviewRequired: true;
+    readonly [key: string]: unknown;
+  };
+}
+
+export declare function createBidirectionalTargetChangeRecord(
+  input?: CreateBidirectionalTargetChangeRecordOptions,
+  options?: Record<string, unknown>
+): BidirectionalTargetChangeRecord;

package/dist/declarations/native-diff.d.ts

@@ -40,6 +40,7 @@ import type { UniversalCapabilityLanguageRow, UniversalCapabilityMatrix, Univers
 import type { NativeImportContractSource, NativeImportSourcePreservationRecordSummary, NativeImportSourcePreservationContract, NativeImportAdapterCoverageRecordSummary, NativeImportAdapterCoverageContract, NativeImportRegionSummary, NativeImportSourceMapSummary, NativeImportReadinessContract, NativeImportResultContract, NativeImportResultContractOptions } from './native-import-contracts.js';
 import type { NativeSourceTokenKind, NativeSourcePreservedToken, NativeSourcePreservedDirective, NativeSourcePreservation, CreateNativeSourcePreservationOptions } from './source-preservation.js';
 import type { SemanticImportOwnershipRegion, SemanticImportSidecarSymbol, SemanticImportRegionTaxonomySummary, SemanticImportPatchHint, SemanticImportSidecarImportEntry, SemanticImportSidecarSourcePreservationRecord, SemanticImportSidecarUniversalAstLayerSummary, SemanticImportSidecarProofSpecSummary, SemanticImportSidecarParadigmSemanticsSummary, SemanticImportSidecar, SemanticImportSidecarOptions } from './semantic-sidecar.js';
+import type { SemanticLineageInferenceResult } from './semantic-lineage.js';
 import type { SemanticMergeCandidateWithConflicts, SemanticMergeConflictSummary } from './semantic-merge-conflicts.js';
 import type { SemanticSliceInput, CreateSemanticSliceOptions, SemanticSliceSourceMapLink, SemanticSliceSourceFile, SemanticSliceExpectedAssertion, SemanticSlice, TestSemanticSliceOptions, SemanticSliceTestAssertion, SemanticSliceTestResult } from './semantic-slice.js';
 import type { NativeImporterAdapterExactness, NativeImporterAdapterSemanticCoverage, NativeImporterAdapterCoverageSnapshot, NativeImporterAdapterCoverageObserved, NativeImporterAdapterCoverageCapabilityRow, NativeImporterAdapterCoverageCapabilityEvidence, NativeImporterAdapterCoverageSummary, NativeImporterAdapterCoverageInput } from './adapter-coverage.js';
@@ -227,6 +228,7 @@ export interface NativeSourceChangeSet {
   readonly patch: SemanticPatchBundle;
   readonly mergeCandidate: SemanticMergeCandidateWithConflicts;
   readonly evidence: readonly EvidenceRecord[];
+  readonly lineageInference?: SemanticLineageInferenceResult;
   readonly readiness: SemanticMergeReadiness;
   readonly reasons: readonly string[];
   readonly sourceMaps: readonly SourceMapRecord[];
@@ -236,5 +238,6 @@ export interface NativeSourceChangeSet {
   readonly metadata?: Record<string, unknown> & {
     readonly changedRegionProjectionSummary?: NativeSourceChangeProjectionSummary;
     readonly semanticMergeConflictSummary?: SemanticMergeConflictSummary;
+    readonly semanticLineageInferenceSummary?: SemanticLineageInferenceResult['summary'];
   };
 }

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

@@ -1,4 +1,6 @@
 import type { FrontierSourceLanguage, SourceSpan } from '@shapeshift-labs/frontier-lang-kernel';
+import type { EvidenceRecord, SemanticMergeReadiness } from '@shapeshift-labs/frontier-lang-kernel';
+import type { ImportNativeSourceOptions, NativeSourceImportResult } from './import-adapter-core.js';
 
 export type SemanticLineageEventKind = 'unchanged' | 'moved' | 'renamed' | 'split' | 'merged' | 'deleted' | 'recreated' | 'unknown' | string;
 export type SemanticLineageResolutionStatus = 'unchanged' | 'resolved' | 'ambiguous' | 'deleted' | 'recreated' | 'cycle' | 'max-depth' | 'not-found' | string;
@@ -183,11 +185,105 @@ export interface SemanticLineageQuery {
   readonly evidenceId?: string | readonly string[];
 }
 
+export interface SemanticLineageInferredAnchorSummary {
+  readonly key?: string;
+  readonly id?: string;
+  readonly name?: string;
+  readonly kind?: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourceSpan?: SourceSpan;
+  readonly signatureHash?: string;
+  readonly bodyHash?: string;
+  readonly ownershipRegionKind?: string;
+}
+
+export interface SemanticLineageAmbiguousCandidate {
+  readonly after: SemanticLineageInferredAnchorSummary;
+  readonly confidence: number;
+  readonly reasons: readonly string[];
+}
+
+export interface SemanticLineageAmbiguousMatch {
+  readonly before: SemanticLineageInferredAnchorSummary;
+  readonly candidates: readonly SemanticLineageAmbiguousCandidate[];
+  readonly reasonCodes: readonly string[];
+}
+
+export interface SemanticLineageInferenceResult {
+  readonly kind: 'frontier.lang.semanticLineageInference';
+  readonly version: 1;
+  readonly id: string;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly beforeImportId?: string;
+  readonly afterImportId?: string;
+  readonly beforeHash?: string;
+  readonly afterHash?: string;
+  readonly events: readonly SemanticLineageEvent[];
+  readonly lineageMap: SemanticLineageMap;
+  readonly evidence: readonly EvidenceRecord[];
+  readonly unmatched: {
+    readonly removed: readonly SemanticLineageInferredAnchorSummary[];
+    readonly added: readonly SemanticLineageInferredAnchorSummary[];
+    readonly ambiguous: readonly SemanticLineageAmbiguousMatch[];
+  };
+  readonly summary: {
+    readonly beforeSymbols: number;
+    readonly afterSymbols: number;
+    readonly unchangedAnchors: number;
+    readonly inferredEvents: number;
+    readonly moved: number;
+    readonly renamed: number;
+    readonly deleted: number;
+    readonly ambiguous: number;
+    readonly unmatchedAdded: number;
+    readonly minConfidence: number;
+    readonly ambiguityMargin: number;
+  };
+  readonly readiness: SemanticMergeReadiness;
+  readonly reasons: readonly string[];
+  readonly metadata: {
+    readonly autoMergeClaim: false;
+    readonly semanticEquivalenceClaim: false;
+    readonly reviewRequired: true;
+    readonly [key: string]: unknown;
+  };
+}
+
+export interface InferSemanticLineageEventsOptions {
+  readonly id?: string;
+  readonly before?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly after?: NativeSourceImportResult | ImportNativeSourceOptions;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly parser?: string;
+  readonly generatedAt?: number | string;
+  readonly regionPrefix?: string;
+  readonly evidenceId?: string;
+  readonly lineageMapId?: string;
+  readonly minConfidence?: number;
+  readonly ambiguityMargin?: number;
+  readonly includeDeleted?: boolean;
+  readonly deletedConfidence?: number;
+  readonly readiness?: SemanticMergeReadiness;
+  readonly actor?: SemanticLineageActor | string;
+  readonly actorId?: string;
+  readonly actorRole?: string;
+  readonly operationId?: string;
+  readonly deps?: readonly string[] | string;
+  readonly heads?: readonly string[] | string;
+  readonly stateVector?: Record<string, number>;
+  readonly metadata?: Record<string, unknown>;
+}
+
 export declare const SemanticLineageEventKinds: readonly SemanticLineageEventKind[];
 export declare const SemanticLineageResolutionStatuses: readonly SemanticLineageResolutionStatus[];
 export declare function createSemanticAnchor(input?: SemanticAnchor | string, defaults?: Partial<SemanticAnchor>): SemanticAnchor | undefined;
 export declare function createSemanticLineageEvent(input?: CreateSemanticLineageEventInput, options?: { readonly id?: string; readonly createdAt?: number | string; readonly actor?: SemanticLineageActor | string; readonly actorId?: string; readonly actorRole?: string }): SemanticLineageEvent;
 export declare function createSemanticLineageMap(events?: readonly (SemanticLineageEvent | CreateSemanticLineageEventInput)[], options?: { readonly id?: string; readonly generatedAt?: number | string }): SemanticLineageMap;
+export declare function inferSemanticLineageEvents(input?: InferSemanticLineageEventsOptions, options?: { readonly metadata?: Record<string, unknown>; readonly deletedConfidence?: number }): SemanticLineageInferenceResult;
 export declare function querySemanticLineageEvents(events: SemanticLineageEvent | readonly SemanticLineageEvent[], query?: SemanticLineageQuery): readonly SemanticLineageEvent[];
 export declare function resolveSemanticLineage(eventsOrMap?: SemanticLineageMap | readonly (SemanticLineageEvent | CreateSemanticLineageEventInput)[], query?: SemanticLineageResolutionQuery | SemanticAnchor | string, options?: { readonly id?: string; readonly generatedAt?: number | string; readonly maxDepth?: number; readonly metadata?: Record<string, unknown> }): SemanticLineageResolution;
 export declare function resolveSemanticLineageBatch(eventsOrMap?: SemanticLineageMap | readonly (SemanticLineageEvent | CreateSemanticLineageEventInput)[], queries?: readonly (SemanticLineageResolutionQuery | SemanticAnchor | string)[], options?: { readonly generatedAt?: number | string; readonly maxDepth?: number; readonly metadata?: Record<string, unknown> }): readonly SemanticLineageResolution[];

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from './declarations/semantic-merge-conflicts.js';
 export * from './declarations/semantic-lineage.js';
 export * from './declarations/semantic-history.js';
 export * from './declarations/semantic-patch-bundle.js';
+export * from './declarations/bidirectional-target-change.js';
 export * from './declarations/semantic-impact.js';
 export * from './declarations/semantic-sidecar.js';
 export * from './declarations/native-diff.js';

package/dist/index.js

@@ -4,6 +4,7 @@ export { compileFrontierDocument } from './internal/index-impl/compileFrontierDo
 export { compileFrontierSource } from './internal/index-impl/compileFrontierSource.js';
 export { compileNativeSource } from './internal/index-impl/compileNativeSource.js';
 export { createBabelNativeImporterAdapter } from './internal/index-impl/createBabelNativeImporterAdapter.js';
+export { createBidirectionalTargetChangeRecord } from './internal/index-impl/createBidirectionalTargetChangeRecord.js';
 export { createClangAstNativeImporterAdapter } from './internal/index-impl/createClangAstNativeImporterAdapter.js';
 export { createCSharpRoslynNativeImporterAdapter } from './internal/index-impl/createCSharpRoslynNativeImporterAdapter.js';
 export { createEstreeNativeImporterAdapter } from './internal/index-impl/createEstreeNativeImporterAdapter.js';
@@ -45,6 +46,7 @@ export { getNativeParserAstFormatProfile } from './internal/index-impl/getNative
 export { importExternalSemanticIndex } from './internal/index-impl/importExternalSemanticIndex.js';
 export { importNativeProject } from './internal/index-impl/importNativeProject.js';
 export { importNativeSource } from './internal/index-impl/importNativeSource.js';
+export { inferSemanticLineageEvents } from './internal/index-impl/inferSemanticLineageEvents.js';
 export { createLanguageAdapterPackageContract, getLanguageAdapterPackageContract, LanguageAdapterPackageContracts, LanguageAdapterPackageReleaseReadinessStatuses, queryLanguageAdapterPackageContracts, summarizeLanguageAdapterPackageContracts } from './language-adapter-package-contracts.js';
 export { NativeImportFeatureEvidencePolicies } from './internal/index-impl/NativeImportFeatureEvidencePolicies.js';
 export { NativeImportLanguageProfiles } from './coverage-matrix-profiles.js';

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

@@ -0,0 +1,198 @@
+import {
+  idFragment,
+  maxSemanticMergeReadiness,
+  uniqueRecordsById,
+  uniqueStrings
+} from '../../native-import-utils.js';
+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 resolvedAnchors = candidateAnchors.flatMap((anchor) => resolveAnchor(anchor, context.lineage));
+  const status = matchStatus(candidateAnchors, resolvedAnchors);
+  const reasonCodes = uniqueStrings([
+    explicit ? 'explicit-anchor-mapping' : 'inferred-by-symbol-name',
+    status === 'unmatched' ? 'source-anchor-not-found' : undefined,
+    status === 'ambiguous' ? 'source-anchor-ambiguous' : undefined,
+    status === 'deleted' ? 'source-anchor-deleted' : undefined,
+    'human-source-port-required'
+  ]);
+  return {
+    kind: 'frontier.lang.bidirectionalTargetChangeSourceAnchorMatch',
+    version: 1,
+    id: `source_anchor_match_${idFragment(context.id)}_${context.index + 1}`,
+    targetRegion: compactRegion(context.region),
+    sourceAnchors: resolvedAnchors.map((entry) => entry.anchor),
+    lineageResolutions: uniqueRecordsById(resolvedAnchors.map((entry) => entry.resolution).filter(Boolean)),
+    status,
+    confidence: status === 'matched' && explicit ? 0.8 : status === 'matched' ? 0.58 : undefined,
+    reasonCodes,
+    reviewRequired: true,
+    autoMergeClaim: false,
+    semanticEquivalenceClaim: false,
+    conflictKeys: uniqueStrings([
+      context.region.conflictKey,
+      context.region.key,
+      ...resolvedAnchors.map((entry) => entry.anchor?.key),
+      status === 'unmatched' ? `target:${context.region.sourcePath ?? context.region.language ?? 'unknown'}` : undefined
+    ])
+  };
+}
+
+export function classifyBidirectionalReadiness(targetChangeSet, source, matches) {
+  let readiness = maxSemanticMergeReadiness(targetChangeSet.readiness, 'needs-review');
+  if (!source) readiness = 'blocked';
+  if (matches.some((match) => match.status === 'deleted')) readiness = 'blocked';
+  if (matches.every((match) => match.status === 'unmatched') && matches.length > 0) readiness = 'blocked';
+  return readiness;
+}
+
+export function sourceRegionsForMatch(match, readiness) {
+  const anchors = match.sourceAnchors.length ? match.sourceAnchors : [undefined];
+  return anchors.map((anchor, index) => compactRecord({
+    id: `source_port_region_${idFragment(match.id)}_${index + 1}`,
+    key: anchor?.key ?? `unmapped-target#${match.targetRegion.key ?? match.targetRegion.id}`,
+    conflictKey: anchor?.key ?? match.targetRegion.conflictKey ?? match.targetRegion.key,
+    changeKind: match.targetRegion.changeKind,
+    regionKind: anchor?.kind ?? match.targetRegion.regionKind,
+    granularity: 'symbol',
+    language: anchor?.language,
+    sourcePath: anchor?.sourcePath,
+    sourceHash: anchor?.sourceHash,
+    symbolId: anchor?.symbolId,
+    symbolName: anchor?.symbolName,
+    sourceSpan: anchor?.sourceSpan,
+    admission: {
+      readiness,
+      action: 'review-port-from-target-change',
+      reasonCodes: match.reasonCodes,
+      conflictKeys: match.conflictKeys
+    },
+    metadata: {
+      bidirectionalTargetChange: {
+        matchId: match.id,
+        targetRegion: match.targetRegion,
+        lineageResolutionIds: match.lineageResolutions.map((resolution) => resolution.id),
+        reviewRequired: true,
+        autoMergeClaim: false,
+        semanticEquivalenceClaim: false
+      }
+    }
+  }));
+}
+
+export function createBidirectionalEvidence(context) {
+  return {
+    id: context.input.evidenceId ?? `evidence_${idFragment(context.id)}_bidirectional_target_change`,
+    kind: 'semantic-merge',
+    status: 'passed',
+    path: context.source?.sourcePath ?? context.targetChangeSet.sourcePath,
+    summary: `Mapped ${context.targetChangeSet.changedRegions.length} target changed region(s) to ${matchedCount(context.sourceAnchorMatches)} source anchor match(es).`,
+    metadata: {
+      schema: 'frontier.lang.bidirectionalTargetChangeEvidence.v1',
+      sourceImportId: context.source?.id,
+      targetChangeSetId: context.targetChangeSet.id,
+      targetPatchId: context.targetChangeSet.patch?.id,
+      sourceAnchorMatchIds: context.sourceAnchorMatches.map((match) => match.id),
+      readiness: context.readiness,
+      reasons: context.reasons,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  };
+}
+
+export function anchorsFromSourceSidecar(sidecar, source) {
+  return uniqueRecordsById((sidecar.ownershipRegions ?? []).map((region) => compactRecord({
+    id: region.id,
+    key: region.key,
+    kind: region.regionKind,
+    language: region.language ?? source?.language,
+    sourcePath: region.sourcePath ?? source?.sourcePath,
+    sourceHash: region.sourceHash ?? sourceHash(source),
+    symbolId: region.symbolId,
+    symbolName: region.symbolName,
+    sourceSpan: region.sourceSpan,
+    metadata: region.metadata
+  })));
+}
+
+export function sourceHash(source) {
+  return source?.nativeSource?.sourceHash ?? source?.nativeAst?.sourceHash ?? source?.sourceHash;
+}
+
+function explicitMappingForRegion(region, mappings) {
+  return mappings.find((mapping) => {
+    const targetKeys = uniqueStrings([
+      mapping.targetAnchorKey,
+      mapping.targetRegionKey,
+      mapping.targetConflictKey,
+      mapping.targetKey
+    ]);
+    if (targetKeys.some((key) => key === region.key || key === region.conflictKey || key === region.id)) return true;
+    if (mapping.targetSymbolName && mapping.targetSymbolName === (region.symbolName ?? region.name)) return true;
+    return mapping.targetSymbolId && mapping.targetSymbolId === region.symbolId;
+  });
+}
+
+function sourceAnchorsForMapping(mapping, sourceAnchors) {
+  const keys = uniqueStrings([mapping.sourceAnchorKey, mapping.sourceRegionKey, mapping.sourceConflictKey, mapping.sourceKey]);
+  const matches = sourceAnchors.filter((anchor) => keys.includes(anchor.key) || keys.includes(anchor.id));
+  if (matches.length) return matches;
+  if (mapping.sourceSymbolName) return sourceAnchors.filter((anchor) => anchor.symbolName === mapping.sourceSymbolName);
+  if (mapping.sourceSymbolId) return sourceAnchors.filter((anchor) => anchor.symbolId === mapping.sourceSymbolId);
+  return [];
+}
+
+function sourceAnchorsByName(region, sourceAnchors) {
+  const names = uniqueStrings([region.symbolName, region.name, region.metadata?.changedRegionProjection?.region?.symbolName]);
+  if (names.length === 0) return [];
+  return sourceAnchors.filter((anchor) => names.includes(anchor.symbolName));
+}
+
+function resolveAnchor(anchor, lineage) {
+  if (!anchor) return [];
+  const resolution = array(lineage).length ? resolveSemanticLineage(lineage, { anchorKey: anchor.key }) : undefined;
+  if (!resolution || resolution.status === 'unchanged') return [{ anchor, resolution }];
+  if (resolution.status === 'deleted') return [{ anchor, resolution }];
+  if (resolution.currentAnchors.length === 0) return [{ anchor, resolution }];
+  return resolution.currentAnchors.map((current) => ({ anchor: { ...anchor, ...current }, resolution }));
+}
+
+function matchStatus(originalAnchors, resolvedAnchors) {
+  if (originalAnchors.length === 0 || resolvedAnchors.length === 0) return 'unmatched';
+  if (resolvedAnchors.some((entry) => entry.resolution?.status === 'deleted')) return 'deleted';
+  if (resolvedAnchors.length > 1 || resolvedAnchors.some((entry) => entry.resolution?.status === 'ambiguous')) return 'ambiguous';
+  return 'matched';
+}
+
+function matchedCount(matches) {
+  return matches.filter((match) => match.status === 'matched').length;
+}
+
+function compactRegion(region) {
+  return compactRecord({
+    id: region.id,
+    key: region.key,
+    conflictKey: region.conflictKey,
+    changeKind: region.changeKind,
+    regionKind: region.regionKind,
+    language: region.language,
+    sourcePath: region.sourcePath,
+    sourceHash: region.sourceHash,
+    symbolId: region.symbolId,
+    symbolName: region.symbolName ?? region.name,
+    sourceSpan: region.sourceSpan
+  });
+}
+
+function array(value) {
+  return value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
+}
+
+function compactRecord(value) {
+  return Object.fromEntries(Object.entries(value ?? {}).filter(([, entry]) => entry !== undefined && (!Array.isArray(entry) || entry.length > 0)));
+}

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

@@ -0,0 +1,169 @@
+import {
+  idFragment,
+  uniqueStrings
+} from '../../native-import-utils.js';
+import { createSemanticImportSidecar } from './createSemanticImportSidecar.js';
+import { createSemanticPatchBundleRecord } from './semanticPatchBundleRecords.js';
+import { createSemanticHistoryRecord } from './semanticHistoryRecords.js';
+import { diffNativeSourceImports } from './diffNativeSourceImports.js';
+import { normalizeNativeDiffImport } from './normalizeNativeDiffImport.js';
+import {
+  anchorsFromSourceSidecar,
+  classifyBidirectionalReadiness,
+  createBidirectionalEvidence,
+  matchTargetRegion,
+  sourceHash,
+  sourceRegionsForMatch
+} from './bidirectionalTargetChangeRecordInternals.js';
+
+export function createBidirectionalTargetChangeRecord(input = {}, options = {}) {
+  const source = normalizeNativeDiffImport(
+    input.source ?? input.sourceImport ?? input.baseSource,
+    { language: input.sourceLanguage, sourcePath: input.sourcePath, parser: input.sourceParser },
+    'source'
+  );
+  const targetChangeSet = input.targetChangeSet ?? diffNativeSourceImports({
+    id: input.targetChangeSetId ?? input.id,
+    language: input.targetLanguage ?? input.language,
+    sourcePath: input.targetPath ?? input.sourcePath,
+    before: input.baseTarget ?? input.beforeTarget ?? input.before,
+    after: input.editedTarget ?? input.afterTarget ?? input.after,
+    evidenceId: input.targetEvidenceId,
+    patchId: input.targetPatchId,
+    mergeCandidateId: input.targetMergeCandidateId,
+    metadata: { direction: 'target-to-source', ...(input.targetMetadata ?? {}) }
+  });
+  const id = input.id ?? `bidirectional_target_change_${idFragment([
+    source?.sourcePath,
+    targetChangeSet.sourcePath,
+    targetChangeSet.id
+  ].filter(Boolean).join('_'))}`;
+  const sourceSidecar = source ? createSemanticImportSidecar(source, {
+    id: `sidecar_source_${idFragment(id)}`,
+    generatedAt: input.generatedAt,
+    regionPrefix: input.sourceRegionPrefix
+  }) : undefined;
+  const sourceAnchors = sourceSidecar ? anchorsFromSourceSidecar(sourceSidecar, source) : [];
+  const mappings = array(input.sourceAnchorMappings ?? input.anchorMappings);
+  const lineage = input.lineage ?? input.lineageEvents ?? input.lineageMap ?? [];
+  const sourceAnchorMatches = targetChangeSet.changedRegions.map((region, index) => matchTargetRegion({
+    id,
+    region,
+    index,
+    source,
+    sourceAnchors,
+    mappings,
+    lineage
+  }));
+  const readiness = classifyBidirectionalReadiness(targetChangeSet, source, sourceAnchorMatches);
+  const reasons = uniqueStrings([
+    'source-port-review-required',
+    'target-change-is-merge-evidence-not-proof',
+    ...array(targetChangeSet.reasons),
+    ...sourceAnchorMatches.flatMap((match) => match.reasonCodes)
+  ]);
+  const evidence = [createBidirectionalEvidence({
+    id,
+    input,
+    source,
+    targetChangeSet,
+    sourceAnchorMatches,
+    readiness,
+    reasons
+  })];
+  const sourceChangedRegions = sourceAnchorMatches.flatMap((match) => sourceRegionsForMatch(match, readiness));
+  const sourcePatchBundle = createSemanticPatchBundleRecord({
+    id: `${id}_source_port_projection`,
+    language: source?.language,
+    sourcePath: source?.sourcePath,
+    baseHash: sourceHash(source),
+    changedRegions: sourceChangedRegions,
+    evidence,
+    readiness,
+    reasons,
+    conflictKeys: uniqueStrings(sourceAnchorMatches.flatMap((match) => match.conflictKeys)),
+    metadata: {
+      projectionOnly: true,
+      targetChangeSetId: targetChangeSet.id,
+      targetPatchId: targetChangeSet.patch?.id,
+      targetMergeCandidateId: targetChangeSet.mergeCandidate?.id
+    }
+  }, {
+    id: input.sourcePatchBundleId ?? `semantic_patch_bundle_${idFragment(id)}_source_port`,
+    patchId: targetChangeSet.patch?.id,
+    mergeCandidateId: targetChangeSet.mergeCandidate?.id,
+    admission: { status: readiness === 'blocked' ? 'blocked' : 'needs-review', readiness },
+    metadata: {
+      source: 'createBidirectionalTargetChangeRecord',
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  });
+  const historyRecord = createSemanticHistoryRecord({
+    id: input.historyRecordId ?? `semantic_history_${idFragment(id)}_target_change`,
+    importResult: source,
+    language: source?.language,
+    sourcePath: source?.sourcePath,
+    baseHash: sourceHash(source),
+    targetHash: sourceHash(source),
+    ownershipRegions: sourceChangedRegions,
+    semanticCandidates: [targetChangeSet.mergeCandidate].filter(Boolean),
+    evidence,
+    evidenceIds: evidence.map((record) => record.id),
+    patchAncestry: targetChangeSet.patch ? [{
+      patchId: targetChangeSet.patch.id,
+      baseHash: targetChangeSet.beforeHash,
+      targetHash: targetChangeSet.afterHash,
+      conflictKeys: targetChangeSet.mergeCandidate?.conflictKeys,
+      metadata: { direction: 'target-to-source' }
+    }] : [],
+    admission: { status: readiness === 'blocked' ? 'blocked' : 'needs-review', readiness, reasonCodes: reasons },
+    replayLinks: targetChangeSet.patch ? [{
+      id: `replay_${idFragment(targetChangeSet.patch.id)}`,
+      kind: 'patch',
+      path: targetChangeSet.patch.id
+    }] : [],
+    metadata: {
+      bidirectionalTargetChangeId: id,
+      sourcePatchBundleId: sourcePatchBundle.id,
+      targetChangeSetId: targetChangeSet.id,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  }, options);
+  return {
+    kind: 'frontier.lang.bidirectionalTargetChangeRecord',
+    version: 1,
+    id,
+    sourceLanguage: source?.language,
+    targetLanguage: targetChangeSet.language,
+    sourcePath: source?.sourcePath,
+    targetPath: targetChangeSet.sourcePath,
+    sourceImport: source,
+    targetChangeSet,
+    sourceAnchorMatches,
+    sourcePatchBundle,
+    historyRecord,
+    evidence,
+    readiness,
+    reasons,
+    summary: {
+      targetChangedRegions: targetChangeSet.changedRegions.length,
+      sourceAnchorMatches: sourceAnchorMatches.filter((match) => match.status === 'matched').length,
+      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
+    },
+    metadata: {
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reviewRequired: true,
+      ...input.metadata
+    }
+  };
+}
+
+function array(value) {
+  return value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
+}

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

@@ -1,5 +1,6 @@
 import{idFragment,maxSemanticMergeReadiness,uniqueByLossId,uniqueRecordsById,uniqueStrings}from'../../native-import-utils.js';import{createPatch,createSemanticMergeCandidateRecord}from'@shapeshift-labs/frontier-lang-kernel';
 import{attachNativeChangeRegionProjectionMetadata}from'./attachNativeChangeRegionProjectionMetadata.js';import{classifyNativeSourceMergeConflicts}from'./semanticMergeConflicts.js';import{createSemanticImportSidecar}from'./createSemanticImportSidecar.js';import{diffNativeOwnershipRegions}from'./diffNativeOwnershipRegions.js';import{diffNativeSymbols}from'./diffNativeSymbols.js';import{fileLevelNativeChangeRegion}from'./fileLevelNativeChangeRegion.js';import{mapDiffSymbols}from'./mapDiffSymbols.js';import{nativeChangeSpans}from'./nativeChangeSpans.js';import{nativeChangeTouchedSymbol}from'./nativeChangeTouchedSymbol.js';import{nativeImportReadiness}from'./nativeImportReadiness.js';import{nativeSourceChangeReasons}from'./nativeSourceChangeReasons.js';import{nativeSourceChangeSummary}from'./nativeSourceChangeSummary.js';import{normalizeNativeDiffImport}from'./normalizeNativeDiffImport.js';import{summarizeNativeChangedRegionProjections}from'./summarizeNativeChangedRegionProjections.js';
+import{inferSemanticLineageEvents}from'./inferSemanticLineageEvents.js';
 import{decorateSemanticMergeCandidateForAdmission}from'./semanticMergeCandidateRecords.js';
 export function diffNativeSourceImports(input) {
   const before = normalizeNativeDiffImport(input.before, input, 'before');
@@ -39,6 +40,17 @@ export function diffNativeSourceImports(input) {
     reasons
   });
   const changedRegionProjectionSummary = summarizeNativeChangedRegionProjections(changedRegions);
+  const lineageInference = inferSemanticLineageEvents({
+    before,
+    after,
+    id: `${idPart}_native_source_diff`,
+    language,
+    sourcePath,
+    generatedAt: input.generatedAt,
+    regionPrefix: input.regionPrefix,
+    evidenceId: `evidence_${idPart}_semantic_lineage_inference`,
+    metadata: { source: 'diffNativeSourceImports' }
+  });
   const evidence = [{
     id: input.evidenceId ?? `evidence_${idPart}_native_source_diff`,
     kind: 'import',
@@ -54,7 +66,8 @@ export function diffNativeSourceImports(input) {
       addedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'added').length,
       removedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'removed').length,
       modifiedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'modified').length,
-      changedRegionProjectionSummary
+      changedRegionProjectionSummary,
+      semanticLineageInferenceSummary: lineageInference.summary
     }
   }];
   const conflictKeys = uniqueStrings([
@@ -148,6 +161,7 @@ export function diffNativeSourceImports(input) {
     patch,
     mergeCandidate,
     evidence,
+    lineageInference,
     readiness,
     reasons,
     sourceMaps: uniqueRecordsById([...(before?.sourceMaps ?? []), ...(after?.sourceMaps ?? [])]),
@@ -160,6 +174,7 @@ export function diffNativeSourceImports(input) {
       beforeImportContract: before?.metadata?.importResultContract,
       afterImportContract: after?.metadata?.importResultContract,
       changedRegionProjectionSummary,
+      semanticLineageInferenceSummary: lineageInference.summary,
       semanticMergeConflictSummary: mergeConflictProfile.conflictSummary,
       ...input.metadata
     }

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

@@ -0,0 +1,214 @@
+import { idFragment, maxSemanticMergeReadiness, uniqueStrings } from '../../native-import-utils.js';
+import { createSemanticImportSidecar } from './createSemanticImportSidecar.js';
+import { createSemanticAnchor, createSemanticLineageEvent, createSemanticLineageMap } from './semanticLineageRecords.js';
+import { matchExactAnchors, matchLineageCandidates, symbolSummary } from './semanticLineageInferenceMatching.js';
+import { mapDiffSymbols } from './mapDiffSymbols.js';
+import { normalizeNativeDiffImport } from './normalizeNativeDiffImport.js';
+
+const DEFAULT_MIN_CONFIDENCE = 0.74;
+const DEFAULT_AMBIGUITY_MARGIN = 0.08;
+
+export function inferSemanticLineageEvents(input = {}, options = {}) {
+  const before = normalizeNativeDiffImport(input.before, input, 'before');
+  const after = normalizeNativeDiffImport(input.after, input, 'after');
+  if (!before && !after) throw new Error('inferSemanticLineageEvents requires before or after native source input');
+  const language = input.language ?? after?.language ?? before?.language;
+  const sourcePath = input.sourcePath ?? after?.sourcePath ?? before?.sourcePath;
+  const beforeHash = before?.nativeSource?.sourceHash ?? before?.nativeAst?.sourceHash ?? before?.sourceHash;
+  const afterHash = after?.nativeSource?.sourceHash ?? after?.nativeAst?.sourceHash ?? after?.sourceHash;
+  const idPart = idFragment(input.id ?? sourcePath ?? language ?? 'semantic_lineage_inference');
+  const beforeSidecar = before ? createSemanticImportSidecar(before, { id: `lineage_sidecar_before_${idPart}`, generatedAt: input.generatedAt, regionPrefix: input.regionPrefix }) : undefined;
+  const afterSidecar = after ? createSemanticImportSidecar(after, { id: `lineage_sidecar_after_${idPart}`, generatedAt: input.generatedAt, regionPrefix: input.regionPrefix }) : undefined;
+  const beforeSymbols = [...mapDiffSymbols(before, beforeSidecar).values()].map((symbol) => lineageSymbol(symbol, before)).filter((symbol) => symbol.anchor?.key);
+  const afterSymbols = [...mapDiffSymbols(after, afterSidecar).values()].map((symbol) => lineageSymbol(symbol, after)).filter((symbol) => symbol.anchor?.key);
+  const exact = matchExactAnchors(beforeSymbols, afterSymbols);
+  const candidates = matchLineageCandidates(exact.unmatchedBefore, exact.unmatchedAfter, input, {
+    minConfidence: minConfidence(input),
+    ambiguityMargin: ambiguityMargin(input)
+  });
+  const deleted = input.includeDeleted === false
+    ? []
+    : candidates.unmatchedBefore.map((symbol) => deletedEvent(symbol, input, options, { before, after }));
+  const events = [...candidates.events, ...deleted].filter(Boolean);
+  const evidence = [lineageInferenceEvidence({
+    input,
+    idPart,
+    sourcePath,
+    language,
+    before,
+    after,
+    beforeHash,
+    afterHash,
+    exact,
+    candidates,
+    deleted,
+    events
+  })];
+  const lineageMap = createSemanticLineageMap(events, {
+    id: input.lineageMapId ?? `semantic_lineage_map_${idPart}`,
+    generatedAt: input.generatedAt
+  });
+  const readiness = inferenceReadiness({ events, deleted, ambiguous: candidates.ambiguous, added: candidates.unmatchedAfter }, input);
+  return {
+    kind: 'frontier.lang.semanticLineageInference',
+    version: 1,
+    id: input.id ?? `semantic_lineage_inference_${idPart}`,
+    language,
+    sourcePath,
+    beforeImportId: before?.id,
+    afterImportId: after?.id,
+    beforeHash,
+    afterHash,
+    events,
+    lineageMap,
+    evidence,
+    unmatched: {
+      removed: candidates.unmatchedBefore.map(symbolSummary),
+      added: candidates.unmatchedAfter.map(symbolSummary),
+      ambiguous: candidates.ambiguous
+    },
+    summary: {
+      beforeSymbols: beforeSymbols.length,
+      afterSymbols: afterSymbols.length,
+      unchangedAnchors: exact.matched.length,
+      inferredEvents: events.length,
+      moved: events.filter((event) => event.eventKind === 'moved').length,
+      renamed: events.filter((event) => event.eventKind === 'renamed').length,
+      deleted: deleted.length,
+      ambiguous: candidates.ambiguous.length,
+      unmatchedAdded: candidates.unmatchedAfter.length,
+      minConfidence: minConfidence(input),
+      ambiguityMargin: ambiguityMargin(input)
+    },
+    readiness,
+    reasons: inferenceReasons({ events, deleted, ambiguous: candidates.ambiguous, added: candidates.unmatchedAfter, readiness }),
+    metadata: {
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false,
+      reviewRequired: true,
+      beforeSidecarId: beforeSidecar?.id,
+      afterSidecarId: afterSidecar?.id,
+      note: 'Inferred lineage is refactoring-aware merge evidence, not proof of semantic equivalence.',
+      ...input.metadata,
+      ...options.metadata
+    }
+  };
+}
+
+function deletedEvent(symbol, input, options, context) {
+  return createSemanticLineageEvent({
+    id: `lineage_deleted_${idFragment(firstString(input.id, symbol.anchor.key))}`,
+    createdAt: input.generatedAt,
+    eventKind: 'deleted',
+    from: symbol.anchor,
+    confidence: deletedConfidence(input, options, context),
+    actor: input.actor,
+    actorId: input.actorId,
+    actorRole: input.actorRole ?? 'semantic-lineage-inference',
+    evidenceIds: [input.evidenceId ?? `evidence_${idFragment(input.id ?? symbol.anchor.key)}_lineage_inference`],
+    conflictKeys: [symbol.anchor.key],
+    metadata: {
+      inferred: true,
+      algorithm: 'frontier.semantic-lineage-inference.v1',
+      reasonCodes: ['anchor-removed-from-after-import'],
+      deletionEvidenceScope: deletionEvidenceScope(context),
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  });
+}
+
+function deletedConfidence(input, options, context) {
+  if (options.deletedConfidence !== undefined) return options.deletedConfidence;
+  if (input.deletedConfidence !== undefined) return input.deletedConfidence;
+  return deletionEvidenceScope(context) === 'same-source-file' ? 0.8 : 0.55;
+}
+
+function deletionEvidenceScope(context) {
+  const beforePath = context.before?.sourcePath ?? context.before?.nativeSource?.sourcePath;
+  const afterPath = context.after?.sourcePath ?? context.after?.nativeSource?.sourcePath;
+  return beforePath && afterPath && beforePath === afterPath ? 'same-source-file' : 'partial-or-moved-scope';
+}
+
+function lineageSymbol(symbol, imported) {
+  const anchor = createSemanticAnchor({
+    key: symbol.ownershipKey ?? symbol.key ?? symbol.id,
+    kind: symbol.ownershipRegionKind ?? symbol.kind,
+    language: symbol.language ?? imported?.language,
+    sourcePath: symbol.sourcePath ?? imported?.sourcePath,
+    sourceHash: symbol.sourceHash ?? imported?.nativeSource?.sourceHash ?? imported?.nativeAst?.sourceHash,
+    symbolId: symbol.id,
+    symbolName: symbol.name,
+    signatureHash: symbol.signatureHash,
+    bodyHash: symbol.spanHash,
+    sourceSpan: symbol.sourceSpan,
+    metadata: {
+      nativeAstNodeId: symbol.nativeAstNodeId,
+      semanticOccurrenceId: symbol.semanticOccurrenceId,
+      sourceMapMappingId: symbol.sourceMapMappingId,
+      ownershipRegionId: symbol.ownershipRegionId,
+      ownershipRegionKind: symbol.ownershipRegionKind
+    }
+  }, { language: imported?.language, sourcePath: imported?.sourcePath });
+  return { ...symbol, anchor };
+}
+
+function lineageInferenceEvidence(input) {
+  return {
+    id: input.input.evidenceId ?? `evidence_${input.idPart}_lineage_inference`,
+    kind: 'import',
+    status: 'passed',
+    path: input.sourcePath,
+    summary: `Inferred ${input.events.length} semantic lineage event(s) from ${input.before?.id ?? 'before'} to ${input.after?.id ?? 'after'}.`,
+    metadata: {
+      algorithm: 'frontier.semantic-lineage-inference.v1',
+      beforeImportId: input.before?.id,
+      afterImportId: input.after?.id,
+      beforeHash: input.beforeHash,
+      afterHash: input.afterHash,
+      language: input.language,
+      unchangedAnchors: input.exact.matched.length,
+      inferredEvents: input.events.length,
+      deleted: input.deleted.length,
+      ambiguous: input.candidates.ambiguous.length,
+      unmatchedAdded: input.candidates.unmatchedAfter.length,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  };
+}
+
+function inferenceReadiness(input, options) {
+  if (input.ambiguous.length) return 'blocked';
+  let readiness = 'ready';
+  if (input.events.length || input.added.length) readiness = maxSemanticMergeReadiness(readiness, 'needs-review');
+  return maxSemanticMergeReadiness(readiness, options.readiness ?? 'ready');
+}
+
+function inferenceReasons(input) {
+  return uniqueStrings([
+    input.events.length ? 'semantic-lineage-inferred' : undefined,
+    input.deleted.length ? 'deleted-anchor-lineage-inferred' : undefined,
+    input.added.length ? 'unmatched-added-anchor-review' : undefined,
+    input.ambiguous.length ? 'ambiguous-lineage-candidates' : undefined,
+    input.readiness === 'blocked' ? 'lineage-inference-blocked' : undefined,
+    'no-auto-merge-claim'
+  ].filter(Boolean));
+}
+
+function minConfidence(input) {
+  return numeric(input.minConfidence, DEFAULT_MIN_CONFIDENCE);
+}
+
+function ambiguityMargin(input) {
+  return numeric(input.ambiguityMargin, DEFAULT_AMBIGUITY_MARGIN);
+}
+
+function numeric(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function firstString(...values) {
+  return values.map((value) => value === undefined || value === null ? '' : String(value)).find(Boolean);
+}

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

@@ -0,0 +1,167 @@
+import { idFragment, uniqueStrings } from '../../native-import-utils.js';
+import { createSemanticLineageEvent } from './semanticLineageRecords.js';
+
+export function matchExactAnchors(beforeSymbols, afterSymbols) {
+  const afterByKey = new Map(afterSymbols.map((symbol) => [symbol.anchor.key, symbol]));
+  const matched = [];
+  const unmatchedBefore = [];
+  const matchedAfterKeys = new Set();
+  for (const before of beforeSymbols) {
+    const after = afterByKey.get(before.anchor.key);
+    if (after && anchorsSameLocation(before.anchor, after.anchor)) {
+      matched.push({ before: symbolSummary(before), after: symbolSummary(after) });
+      matchedAfterKeys.add(after.anchor.key);
+    } else {
+      unmatchedBefore.push(before);
+    }
+  }
+  return {
+    matched,
+    unmatchedBefore,
+    unmatchedAfter: afterSymbols.filter((symbol) => !matchedAfterKeys.has(symbol.anchor.key))
+  };
+}
+
+export function matchLineageCandidates(beforeSymbols, afterSymbols, input, options) {
+  const claimedAfter = new Set();
+  const events = [];
+  const ambiguous = [];
+  const unmatchedBefore = [];
+  for (const before of beforeSymbols) {
+    const ranked = afterSymbols
+      .filter((after) => !claimedAfter.has(after.anchor.key))
+      .map((after) => ({ after, score: scoreLineagePair(before, after) }))
+      .filter((candidate) => candidate.score.confidence >= options.minConfidence)
+      .sort(compareCandidateScores);
+    const best = ranked[0];
+    const runnerUp = ranked[1];
+    if (!best) {
+      unmatchedBefore.push(before);
+      continue;
+    }
+    if (runnerUp && best.score.confidence - runnerUp.score.confidence < options.ambiguityMargin) {
+      ambiguous.push(ambiguousMatch(before, ranked));
+      unmatchedBefore.push(before);
+      continue;
+    }
+    claimedAfter.add(best.after.anchor.key);
+    events.push(inferredEvent(before, best.after, best.score, input));
+  }
+  return {
+    events,
+    ambiguous,
+    unmatchedBefore,
+    unmatchedAfter: afterSymbols.filter((symbol) => !claimedAfter.has(symbol.anchor.key))
+  };
+}
+
+export function symbolSummary(symbol) {
+  return {
+    key: symbol.anchor.key,
+    id: symbol.id,
+    name: symbol.name,
+    kind: symbol.kind,
+    language: symbol.language,
+    sourcePath: symbol.anchor.sourcePath,
+    sourceHash: symbol.anchor.sourceHash,
+    sourceSpan: symbol.anchor.sourceSpan,
+    signatureHash: symbol.signatureHash,
+    bodyHash: symbol.spanHash,
+    ownershipRegionKind: symbol.ownershipRegionKind
+  };
+}
+
+function ambiguousMatch(before, ranked) {
+  return {
+    before: symbolSummary(before),
+    candidates: ranked.slice(0, 4).map((candidate) => ({
+      after: symbolSummary(candidate.after),
+      confidence: candidate.score.confidence,
+      reasons: candidate.score.reasons
+    })),
+    reasonCodes: ['ambiguous-lineage-candidates']
+  };
+}
+
+function compareCandidateScores(left, right) {
+  return right.score.confidence - left.score.confidence
+    || String(left.after.anchor.key).localeCompare(String(right.after.anchor.key));
+}
+
+function inferredEvent(before, after, score, input) {
+  const nameChanged = before.anchor.symbolName
+    && after.anchor.symbolName
+    && before.anchor.symbolName !== after.anchor.symbolName;
+  const pathChanged = before.anchor.sourcePath !== after.anchor.sourcePath;
+  const spanMoved = JSON.stringify(before.anchor.sourceSpan ?? null) !== JSON.stringify(after.anchor.sourceSpan ?? null);
+  const eventKind = nameChanged ? 'renamed' : 'moved';
+  return createSemanticLineageEvent({
+    id: `lineage_inferred_${idFragment(firstString(input.id, before.anchor.key))}_${idFragment(after.anchor.key)}`,
+    createdAt: input.generatedAt,
+    eventKind,
+    from: before.anchor,
+    to: after.anchor,
+    confidence: score.confidence,
+    actor: input.actor,
+    actorId: input.actorId,
+    actorRole: input.actorRole ?? 'semantic-lineage-inference',
+    operationId: input.operationId,
+    deps: input.deps,
+    heads: input.heads,
+    stateVector: input.stateVector,
+    evidenceIds: [input.evidenceId ?? `evidence_${idFragment(input.id ?? before.anchor.key)}_lineage_inference`],
+    signatureHashMatch: score.reasons.includes('signature-hash-match'),
+    bodyHashMatch: score.reasons.includes('body-hash-match'),
+    pathMatch: !pathChanged,
+    sourceSpanMoved: pathChanged || spanMoved,
+    conflictKeys: uniqueStrings([before.anchor.key, after.anchor.key]),
+    metadata: {
+      inferred: true,
+      algorithm: 'frontier.semantic-lineage-inference.v1',
+      reasonCodes: score.reasons,
+      moved: pathChanged || spanMoved,
+      renamed: nameChanged,
+      autoMergeClaim: false,
+      semanticEquivalenceClaim: false
+    }
+  });
+}
+
+function scoreLineagePair(before, after) {
+  const reasons = [];
+  let score = 0;
+  const add = (value, reason) => {
+    score += value;
+    reasons.push(reason);
+  };
+  if (before.anchor.key && before.anchor.key === after.anchor.key) add(0.4, 'anchor-key-match');
+  if (before.name && before.name === after.name) add(0.28, 'symbol-name-match');
+  if (before.kind && before.kind === after.kind) add(0.12, 'symbol-kind-match');
+  if (before.signatureHash && before.signatureHash === after.signatureHash) add(0.52, 'signature-hash-match');
+  if (before.spanHash && before.spanHash === after.spanHash) add(0.22, 'body-hash-match');
+  if (before.anchor.kind && before.anchor.kind === after.anchor.kind) add(0.06, 'anchor-kind-match');
+  if (before.anchor.sourcePath && before.anchor.sourcePath === after.anchor.sourcePath) add(0.04, 'source-path-match');
+  if (sourceSpanRangeSame(before.anchor.sourceSpan, after.anchor.sourceSpan)) add(0.18, 'source-span-range-match');
+  if (before.ownershipRegionKind && before.ownershipRegionKind === after.ownershipRegionKind) add(0.04, 'ownership-kind-match');
+  if (before.nativeAstNodeId && before.nativeAstNodeId === after.nativeAstNodeId) add(0.06, 'native-node-id-match');
+  if (before.anchor.sourcePath !== after.anchor.sourcePath && (before.name === after.name || before.signatureHash === after.signatureHash)) add(0.04, 'source-path-moved');
+  return { confidence: Math.max(0, Math.min(1, Number(score.toFixed(3)))), reasons };
+}
+
+function anchorsSameLocation(before, after) {
+  return (before.sourcePath ?? '') === (after.sourcePath ?? '')
+    && JSON.stringify(before.sourceSpan ?? null) === JSON.stringify(after.sourceSpan ?? null);
+}
+
+function sourceSpanRangeSame(before, after) {
+  return before
+    && after
+    && before.startLine === after.startLine
+    && before.startColumn === after.startColumn
+    && before.endLine === after.endLine
+    && before.endColumn === after.endColumn;
+}
+
+function firstString(...values) {
+  return values.map((value) => value === undefined || value === null ? '' : String(value)).find(Boolean);
+}

package/package.json

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