@shapeshift-labs/frontier-lang-compiler 0.2.122 → 0.2.124

package/README.md

@@ -289,8 +289,28 @@ the semantic index and project symbol graph.
 `safeMergeJsTsProject` stays synchronous. When a caller already has parser-backed
 native import results for merged output files, pass them as `outputProjectImports`
 with `includeOutputProjectSymbolGraph`. The graph builder matches supplied
-imports by `sourcePath` and `sourceHash`, uses them for output graph artifacts,
-and falls back to the lightweight scanner for missing or stale files.
+imports by `sourcePath` and `sourceHash`, requires hash-verified matches when
+the merged source has a hash, uses them for output graph artifacts, and falls
+back to the lightweight scanner for missing or stale files.
+
+For admission queues that need bounded cross-branch API checks, enable
+`includeProjectGraphDelta`. This additionally builds base, worker, head, and
+output project graph stages and blocks the merge when worker and head both
+change the same public contract, re-export identity, or import target in
+incompatible ways. Parser-backed stage imports can be supplied with
+`baseProjectImports`, `workerProjectImports`, `headProjectImports`, and
+`outputProjectImports`; missing or hash-stale stages fall back to the synchronous
+lightweight scanner. This is a conservative admission gate only: results still
+keep `autoMergeClaim: false` and `semanticEquivalenceClaim: false`.
+
+Artifact-size and runtime note: these graph options are deliberately opt-in.
+On a local Node v26.1.0 smoke fixture with 10 small JS/TS files and 36 scanned
+stage files for the delta case, baseline project merge JSON was 115 KB at a
+21.6 ms median. `includeOutputProjectSymbolGraph` raised the returned JSON to
+17.8 MB at a 303.1 ms median, and `includeProjectGraphDelta` raised it to
+83.0 MB at a 1,466.8 ms median. Keep these paths behind admission-queue caps
+for file count, total source bytes, graph edge count, and serialized artifact
+bytes, or expose summary/lazy graph materialization before using them broadly.
 
 High-risk native features also have explicit evidence policies. These policies are advisory in this package: they tell a swarm or admission queue what evidence is missing without silently changing the existing readiness classification.
 

package/dist/declarations/js-ts-safe-project-merge.d.ts

@@ -51,6 +51,15 @@ export type JsTsProjectSafeMergeOutputProjectImports =
   | ReadonlyMap<string, NativeSourceImportResult>
   | Readonly<Record<string, NativeSourceImportResult>>;
 
