@shapeshift-labs/frontier-lang-compiler 0.2.24 → 0.2.25

package/README.md

@@ -229,10 +229,12 @@ const changeSet = diffNativeSources({
 
 console.log(changeSet.changedSymbols[0]?.changeKind); // "modified"
 console.log(changeSet.changedRegions[0]?.conflictKey); // semantic ownership key
+console.log(changeSet.changedRegions[0]?.metadata.changedRegionProjection.reviewRequired); // true
+console.log(changeSet.metadata.changedRegionProjectionSummary.autoMergeClaims); // 0
 console.log(changeSet.mergeCandidate.readiness); // merge-admission classification
 ```
 
-Use `diffNativeSourceImports` when the worker or runner already produced `importNativeSource` results. Body-only edits that the lightweight scanner cannot anchor to a symbol are still reported as file-level changed regions instead of being silently treated as safe.
+Use `diffNativeSourceImports` when the worker or runner already produced `importNativeSource` results. Changed regions include a `metadata.changedRegionProjection` envelope with before/after source hashes, source-map links, ownership keys, readiness, and `autoMergeClaim: false` so swarm admission tools can score or port patches without treating semantic metadata as proof. Body-only edits that the lightweight scanner cannot anchor to a symbol are still reported as file-level changed regions instead of being silently treated as safe.
 
 Compile native source imports through the same reader/IR/writer facade that swarms use for sidecar evidence. Same-language targets preserve exact source when hashes match; cross-language targets emit declaration stubs until a real adapter provides stronger evidence:
 

package/bench/smoke.mjs

@@ -7,6 +7,7 @@ import {
   createProjectionTargetLossMatrix,
   createNativeSourcePreservation,
   createSemanticImportSidecar,
+  diffNativeSources,
   importExternalSemanticIndex,
   importNativeSource,
   projectNativeImportToSource,
@@ -165,6 +166,20 @@ const regionScanDurationMs = performance.now() - regionScanStart;
 const regionScanSymbols = regionScanImports.reduce((sum, entry) => sum + entry.imported.semanticIndex.symbols.length, 0);
 const regionScanOwnershipRegions = regionScanImports.reduce((sum, entry) => sum + entry.sidecar.ownershipRegions.length, 0);
 
+const changeProjectionStart = performance.now();
+const changeProjectionSets = [];
+for (let index = 0; index < 80; index += 1) {
+  changeProjectionSets.push(diffNativeSources({
+    language: 'javascript',
+    sourcePath: `src/change-projection-${index}.js`,
+    beforeSourceText: `export function changeProjection${index}() { return ${index}; }\n`,
+    afterSourceText: `export function changeProjection${index}() { return ${index + 1}; }\nexport const changeProjectionFlag${index} = true;\n`
+  }));
+}
+const changeProjectionDurationMs = performance.now() - changeProjectionStart;
+const changedRegionProjections = changeProjectionSets.reduce((sum, changeSet) => sum + changeSet.metadata.changedRegionProjectionSummary.withProjection, 0);
+const changedRegionProjectionSourceMapLinks = changeProjectionSets.reduce((sum, changeSet) => sum + changeSet.metadata.changedRegionProjectionSummary.sourceMapLinks, 0);
+
 const externalSemanticStart = performance.now();
 const externalSemanticImports = [];
 for (let index = 0; index < 100; index += 1) {
@@ -242,6 +257,10 @@ console.log(JSON.stringify({
   regionScanSymbols,
   regionScanOwnershipRegions,
   regionScanDurationMs: Number(regionScanDurationMs.toFixed(2)),
+  changeProjectionSets: changeProjectionSets.length,
+  changedRegionProjections,
+  changedRegionProjectionSourceMapLinks,
+  changeProjectionDurationMs: Number(changeProjectionDurationMs.toFixed(2)),
   externalSemanticImports: externalSemanticImports.length,
   externalSemanticSymbols,
   externalSemanticMappings,

package/dist/index.d.ts

@@ -786,6 +786,91 @@ export interface SemanticImportSidecarOptions {
 
 export type NativeSourceChangeKind = 'added' | 'removed' | 'modified' | 'unchanged';
 
+export interface NativeSourceChangeProjectionEndpoint {
+  readonly side: 'before' | 'after';
+  readonly importId?: string;
+  readonly sidecarId?: string;
+  readonly nativeSourceId?: string;
+  readonly nativeAstId?: string;
+  readonly semanticIndexId?: string;
+  readonly universalAstId?: string;
+  readonly sourcePath?: string;
+  readonly sourceHash?: string;
+  readonly sourcePreservationId?: string;
+  readonly exactSourceAvailable: boolean;
+  readonly ownershipRegionId?: string;
+  readonly ownershipKey?: string;
+  readonly ownershipRegionKind?: NativeImportRegionTaxonomyKind;
+  readonly sourceSpan?: SourceSpan;
+  readonly sourceMapIds: readonly string[];
+  readonly sourceMapMappingIds: readonly string[];
+}
+
+export interface NativeSourceChangeProjectionSourceMapLink {
+  readonly id: string;
+  readonly side: 'before' | 'after';
+  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 ownershipRegionId?: string;
+  readonly ownershipRegionKey?: string;
+  readonly ownershipRegionKind?: NativeImportRegionTaxonomyKind;
+}
+
+export interface NativeSourceChangeProjectionMetadata {
+  readonly schema: 'frontier.lang.changedRegionProjection.v1';
+  readonly id: string;
+  readonly reviewRequired: true;
+  readonly autoMergeClaim: false;
+  readonly changeKind: NativeSourceChangeKind;
+  readonly language?: FrontierSourceLanguage | string;
+  readonly sourcePath?: string;
+  readonly conflictKey: string;
+  readonly region: {
+    readonly id?: string;
+    readonly key?: string;
+    readonly kind?: NativeImportRegionTaxonomyKind;
+    readonly granularity?: string;
+    readonly precision?: string;
+    readonly sourceSpan?: SourceSpan;
+    readonly nativeAstNodeId?: string;
+    readonly symbolId?: string;
+    readonly symbolName?: string;
+    readonly symbolKind?: string;
+  };
+  readonly before?: NativeSourceChangeProjectionEndpoint;
+  readonly after?: NativeSourceChangeProjectionEndpoint;
+  readonly sourceMapLinks: readonly NativeSourceChangeProjectionSourceMapLink[];
+  readonly admission: {
+    readonly readiness: SemanticMergeReadiness;
+    readonly action: 'review-addition' | 'review-removal' | 'review-file' | 'review-port' | 'rerun-or-human-port' | string;
+    readonly reasons: readonly string[];
+    readonly conflictKeys: readonly string[];
+  };
+}
+
+export interface NativeSourceChangeProjectionSummary {
+  readonly schema: 'frontier.lang.changedRegionProjectionSummary.v1';
+  readonly total: number;
+  readonly withProjection: number;
+  readonly reviewRequired: number;
+  readonly autoMergeClaims: number;
+  readonly sourceMapLinks: number;
+  readonly byAction: Readonly<Record<string, number>>;
+  readonly byRegionKind: Readonly<Record<string, number>>;
+}
+
 export interface NativeSourceChangeSymbol {
   readonly changeKind: NativeSourceChangeKind;
   readonly key: string;
@@ -813,6 +898,9 @@ export interface NativeSourceChangeSymbol {
 export interface NativeSourceChangeRegion extends SemanticImportOwnershipRegion {
   readonly changeKind: NativeSourceChangeKind;
   readonly conflictKey: string;
+  readonly metadata?: SemanticImportOwnershipRegion['metadata'] & {
+    readonly changedRegionProjection?: NativeSourceChangeProjectionMetadata;
+  };
 }
 
 export interface NativeSourceChangeSummary {
@@ -875,7 +963,9 @@ export interface NativeSourceChangeSet {
   readonly semanticIndex?: SemanticIndexRecord;
   readonly losses: readonly NativeAstLossRecord[];
   readonly summary: NativeSourceChangeSummary;
-  readonly metadata?: Record<string, unknown>;
+  readonly metadata?: Record<string, unknown> & {
+    readonly changedRegionProjectionSummary?: NativeSourceChangeProjectionSummary;
+  };
 }
 
 export type NativeImporterAdapterExactness =

package/dist/index.js

@@ -3158,6 +3158,25 @@ export function diffNativeSourceImports(input) {
   if (sourceChanged && changedSymbols.length === 0 && changedRegions.length === 0) {
     changedRegions = [fileLevelNativeChangeRegion({ language, sourcePath, beforeHash, afterHash, before, after })];
   }
+  const readiness = maxSemanticMergeReadiness(
+    maxSemanticMergeReadiness(nativeImportReadiness(before), nativeImportReadiness(after)),
+    sourceChanged && changedSymbols.length === 0 ? 'needs-review' : 'ready'
+  );
+  const reasons = nativeSourceChangeReasons({ before, after, beforeHash, afterHash, changedSymbols, changedRegions, readiness });
+  changedRegions = attachNativeChangeRegionProjectionMetadata(changedRegions, {
+    before,
+    after,
+    beforeSidecar,
+    afterSidecar,
+    changedSymbols,
+    language,
+    sourcePath,
+    beforeHash,
+    afterHash,
+    readiness,
+    reasons
+  });
+  const changedRegionProjectionSummary = summarizeNativeChangedRegionProjections(changedRegions);
   const evidence = [{
     id: input.evidenceId ?? `evidence_${idPart}_native_source_diff`,
     kind: 'import',
@@ -3172,14 +3191,10 @@ export function diffNativeSourceImports(input) {
       sourceChanged,
       addedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'added').length,
       removedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'removed').length,
-      modifiedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'modified').length
+      modifiedSymbols: changedSymbols.filter((symbol) => symbol.changeKind === 'modified').length,
+      changedRegionProjectionSummary
     }
   }];
-  const readiness = maxSemanticMergeReadiness(
-    maxSemanticMergeReadiness(nativeImportReadiness(before), nativeImportReadiness(after)),
-    sourceChanged && changedSymbols.length === 0 ? 'needs-review' : 'ready'
-  );
-  const reasons = nativeSourceChangeReasons({ before, after, beforeHash, afterHash, changedSymbols, changedRegions, readiness });
   const conflictKeys = uniqueStrings([
     ...changedSymbols.map((symbol) => symbol.conflictKey),
     ...changedRegions.map((region) => region.conflictKey ?? region.key ?? region.id),
@@ -3230,7 +3245,8 @@ export function diffNativeSourceImports(input) {
       beforeImportId: before?.id,
       afterImportId: after?.id,
       sourceChanged,
-      changeSummary: nativeSourceChangeSummary(changedSymbols, changedRegions, sourceChanged)
+      changeSummary: nativeSourceChangeSummary(changedSymbols, changedRegions, sourceChanged),
+      changedRegionProjectionSummary
     }
   });
   return {
@@ -3259,6 +3275,7 @@ export function diffNativeSourceImports(input) {
       afterSidecarId: afterSidecar?.id,
       beforeImportContract: before?.metadata?.importResultContract,
       afterImportContract: after?.metadata?.importResultContract,
+      changedRegionProjectionSummary,
       ...input.metadata
     }
   };
@@ -3404,6 +3421,199 @@ function fileLevelNativeChangeRegion(input) {
   };
 }
 
+function attachNativeChangeRegionProjectionMetadata(regions, context) {
+  return (regions ?? []).map((region) => {
+    const projection = nativeChangedRegionProjectionMetadata(region, context);
+    return {
+      ...region,
+      metadata: {
+        ...(region.metadata ?? {}),
+        changedRegionProjection: projection
+      }
+    };
+  });
+}
+
+function nativeChangedRegionProjectionMetadata(region, context) {
+  const beforeRegion = findSemanticImportRegion(context.beforeSidecar, region);
+  const afterRegion = findSemanticImportRegion(context.afterSidecar, region);
+  const regionSymbols = (context.changedSymbols ?? []).filter((symbol) => nativeChangeSymbolTouchesRegion(symbol, region));
+  const sourceMapLinks = uniqueRecordsById([
+    ...nativeChangeProjectionSourceMapLinks(context.before, 'before', beforeRegion ?? region, regionSymbols),
+    ...nativeChangeProjectionSourceMapLinks(context.after, 'after', afterRegion ?? region, regionSymbols)
+  ]).slice(0, 24);
+  const action = nativeChangedRegionProjectionAction(region, context.readiness);
+  const conflictKeys = uniqueStrings([
+    region.conflictKey,
+    region.key ? `region:${region.key}` : undefined,
+    region.id ? `region:${region.id}` : undefined,
+    ...regionSymbols.map((symbol) => symbol.conflictKey)
+  ].filter(Boolean));
+  return {
+    schema: 'frontier.lang.changedRegionProjection.v1',
+    id: `changed_region_projection_${idFragment(region.conflictKey ?? region.key ?? region.id)}`,
+    reviewRequired: true,
+    autoMergeClaim: false,
+    changeKind: region.changeKind,
+    language: region.language ?? context.language,
+    sourcePath: region.sourcePath ?? context.sourcePath,
+    conflictKey: region.conflictKey,
+    region: {
+      id: region.id,
+      key: region.key,
+      kind: region.regionKind,
+      granularity: region.granularity,
+      precision: region.precision,
+      sourceSpan: region.sourceSpan,
+      nativeAstNodeId: region.nativeAstNodeId,
+      symbolId: region.symbolId,
+      symbolName: region.symbolName,
+      symbolKind: region.symbolKind
+    },
+    before: nativeChangeProjectionEndpoint(context.before, context.beforeSidecar, beforeRegion ?? (region.changeKind === 'added' ? undefined : region), 'before'),
+    after: nativeChangeProjectionEndpoint(context.after, context.afterSidecar, afterRegion ?? (region.changeKind === 'removed' ? undefined : region), 'after'),
+    sourceMapLinks,
+    admission: {
+      readiness: context.readiness,
+      action,
+      reasons: context.reasons ?? [],
+      conflictKeys
+    }
+  };
+}
+
+function findSemanticImportRegion(sidecar, region) {
+  return (sidecar?.ownershipRegions ?? []).find((candidate) => (
+    (region.id && candidate.id === region.id) ||
+    (region.key && candidate.key === region.key)
+  ));
+}
+
+function nativeChangeProjectionEndpoint(imported, sidecar, region, side) {
+  if (!imported && !region) return undefined;
+  const preservation = nativeImportSourcePreservationRecord(imported);
+  const sourceMaps = imported?.sourceMaps ?? imported?.universalAst?.sourceMaps ?? [];
+  const regionMappings = sourceMaps
+    .flatMap((sourceMap) => (sourceMap?.mappings ?? []).map((mapping) => ({ sourceMap, mapping })))
+    .filter(({ mapping }) => nativeChangeMappingTouchesRegion(mapping, region, []));
+  return {
+    side,
+    importId: imported?.id,
+    sidecarId: sidecar?.id,
+    nativeSourceId: imported?.nativeSource?.id,
+    nativeAstId: imported?.nativeAst?.id,
+    semanticIndexId: imported?.semanticIndex?.id,
+    universalAstId: imported?.universalAst?.id,
+    sourcePath: imported?.sourcePath ?? region?.sourcePath,
+    sourceHash: imported?.nativeSource?.sourceHash ?? imported?.nativeAst?.sourceHash ?? region?.sourceHash,
+    sourcePreservationId: preservation?.id,
+    exactSourceAvailable: preservation?.summary?.exactSourceAvailable === true,
+    ownershipRegionId: region?.id,
+    ownershipKey: region?.key,
+    ownershipRegionKind: region?.regionKind,
+    sourceSpan: region?.sourceSpan,
+    sourceMapIds: sourceMaps.map((sourceMap) => sourceMap?.id).filter(Boolean),
+    sourceMapMappingIds: regionMappings.map(({ mapping }) => mapping?.id).filter(Boolean)
+  };
+}
+
+function nativeChangeProjectionSourceMapLinks(imported, side, region, symbols) {
+  if (!imported) return [];
+  const sourceMaps = imported.sourceMaps ?? imported.universalAst?.sourceMaps ?? [];
+  const links = [];
+  for (const sourceMap of sourceMaps) {
+    for (const mapping of sourceMap?.mappings ?? []) {
+      if (!nativeChangeMappingTouchesRegion(mapping, region, symbols)) continue;
+      links.push({
+        id: `${side}:${sourceMap.id}:${mapping.id}`,
+        side,
+        sourceMapId: sourceMap.id,
+        sourceMapMappingId: mapping.id,
+        sourcePath: mapping.sourceSpan?.path ?? sourceMap.sourcePath ?? imported.sourcePath,
+        sourceHash: sourceMap.sourceHash ?? imported.nativeSource?.sourceHash ?? imported.nativeAst?.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,
+        ownershipRegionId: mapping.ownershipRegionId,
+        ownershipRegionKey: mapping.ownershipRegionKey,
+        ownershipRegionKind: mapping.ownershipRegionKind
+      });
+    }
+  }
+  return links;
+}
+
+function nativeChangeMappingTouchesRegion(mapping, region, symbols) {
+  if (!mapping || !region) return false;
+  const symbolIds = new Set((symbols ?? []).map((symbol) => symbol.id).filter(Boolean));
+  const occurrenceIds = new Set((symbols ?? []).map((symbol) => symbol.semanticOccurrenceId).filter(Boolean));
+  const mappingIds = new Set((symbols ?? []).map((symbol) => symbol.sourceMapMappingId).filter(Boolean));
+  if (mappingIds.has(mapping.id)) return true;
+  if (region.id && mapping.ownershipRegionId === region.id) return true;
+  if (region.key && mapping.ownershipRegionKey === region.key) return true;
+  if (region.nativeAstNodeId && mapping.nativeAstNodeId === region.nativeAstNodeId) return true;
+  if (symbolIds.has(mapping.semanticSymbolId)) return true;
+  if (occurrenceIds.has(mapping.semanticOccurrenceId)) return true;
+  if (region.granularity === 'file') {
+    return !region.sourcePath || sourceSpanPathMatches(mapping.sourceSpan, region.sourcePath);
+  }
+  return false;
+}
+
+function sourceSpanPathMatches(span, sourcePath) {
+  if (!span || !sourcePath) return false;
+  return span.path === sourcePath || span.sourceId === sourcePath;
+}
+
+function nativeChangeSymbolTouchesRegion(symbol, region) {
+  return Boolean(symbol && region && (
+    (region.id && symbol.ownershipRegionId === region.id) ||
+    (region.key && (
+      symbol.ownershipKey === region.key ||
+      symbol.beforeOwnershipKey === region.key ||
+      symbol.afterOwnershipKey === region.key
+    ))
+  ));
+}
+
+function nativeChangedRegionProjectionAction(region, readiness) {
+  if (readiness === 'blocked') return 'rerun-or-human-port';
+  if (region.changeKind === 'added') return 'review-addition';
+  if (region.changeKind === 'removed') return 'review-removal';
+  if (region.granularity === 'file') return 'review-file';
+  return 'review-port';
+}
+
+function nativeImportSourcePreservationRecord(imported) {
+  return imported?.metadata?.sourcePreservation
+    ?? imported?.nativeSource?.metadata?.sourcePreservation
+    ?? imported?.nativeAst?.metadata?.sourcePreservation
+    ?? imported?.universalAst?.metadata?.sourcePreservation;
+}
+
+function summarizeNativeChangedRegionProjections(regions) {
+  const projections = (regions ?? [])
+    .map((region) => region?.metadata?.changedRegionProjection)
+    .filter(Boolean);
+  return {
+    schema: 'frontier.lang.changedRegionProjectionSummary.v1',
+    total: regions?.length ?? 0,
+    withProjection: projections.length,
+    reviewRequired: projections.filter((projection) => projection.reviewRequired === true).length,
+    autoMergeClaims: projections.filter((projection) => projection.autoMergeClaim === true).length,
+    sourceMapLinks: projections.reduce((sum, projection) => sum + (projection.sourceMapLinks?.length ?? 0), 0),
+    byAction: countBy(projections.map((projection) => projection.admission?.action ?? 'unknown')),
+    byRegionKind: countBy(projections.map((projection) => projection.region?.kind ?? 'unknown'))
+  };
+}
+
 function nativeImportReadiness(imported) {
   return imported?.metadata?.semanticMergeReadiness
     ?? imported?.metadata?.nativeImportLossSummary?.semanticMergeReadiness
@@ -3467,11 +3677,31 @@ function nativeChangeSpans(changedSymbols, changedRegions, input) {
       symbolId: region.symbolId,
       span: region.sourceSpan,
       conflictKey: region.conflictKey ?? `region:${region.key ?? region.id}`,
-      metadata: { changeKind: region.changeKind, regionKind: region.regionKind, granularity: region.granularity }
+      metadata: {
+        changeKind: region.changeKind,
+        regionKind: region.regionKind,
+        granularity: region.granularity,
+        ...(region.metadata?.changedRegionProjection ? {
+          changedRegionProjection: nativeChangedRegionProjectionSpanMetadata(region.metadata.changedRegionProjection)
+        } : {})
+      }
     }));
   return uniqueRecordsById([...symbolSpans, ...regionSpans]);
 }
 
+function nativeChangedRegionProjectionSpanMetadata(projection) {
+  return {
+    schema: projection.schema,
+    id: projection.id,
+    reviewRequired: projection.reviewRequired,
+    autoMergeClaim: projection.autoMergeClaim,
+    beforeSourceHash: projection.before?.sourceHash,
+    afterSourceHash: projection.after?.sourceHash,
+    sourceMapLinks: projection.sourceMapLinks?.length ?? 0,
+    admission: projection.admission
+  };
+}
+
 function nativeSourceChangeSummary(changedSymbols, changedRegions, sourceChanged) {
   return {
     sourceChanged,

package/package.json

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