+export type JsTsProjectGraphStageName = 'base' | 'worker' | 'head' | 'output' | string;
+
+export type JsTsProjectSafeMergeProjectGraphImportsByStage = Readonly<{
+  base?: JsTsProjectSafeMergeOutputProjectImports;
+  worker?: JsTsProjectSafeMergeOutputProjectImports;
+  head?: JsTsProjectSafeMergeOutputProjectImports;
+  output?: JsTsProjectSafeMergeOutputProjectImports;
+} & Record<string, JsTsProjectSafeMergeOutputProjectImports | undefined>>;
+
 export interface JsTsProjectSafeMergeInput {
   readonly id?: string;
   readonly language?: FrontierSourceLanguage | string;
@@ -62,7 +71,12 @@ export interface JsTsProjectSafeMergeInput {
   readonly allowFileAdditions?: boolean;
   readonly allowFileDeletes?: boolean;
   readonly includeOutputProjectSymbolGraph?: boolean;
+  readonly includeProjectGraphDelta?: boolean;
   readonly outputProjectImports?: JsTsProjectSafeMergeOutputProjectImports;
+  readonly baseProjectImports?: JsTsProjectSafeMergeOutputProjectImports;
+  readonly workerProjectImports?: JsTsProjectSafeMergeOutputProjectImports;
+  readonly headProjectImports?: JsTsProjectSafeMergeOutputProjectImports;
+  readonly projectGraphImports?: JsTsProjectSafeMergeProjectGraphImportsByStage;
   readonly moduleResolution?: NativeProjectModuleResolutionOptions;
   readonly tsconfig?: NativeProjectModuleResolutionOptions;
   readonly workerChangeSetId?: string;
@@ -115,6 +129,56 @@ export interface JsTsProjectSafeMergeAdmission {
   readonly conflictKeys: readonly string[];
 }
 
+export interface JsTsProjectGraphDeltaStageSummary {
+  readonly stage: JsTsProjectGraphStageName;
+  readonly sourceFiles: number;
+  readonly documents: number;
+  readonly symbols: number;
+  readonly fileHashes: number;
+  readonly importEdges: number;
+  readonly exportEdges: number;
+  readonly publicContractRegions: number;
+  readonly reExportIdentities: number;
+  readonly unresolvedImportEdges: number;
+  readonly suppliedImports: number;
+  readonly matchedSuppliedImports: number;
+  readonly scannerFallbackImports: number;
+}
+
+export interface JsTsProjectGraphDeltaStage {
+  readonly kind: 'frontier.lang.jsTsProjectGraphStage';
+  readonly version: 1;
+  readonly stage: JsTsProjectGraphStageName;
+  readonly projectImport?: NativeProjectImportResult;
+  readonly projectSymbolGraph?: NativeProjectSymbolGraphSummary;
+  readonly summary: JsTsProjectGraphDeltaStageSummary;
+}
+
+export interface JsTsProjectGraphDeltaSummary {
+  readonly stages: number;
+  readonly sourceFiles: number;
+  readonly publicContractRegions: number;
+  readonly reExportIdentities: number;
+  readonly importEdges: number;
+  readonly exportEdges: number;
+  readonly unresolvedImportEdges: number;
+  readonly suppliedImports: number;
+  readonly matchedSuppliedImports: number;
+  readonly scannerFallbackImports: number;
+  readonly conflicts: number;
+  readonly publicContractConflicts: number;
+  readonly reExportIdentityConflicts: number;
+  readonly importTargetConflicts: number;
+  readonly stageSummaries: Readonly<Record<string, JsTsProjectGraphDeltaStageSummary>>;
+}
+
+export interface JsTsProjectGraphDelta {
+  readonly kind: 'frontier.lang.jsTsProjectGraphDelta';
+  readonly version: 1;
+  readonly stages: Readonly<Record<string, JsTsProjectGraphDeltaStage>>;
+  readonly summary: JsTsProjectGraphDeltaSummary;
+}
+
 export interface JsTsProjectSafeMergeResult {
   readonly kind: 'frontier.lang.jsTsProjectSafeMerge';
   readonly version: 1;
@@ -126,6 +190,7 @@ export interface JsTsProjectSafeMergeResult {
   readonly outputFiles: readonly JsTsProjectSafeMergeOutputFile[];
   readonly outputProjectImport?: NativeProjectImportResult;
   readonly outputProjectSymbolGraph?: NativeProjectSymbolGraphSummary;
+  readonly projectGraphDelta?: JsTsProjectGraphDelta;
   readonly conflicts: readonly JsTsSafeMergeConflict[];
   readonly admission: JsTsProjectSafeMergeAdmission;
   readonly summary: {
@@ -134,6 +199,11 @@ export interface JsTsProjectSafeMergeResult {
     readonly blockedFiles: number;
     readonly outputFiles: number;
     readonly projectGraphConflicts: number;
+    readonly outputProjectGraphConflicts: number;
+    readonly projectGraphDeltaConflicts: number;
+    readonly projectGraphPublicContractConflicts: number;
+    readonly projectGraphReExportIdentityConflicts: number;
+    readonly projectGraphImportTargetConflicts: number;
     readonly semanticArtifactFiles: number;
     readonly operations: Readonly<Record<string, number>>;
   };

package/dist/js-ts-safe-project-merge-graph-conflicts.js

@@ -1,16 +1,29 @@
 import { compactRecord } from './js-ts-safe-merge-context.js';
+import { projectGraphDeltaConflicts } from './js-ts-safe-project-merge-graph-delta-conflicts.js';
 
 function outputProjectGraphConflicts(projectSymbolGraph) {
   const importEdges = Array.isArray(projectSymbolGraph?.importEdges) ? projectSymbolGraph.importEdges : [];
-  const groups = new Map();
+  const missingModuleGroups = new Map();
+  const missingSymbolGroups = new Map();
   for (const edge of importEdges) {
-    if (!isMissingProjectImportEdge(edge)) continue;
-    const key = [edge.sourcePath, edge.moduleSpecifier, edge.resolutionKind, edge.resolvedModulePath].join('\u0000');
-    const group = groups.get(key) ?? [];
-    group.push(edge);
-    groups.set(key, group);
+    if (isMissingProjectImportEdge(edge)) {
+      const key = [edge.sourcePath, edge.moduleSpecifier, edge.resolutionKind, edge.resolvedModulePath].join('\u0000');
+      const group = missingModuleGroups.get(key) ?? [];
+      group.push(edge);
+      missingModuleGroups.set(key, group);
+      continue;
+    }
+    if (isMissingProjectImportTargetEdge(edge)) {
+      const key = [edge.sourcePath, edge.moduleSpecifier, projectImportTargetName(edge), edge.resolvedModulePath].join('\u0000');
+      const group = missingSymbolGroups.get(key) ?? [];
+      group.push(edge);
+      missingSymbolGroups.set(key, group);
+    }
   }
-  return [...groups.values()].map(projectGraphMissingImportConflict);
+  return [
+    ...[...missingModuleGroups.values()].map(projectGraphMissingImportConflict),
+    ...[...missingSymbolGroups.values()].map(projectGraphMissingTargetConflict)
+  ];
 }
 
 function projectGraphMissingImportConflict(group) {
@@ -34,12 +47,52 @@ function projectGraphMissingImportConflict(group) {
   };
 }
 
+function projectGraphMissingTargetConflict(group) {
+  const edge = group[0] ?? {};
+  const targetName = projectImportTargetName(edge);
+  return {
+    code: 'project-output-symbol-unresolved',
+    gateId: 'project-symbol-graph',
+    message: `Output project graph import ${JSON.stringify(edge.moduleSpecifier ?? 'unknown')} resolves to a module without exported symbol ${JSON.stringify(targetName ?? 'unknown')}.`,
+    sourcePath: edge.sourcePath,
+    details: compactRecord({
+      reasonCode: 'project-output-symbol-unresolved',
+      conflictKey: `project-symbol#${edge.sourcePath ?? 'unknown'}#${edge.moduleSpecifier ?? edge.resolvedModulePath ?? 'unknown'}#${targetName ?? 'unknown'}`,
+      sourcePath: edge.sourcePath,
+      moduleSpecifier: edge.moduleSpecifier,
+      resolutionKind: edge.resolutionKind,
+      resolvedModulePath: edge.resolvedModulePath,
+      targetDocumentId: edge.targetDocumentId,
+      targetExportName: targetName,
+      edgeIds: uniqueStrings(group.map((record) => record.id)),
+      importKinds: uniqueStrings(group.map((record) => record.importKind)),
+      importedNames: uniqueStrings(group.map((record) => record.importedName)),
+      localNames: uniqueStrings(group.map((record) => record.localName))
+    })
+  };
+}
+
 function isMissingProjectImportEdge(edge) {
   return typeof edge?.resolutionKind === 'string' && edge.resolutionKind.endsWith('-missing');
 }
 
+function isMissingProjectImportTargetEdge(edge) {
+  return hasResolvedProjectModule(edge) && Boolean(projectImportTargetName(edge)) && !edge.resolvedTargetSymbolId;
+}
+
+function hasResolvedProjectModule(edge) {
+  return Boolean(edge?.targetDocumentId) && typeof edge?.resolutionKind === 'string' && edge.resolutionKind.endsWith('-source');
+}
+
+function projectImportTargetName(edge) {
+  if (edge?.importKind === 'side-effect' || edge?.importKind === 'namespace') return undefined;
+  const name = edge?.importedName ?? edge?.localName ?? edge?.exportedName;
+  if (!name || name === '*') return undefined;
+  return String(name);
+}
+
 function uniqueStrings(values) {
   return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
 }
 
-export { outputProjectGraphConflicts };
+export { outputProjectGraphConflicts, projectGraphDeltaConflicts };

package/dist/js-ts-safe-project-merge-graph-delta-conflicts.js

@@ -0,0 +1,279 @@
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { compactRecord } from './js-ts-safe-merge-context.js';
+
+function projectGraphDeltaConflicts(projectGraphDelta) {
+  const baseGraph = projectGraphDelta?.stages?.base?.projectSymbolGraph;
+  const workerGraph = projectGraphDelta?.stages?.worker?.projectSymbolGraph;
+  const headGraph = projectGraphDelta?.stages?.head?.projectSymbolGraph;
+  const outputGraph = projectGraphDelta?.stages?.output?.projectSymbolGraph;
+  if (!baseGraph || !workerGraph || !headGraph) return [];
+  return [
+    ...changedIdentityConflicts({
+      code: 'project-public-contract-delta-conflict',
+      label: 'public contract',
+      baseRecords: baseGraph.publicContractRegions,
+      workerRecords: workerGraph.publicContractRegions,
+      headRecords: headGraph.publicContractRegions,
+      outputRecords: outputGraph?.publicContractRegions,
+      identityKey: publicContractIdentityKey,
+      fingerprint: publicContractFingerprint,
+      details: publicContractDetails
+    }),
+    ...changedIdentityConflicts({
+      code: 'project-re-export-identity-delta-conflict',
+      label: 're-export identity',
+      baseRecords: baseGraph.reExportIdentities,
+      workerRecords: workerGraph.reExportIdentities,
+      headRecords: headGraph.reExportIdentities,
+      outputRecords: outputGraph?.reExportIdentities,
+      identityKey: reExportIdentityKey,
+      fingerprint: reExportIdentityFingerprint,
+      details: reExportIdentityDetails
+    }),
+    ...projectImportTargetDeltaConflicts(projectGraphDelta)
+  ];
+}
+
+function addProjectGraphDeltaConflictSummary(projectGraphDelta, conflicts) {
+  if (!projectGraphDelta) return undefined;
+  return {
+    ...projectGraphDelta,
+    summary: {
+      ...projectGraphDelta.summary,
+      conflicts: conflicts.length,
+      publicContractConflicts: conflicts.filter((conflict) => conflict.code === 'project-public-contract-delta-conflict').length,
+      reExportIdentityConflicts: conflicts.filter((conflict) => conflict.code === 'project-re-export-identity-delta-conflict').length,
+      importTargetConflicts: conflicts.filter((conflict) => conflict.code === 'project-import-target-delta-conflict').length
+    }
+  };
+}
+
+function changedIdentityConflicts(input) {
+  const base = recordsByIdentityKey(input.baseRecords, input.identityKey);
+  const worker = recordsByIdentityKey(input.workerRecords, input.identityKey);
+  const head = recordsByIdentityKey(input.headRecords, input.identityKey);
+  const output = recordsByIdentityKey(input.outputRecords, input.identityKey);
+  const keys = uniqueStrings([...base.keys(), ...worker.keys(), ...head.keys()]);
+  return keys.flatMap((identityKey) => {
+    const baseRecord = base.get(identityKey);
+    const workerRecord = worker.get(identityKey);
+    const headRecord = head.get(identityKey);
+    const baseFingerprint = optionalFingerprint(baseRecord, input.fingerprint);
+    const workerFingerprint = optionalFingerprint(workerRecord, input.fingerprint);
+    const headFingerprint = optionalFingerprint(headRecord, input.fingerprint);
+    if (baseFingerprint === workerFingerprint || baseFingerprint === headFingerprint || workerFingerprint === headFingerprint) return [];
+    return [projectGraphDeltaConflict({
+      code: input.code,
+      label: input.label,
+      identityKey,
+      baseRecord,
+      workerRecord,
+      headRecord,
+      outputRecord: output.get(identityKey),
+      details: input.details
+    })];
+  });
+}
+
+function projectImportTargetDeltaConflicts(projectGraphDelta) {
+  const baseStage = projectGraphDelta?.stages?.base;
+  const workerStage = projectGraphDelta?.stages?.worker;
+  const headStage = projectGraphDelta?.stages?.head;
+  const outputStage = projectGraphDelta?.stages?.output;
+  const workerEdges = importEdgesByIdentityKey(workerStage?.projectSymbolGraph?.importEdges);
+  const baseSymbolIds = semanticSymbolIds(baseStage);
+  const headSymbolIds = semanticSymbolIds(headStage);
+  const conflicts = [];
+  for (const [identityKey, edge] of importEdgesByIdentityKey(outputStage?.projectSymbolGraph?.importEdges)) {
+    if (!edge.resolvedTargetSymbolId) continue;
+    const workerEdge = workerEdges.get(identityKey);
+    if (!workerEdge || workerEdge.resolvedTargetSymbolId === edge.resolvedTargetSymbolId) continue;
+    if (baseSymbolIds.has(edge.resolvedTargetSymbolId) || !headSymbolIds.has(edge.resolvedTargetSymbolId)) continue;
+    conflicts.push(projectImportTargetDeltaConflict(identityKey, edge, workerEdge));
+  }
+  return conflicts;
+}
+
+function projectGraphDeltaConflict(input) {
+  const sourcePath = input.workerRecord?.sourcePath ?? input.headRecord?.sourcePath ?? input.baseRecord?.sourcePath;
+  const conflictKey = `project-graph-delta#${input.label.replace(/\s+/g, '-')}#${input.identityKey}`;
+  return {
+    code: input.code,
+    gateId: 'project-graph-delta',
+    message: `Worker and head both changed ${input.label} ${JSON.stringify(input.identityKey)} in incompatible ways.`,
+    sourcePath,
+    details: compactRecord({
+      reasonCode: input.code,
+      conflictKey,
+      identityKey: input.identityKey,
+      sourcePath,
+      base: input.details(input.baseRecord),
+      worker: input.details(input.workerRecord),
+      head: input.details(input.headRecord),
+      output: input.details(input.outputRecord)
+    })
+  };
+}
+
+function projectImportTargetDeltaConflict(identityKey, edge, workerEdge) {
+  return {
+    code: 'project-import-target-delta-conflict',
+    gateId: 'project-graph-delta',
+    message: `Output import ${JSON.stringify(projectImportTargetName(edge) ?? edge.moduleSpecifier ?? 'unknown')} resolves to a head-branch exported symbol that the worker import did not resolve against.`,
+    sourcePath: edge.sourcePath,
+    details: compactRecord({
+      reasonCode: 'project-import-target-delta-conflict',
+      conflictKey: `project-graph-delta#import-target#${identityKey}`,
+      identityKey,
+      sourcePath: edge.sourcePath,
+      moduleSpecifier: edge.moduleSpecifier,
+      importedName: edge.importedName,
+      localName: edge.localName,
+      importKind: edge.importKind,
+      resolvedModulePath: edge.resolvedModulePath,
+      outputTargetSymbolId: edge.resolvedTargetSymbolId,
+      workerTargetSymbolId: workerEdge.resolvedTargetSymbolId,
+      workerResolutionKind: workerEdge.resolutionKind,
+      outputResolutionKind: edge.resolutionKind
+    })
+  };
+}
+
+function recordsByIdentityKey(records, identityKey) {
+  const result = new Map();
+  for (const record of records ?? []) {
+    const key = identityKey(record);
+    if (!key || result.has(key)) continue;
+    result.set(key, record);
+  }
+  return result;
+}
+
+function publicContractIdentityKey(record) {
+  return firstString(
+    record?.key,
+    stableKey(['public-contract', record?.sourcePath, record?.apiSurfaceKind, record?.edgeKind, record?.moduleSpecifier, record?.exportedName ?? record?.symbolName ?? record?.symbolId])
+  );
+}
+
+function publicContractFingerprint(record) {
+  return hashSemanticValue({
+    kind: 'frontier.lang.projectGraphDelta.publicContractFingerprint',
+    contractHash: record.contractHash,
+    signatureHash: record.signatureHash,
+    symbolName: record.symbolName,
+    symbolKind: record.symbolKind,
+    apiSurfaceKind: record.apiSurfaceKind,
+    exportedName: record.exportedName,
+    moduleSpecifier: record.moduleSpecifier,
+    edgeKind: record.edgeKind
+  });
+}
+
+function publicContractDetails(record) {
+  if (!record) return undefined;
+  return compactRecord({
+    sourcePath: record.sourcePath,
+    key: publicContractIdentityKey(record),
+    symbolName: record.symbolName,
+    symbolKind: record.symbolKind,
+    apiSurfaceKind: record.apiSurfaceKind,
+    exportedName: record.exportedName,
+    moduleSpecifier: record.moduleSpecifier,
+    edgeKind: record.edgeKind,
+    signatureHash: record.signatureHash,
+    contractHash: record.contractHash,
+    sourceHash: record.sourceHash
+  });
+}
+
+function reExportIdentityKey(record) {
+  return stableKey(['re-export-identity', record?.sourcePath, record?.exportedName ?? record?.localName ?? record?.namespace ?? (record?.exportStar || record?.isExportStar ? '*' : undefined)]);
+}
+
+function reExportIdentityFingerprint(record) {
+  return hashSemanticValue({
+    kind: 'frontier.lang.projectGraphDelta.reExportIdentityFingerprint',
+    sourcePath: record.sourcePath,
+    moduleSpecifier: record.moduleSpecifier,
+    exportedName: record.exportedName,
+    importedName: record.importedName,
+    localName: record.localName,
+    namespace: record.namespace,
+    isTypeOnly: record.isTypeOnly,
+    exportStar: record.exportStar,
+    isExportStar: record.isExportStar,
+    originSymbolId: record.originSymbolId,
+    exportedSymbolId: record.exportedSymbolId,
+    localSymbolId: record.localSymbolId
+  });
+}
+
+function reExportIdentityDetails(record) {
+  if (!record) return undefined;
+  return compactRecord({
+    sourcePath: record.sourcePath,
+    key: reExportIdentityKey(record),
+    moduleSpecifier: record.moduleSpecifier,
+    exportedName: record.exportedName,
+    importedName: record.importedName,
+    localName: record.localName,
+    namespace: record.namespace,
+    isTypeOnly: record.isTypeOnly,
+    exportStar: record.exportStar,
+    isExportStar: record.isExportStar,
+    originSymbolId: record.originSymbolId,
+    exportedSymbolId: record.exportedSymbolId,
+    localSymbolId: record.localSymbolId,
+    sourceHash: record.sourceHash
+  });
+}
+
+function importEdgesByIdentityKey(records) {
+  const result = new Map();
+  for (const record of records ?? []) {
+    const key = importEdgeIdentityKey(record);
+    if (!key || result.has(key)) continue;
+    result.set(key, record);
+  }
+  return result;
+}
+
+function importEdgeIdentityKey(edge) {
+  const targetName = projectImportTargetName(edge);
+  if (!edge?.sourcePath || !edge.moduleSpecifier || !targetName) return undefined;
+  return stableKey(['import-target', edge.sourcePath, edge.moduleSpecifier, targetName, edge.importKind, edge.isTypeOnly]);
+}
+
+function projectImportTargetName(edge) {
+  if (edge?.importKind === 'side-effect' || edge?.importKind === 'namespace') return undefined;
+  const name = edge?.importedName ?? edge?.localName ?? edge?.exportedName;
+  if (!name || name === '*') return undefined;
+  return String(name);
+}
+
+function optionalFingerprint(record, fingerprint) {
+  return record ? fingerprint(record) : undefined;
+}
+
+function semanticSymbolIds(stage) {
+  return new Set((stage?.projectImport?.semanticIndex?.symbols ?? []).map((symbol) => symbol.id).filter(Boolean));
+}
+
+function stableKey(parts) {
+  const values = parts.map((part) => part === undefined || part === null ? '' : String(part));
+  return values.some(Boolean) ? values.join('#') : undefined;
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (value !== undefined && value !== null && String(value)) return String(value);
+  }
+  return undefined;
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+export { addProjectGraphDeltaConflictSummary, projectGraphDeltaConflicts };

package/dist/js-ts-safe-project-merge-graph.js

@@ -1,47 +1,90 @@
 import { idFragment } from './native-import-utils.js';
+import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
+import { compactRecord } from './js-ts-safe-merge-context.js';
 import { createNativeProjectImportResult } from './internal/index-impl/createNativeProjectImportResult.js';
 import { importNativeSource } from './internal/index-impl/importNativeSource.js';
 
 function createJsTsProjectSafeMergeGraphArtifacts(input, outputFiles, mergeId) {
-  const sources = outputFiles.map((file) => ({
-    id: `${mergeId}_output_${idFragment(file.sourcePath)}`,
+  return createProjectGraphStageArtifacts(input, outputFiles, mergeId, 'output', projectImportsForStage(input, 'output'));
+}
+
+function createJsTsProjectSafeMergeGraphDelta(input, files, outputFiles, mergeId) {
+  const stageFiles = projectGraphDeltaStageFiles(files, outputFiles, input);
+  const stages = {};
+  for (const stageName of ['base', 'worker', 'head', 'output']) {
+    const files = stageFiles?.[stageName];
+    if (!Array.isArray(files)) continue;
+    stages[stageName] = createProjectGraphStageArtifacts(input, files, mergeId, stageName, projectImportsForStage(input, stageName));
+  }
+  const stageSummaries = Object.fromEntries(Object.entries(stages).map(([stageName, artifacts]) => [stageName, artifacts.summary]));
+  return {
+    kind: 'frontier.lang.jsTsProjectGraphDelta',
+    version: 1,
+    stages,
+    summary: {
+      stages: Object.keys(stages).length,
+      sourceFiles: sumStageSummary(stageSummaries, 'sourceFiles'),
+      publicContractRegions: sumStageSummary(stageSummaries, 'publicContractRegions'),
+      reExportIdentities: sumStageSummary(stageSummaries, 'reExportIdentities'),
+      importEdges: sumStageSummary(stageSummaries, 'importEdges'),
+      exportEdges: sumStageSummary(stageSummaries, 'exportEdges'),
+      unresolvedImportEdges: sumStageSummary(stageSummaries, 'unresolvedImportEdges'),
+      suppliedImports: sumStageSummary(stageSummaries, 'suppliedImports'),
+      matchedSuppliedImports: sumStageSummary(stageSummaries, 'matchedSuppliedImports'),
+      scannerFallbackImports: sumStageSummary(stageSummaries, 'scannerFallbackImports'),
+      stageSummaries
+    }
+  };
+}
+
+function createProjectGraphStageArtifacts(input, files, mergeId, stageName, stageImports) {
+  const sources = files.map((file) => ({
+    id: `${mergeId}_${stageName}_${idFragment(file.sourcePath)}`,
     language: file.language ?? input.language ?? languageForPath(file.sourcePath),
     sourcePath: file.sourcePath,
     sourceText: file.sourceText,
     sourceHash: file.sourceHash,
-    metadata: { semanticImportExpected: true, projectSafeMergeOutput: true }
+    metadata: { semanticImportExpected: true, projectSafeMergeStage: stageName, projectSafeMergeOutput: stageName === 'output' }
   }));
-  const suppliedImports = normalizeOutputProjectImports(input.outputProjectImports);
+  const suppliedImports = normalizeProjectImports(stageImports);
   const importSelections = sources.map((source) => {
-    const suppliedImport = matchingOutputProjectImport(source, suppliedImports);
+    const suppliedImport = matchingProjectImport(source, suppliedImports);
     return {
       importResult: suppliedImport ?? importNativeSource(source),
-      sourceKind: suppliedImport ? 'supplied-output-project-import' : 'lightweight-output-project-scan'
+      sourceKind: suppliedImport ? `supplied-${stageName}-project-import` : `lightweight-${stageName}-project-scan`
     };
   });
   const imports = importSelections.map((selection) => selection.importResult);
+  const projectGraphImportSource = {
+    stage: stageName,
+    suppliedImports: suppliedImports.length,
+    matchedSuppliedImports: importSelections.filter((selection) => selection.sourceKind === `supplied-${stageName}-project-import`).length,
+    scannerFallbackImports: importSelections.filter((selection) => selection.sourceKind === `lightweight-${stageName}-project-scan`).length
+  };
   const projectImport = createNativeProjectImportResult({
-    id: `${mergeId}_output_project_import`,
+    id: `${mergeId}_${stageName}_project_import`,
     projectRoot: input.projectRoot,
     moduleResolution: input.moduleResolution ?? input.tsconfig,
     sources,
     metadata: {
       projectSafeMergeId: mergeId,
-      outputProjectSymbolGraph: true,
-      outputProjectImportSource: {
-        suppliedImports: suppliedImports.length,
-        matchedSuppliedImports: importSelections.filter((selection) => selection.sourceKind === 'supplied-output-project-import').length,
-        scannerFallbackImports: importSelections.filter((selection) => selection.sourceKind === 'lightweight-output-project-scan').length
-      }
+      projectGraphStage: stageName,
+      outputProjectSymbolGraph: stageName === 'output',
+      projectGraphImportSource,
+      ...(stageName === 'output' ? { outputProjectImportSource: projectGraphImportSource } : {})
     }
   }, imports);
   return {
+    kind: 'frontier.lang.jsTsProjectGraphStage',
+    version: 1,
+    stage: stageName,
     projectImport,
-    projectSymbolGraph: projectImport.projectSymbolGraph
+    projectSymbolGraph: projectImport.projectSymbolGraph,
+    summary: projectGraphStageSummary(stageName, projectImport.projectSymbolGraph, projectGraphImportSource)
   };
 }
 
-function normalizeOutputProjectImports(value) {
+function normalizeProjectImports(value) {
   if (!value) return [];
   if (Array.isArray(value)) return value.filter(Boolean);
   if (value instanceof Map) return [...value.values()].filter(Boolean);
@@ -49,18 +92,93 @@ function normalizeOutputProjectImports(value) {
   return [];
 }
 
-function matchingOutputProjectImport(source, imports) {
+function projectImportsForStage(input, stageName) {
+  if (stageName === 'output') return input.outputProjectImports ?? input.projectGraphImports?.output;
+  if (stageName === 'base') return input.baseProjectImports ?? input.projectGraphImports?.base;
+  if (stageName === 'worker') return input.workerProjectImports ?? input.projectGraphImports?.worker;
+  if (stageName === 'head') return input.headProjectImports ?? input.projectGraphImports?.head;
+  return input.projectGraphImports?.[stageName];
+}
+
+function matchingProjectImport(source, imports) {
   const sourcePath = String(source.sourcePath ?? '');
   const sourceHash = String(source.sourceHash ?? '');
   return imports.find((importResult) => {
     const importSourcePath = sourcePathForImport(importResult);
     if (importSourcePath && sourcePath && importSourcePath !== sourcePath) return false;
     const importSourceHash = sourceHashForImport(importResult);
+    if (sourceHash && importSourceHash !== sourceHash) return false;
     if (importSourceHash && sourceHash && importSourceHash !== sourceHash) return false;
     return importSourcePath === sourcePath || importSourceHash === sourceHash;
   });
 }
 
+function projectGraphStageSummary(stageName, projectSymbolGraph, importSource) {
+  const importEdges = Array.isArray(projectSymbolGraph?.importEdges) ? projectSymbolGraph.importEdges : [];
+  return {
+    stage: stageName,
+    sourceFiles: projectSymbolGraph?.sourceCount ?? 0,
+    documents: projectSymbolGraph?.documentCount ?? 0,
+    symbols: projectSymbolGraph?.symbolCount ?? 0,
+    fileHashes: projectSymbolGraph?.fileHashes?.length ?? 0,
+    importEdges: importEdges.length,
+    exportEdges: projectSymbolGraph?.exportEdges?.length ?? 0,
+    publicContractRegions: projectSymbolGraph?.publicContractRegions?.length ?? 0,
+    reExportIdentities: projectSymbolGraph?.reExportIdentities?.length ?? 0,
+    unresolvedImportEdges: importEdges.filter(isMissingProjectImportEdge).length,
+    suppliedImports: importSource.suppliedImports,
+    matchedSuppliedImports: importSource.matchedSuppliedImports,
+    scannerFallbackImports: importSource.scannerFallbackImports
+  };
+}
+
+function isMissingProjectImportEdge(edge) {
+  return typeof edge?.resolutionKind === 'string' && edge.resolutionKind.endsWith('-missing');
+}
+
+function sumStageSummary(stageSummaries, field) {
+  return Object.values(stageSummaries).reduce((total, summary) => total + Number(summary?.[field] ?? 0), 0);
+}
+
+function projectGraphDeltaStageFiles(files, outputFiles, input) {
+  return {
+    base: files
+      .map((file) => stageFile(file, file.baseSourceText, input))
+      .filter(Boolean),
+    worker: files
+      .map((file) => stageFile(file, workerStageSourceText(file), input))
+      .filter(Boolean),
+    head: files
+      .map((file) => stageFile(file, headStageSourceText(file), input))
+      .filter(Boolean),
+    output: outputFiles
+  };
+}
+
+function workerStageSourceText(file) {
+  if (file.workerDeleted) return undefined;
+  return file.workerSourceText ?? file.baseSourceText;
+}
+
+function headStageSourceText(file) {
+  if (file.headDeleted) return undefined;
+  return file.headSourceText ?? file.baseSourceText;
+}
+
+function stageFile(file, sourceText, input) {
+  if (typeof sourceText !== 'string' || !file.sourcePath) return undefined;
+  return compactRecord({
+    sourcePath: file.sourcePath,
+    language: file.language ?? input.language,
+    sourceText,
+    sourceHash: hashText(sourceText)
+  });
+}
+
+function hashText(sourceText) {
+  return hashSemanticValue(sourceText);
+}
+
 function sourcePathForImport(importResult) {
   return firstString(
     importResult?.sourcePath,
@@ -92,4 +210,4 @@ function firstString(...values) {
   return undefined;
 }
 
-export { createJsTsProjectSafeMergeGraphArtifacts };
+export { createJsTsProjectSafeMergeGraphArtifacts, createJsTsProjectSafeMergeGraphDelta };

package/dist/js-ts-safe-project-merge.js

@@ -1,8 +1,9 @@
 import { hashSemanticValue } from '@shapeshift-labs/frontier-lang-kernel';
 import { safeMergeJsTsSource } from './js-ts-safe-merge-composed.js';
 import { compactRecord } from './js-ts-safe-merge-context.js';
-import { createJsTsProjectSafeMergeGraphArtifacts } from './js-ts-safe-project-merge-graph.js';
-import { outputProjectGraphConflicts } from './js-ts-safe-project-merge-graph-conflicts.js';
+import { createJsTsProjectSafeMergeGraphArtifacts, createJsTsProjectSafeMergeGraphDelta } from './js-ts-safe-project-merge-graph.js';
+import { addProjectGraphDeltaConflictSummary } from './js-ts-safe-project-merge-graph-delta-conflicts.js';
+import { outputProjectGraphConflicts, projectGraphDeltaConflicts } from './js-ts-safe-project-merge-graph-conflicts.js';
 
 function safeMergeJsTsProject(input = {}) {
   const id = String(input.id ?? 'js_ts_project_safe_merge');
@@ -18,10 +19,16 @@ function safeMergeJsTsProject(input = {}) {
       sourceHash: file.outputHash,
       operation: file.operation
     }));
-  const graphArtifacts = blockedFiles.length === 0 && input.includeOutputProjectSymbolGraph
-    ? createJsTsProjectSafeMergeGraphArtifacts(input, outputFiles, id)
+  const projectGraphDelta = blockedFiles.length === 0 && input.includeProjectGraphDelta
+    ? createJsTsProjectSafeMergeGraphDelta(input, files, outputFiles, id)
     : undefined;
-  const graphConflicts = outputProjectGraphConflicts(graphArtifacts?.projectSymbolGraph);
+  const graphArtifacts = projectGraphDelta?.stages?.output ?? (blockedFiles.length === 0 && input.includeOutputProjectSymbolGraph
+    ? createJsTsProjectSafeMergeGraphArtifacts(input, outputFiles, id)
+    : undefined);
+  const outputGraphConflicts = outputProjectGraphConflicts(graphArtifacts?.projectSymbolGraph);
+  const deltaGraphConflicts = projectGraphDeltaConflicts(projectGraphDelta);
+  const projectGraphDeltaWithConflicts = addProjectGraphDeltaConflictSummary(projectGraphDelta, deltaGraphConflicts);
+  const graphConflicts = [...outputGraphConflicts, ...deltaGraphConflicts];
   const status = blockedFiles.length || graphConflicts.length ? 'blocked' : 'merged';
   const reasonCodes = uniqueStrings([
     ...blockedFiles.flatMap((file) => file.admission.reasonCodes),
@@ -41,6 +48,7 @@ function safeMergeJsTsProject(input = {}) {
     outputFiles,
     outputProjectImport: graphArtifacts?.projectImport,
     outputProjectSymbolGraph: graphArtifacts?.projectSymbolGraph,
+    projectGraphDelta: projectGraphDeltaWithConflicts,
     conflicts: [...fileResults.flatMap((file) => file.conflicts), ...graphConflicts],
     admission: {
       status: status === 'merged' ? 'auto-merge-candidate' : 'blocked',
@@ -59,7 +67,10 @@ function safeMergeJsTsProject(input = {}) {
       projectRoot: input.projectRoot,
       filesInput: Array.isArray(input.files) ? 'records' : 'maps',
       outputProjectSymbolGraph: Boolean(graphArtifacts?.projectSymbolGraph),
+      projectGraphDelta: Boolean(projectGraphDeltaWithConflicts),
       projectGraphConflicts: graphConflicts.length || undefined,
+      outputProjectGraphConflicts: outputGraphConflicts.length || undefined,
+      projectGraphDeltaConflicts: deltaGraphConflicts.length || undefined,
       autoMergeClaim: false,
       semanticEquivalenceClaim: false
     })
@@ -240,20 +251,24 @@ function policyForFile(input, sourcePath) {
 
 function sourceLedgersForFile(input, sourcePath) {
   const byPath = input.sourceLedgersByPath?.[sourcePath] ?? input.sourceLedgers?.[sourcePath];
-  if (byPath) return byPath;
-  if (input.sourceLedgers?.base || input.sourceLedgers?.worker || input.sourceLedgers?.head) return input.sourceLedgers;
-  return undefined;
+  return byPath ?? (input.sourceLedgers?.base || input.sourceLedgers?.worker || input.sourceLedgers?.head ? input.sourceLedgers : undefined);
 }
 
 function projectSummary(files, graphConflicts = []) {
   const byOperation = {};
   for (const file of files) byOperation[file.operation] = (byOperation[file.operation] ?? 0) + 1;
+  const deltaConflicts = graphConflicts.filter((conflict) => conflict.gateId === 'project-graph-delta');
   return {
     files: files.length,
     mergedFiles: files.filter((file) => file.status === 'merged').length,
     blockedFiles: files.filter((file) => file.status === 'blocked').length,
     outputFiles: files.filter((file) => typeof file.outputSourceText === 'string').length,
     projectGraphConflicts: graphConflicts.length,
+    outputProjectGraphConflicts: graphConflicts.length - deltaConflicts.length,
+    projectGraphDeltaConflicts: deltaConflicts.length,
+    projectGraphPublicContractConflicts: deltaConflicts.filter((conflict) => conflict.code === 'project-public-contract-delta-conflict').length,
+    projectGraphReExportIdentityConflicts: deltaConflicts.filter((conflict) => conflict.code === 'project-re-export-identity-delta-conflict').length,
+    projectGraphImportTargetConflicts: deltaConflicts.filter((conflict) => conflict.code === 'project-import-target-delta-conflict').length,
     semanticArtifactFiles: files.filter((file) => file.semanticArtifacts).length,
     operations: byOperation
   };
@@ -283,21 +298,15 @@ function blockedAdmission(reasonCode) {
   };
 }
 
-function hashText(text) {
-  return typeof text === 'string' ? hashSemanticValue(text) : undefined;
-}
+function hashText(text) { return typeof text === 'string' ? hashSemanticValue(text) : undefined; }
 
-function stringOrUndefined(value) {
-  return typeof value === 'string' ? value : undefined;
-}
+function stringOrUndefined(value) { return typeof value === 'string' ? value : undefined; }
 
 function safeId(value) {
   return String(value ?? 'unknown').replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'file';
 }
 
-function bySourcePath(left, right) {
-  return String(left.sourcePath ?? '').localeCompare(String(right.sourcePath ?? ''));
-}
+function bySourcePath(left, right) { return String(left.sourcePath ?? '').localeCompare(String(right.sourcePath ?? '')); }
 
 function uniqueStrings(values) {
   return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];

package/package.json

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