@shapeshift-labs/frontier-lang-compiler 0.2.41 → 0.2.42

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

@@ -0,0 +1,166 @@
+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';
+export function diffNativeSourceImports(input) {
+  const before = normalizeNativeDiffImport(input.before, input, 'before');
+  const after = normalizeNativeDiffImport(input.after, input, 'after');
+  if (!before && !after) throw new Error('diffNativeSourceImports 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 ?? 'native_source_change');
+  const beforeSidecar = before ? createSemanticImportSidecar(before, { id: `sidecar_before_${idPart}`, generatedAt: input.generatedAt, regionPrefix: input.regionPrefix }) : undefined;
+  const afterSidecar = after ? createSemanticImportSidecar(after, { id: `sidecar_after_${idPart}`, generatedAt: input.generatedAt, regionPrefix: input.regionPrefix }) : undefined;
+  const beforeSymbols = mapDiffSymbols(before, beforeSidecar);
+  const afterSymbols = mapDiffSymbols(after, afterSidecar);
+  const changedSymbols = diffNativeSymbols(beforeSymbols, afterSymbols);
+  let changedRegions = diffNativeOwnershipRegions(beforeSidecar, afterSidecar, changedSymbols);
+  const sourceChanged = Boolean(beforeHash && afterHash && beforeHash !== afterHash);
+  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',
+    status: input.evidenceStatus ?? 'passed',
+    path: sourcePath,
+    summary: `Compared ${language ?? 'native'} source imports: ${changedSymbols.length} changed symbol(s), ${changedRegions.length} changed region(s).`,
+    metadata: {
+      beforeImportId: before?.id,
+      afterImportId: after?.id,
+      beforeHash,
+      afterHash,
+      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,
+      changedRegionProjectionSummary
+    }
+  }];
+  const conflictKeys = uniqueStrings([
+    ...changedSymbols.map((symbol) => symbol.conflictKey),
+    ...changedRegions.map((region) => region.conflictKey ?? region.key ?? region.id),
+    ...(sourcePath ? [`source:${sourcePath}`] : [])
+  ]);
+  const mergeConflictProfile = classifyNativeSourceMergeConflicts({
+    before,
+    after,
+    beforeHash,
+    afterHash,
+    beforeSymbols: [...beforeSymbols.values()],
+    afterSymbols: [...afterSymbols.values()],
+    changedSymbols,
+    changedRegions,
+    sourceChanged,
+    conflictKeys,
+    readiness,
+    evidence,
+    language,
+    sourcePath
+  });
+  evidence[0].metadata.semanticMergeConflictSummary = mergeConflictProfile.conflictSummary;
+  const touches = changedRegions.map((region) => ({ id: region.id, access: 'write' }));
+  const operations = [
+    ...(after?.nativeSource ? [{ op: 'upsertNode', node: after.nativeSource, touches: touches.length ? touches : [{ id: after.nativeSource.id, access: 'evidence' }] }] : []),
+    ...(!after && before?.nativeSource ? [{ op: 'removeNode', id: before.nativeSource.id, touches: touches.length ? touches : [{ id: before.nativeSource.id, access: 'evidence' }] }] : []),
+    { op: 'addEvidence', evidence: evidence[0], touches }
+  ];
+  const patch = createPatch({
+    id: input.patchId ?? `patch_${idPart}_native_source_diff`,
+    baseHash: beforeHash,
+    targetHash: afterHash,
+    author: input.author ?? '@shapeshift-labs/frontier-lang-compiler/diffNativeSourceImports',
+    risk: readiness === 'blocked' ? 'high' : readiness === 'needs-review' ? 'medium' : 'low',
+    operations,
+    evidence,
+    metadata: {
+      sourceLanguage: language,
+      sourcePath,
+      beforeImportId: before?.id,
+      afterImportId: after?.id,
+      beforeHash,
+      afterHash,
+      changedSymbols: changedSymbols.length,
+      changedRegions: changedRegions.length,
+      semanticMergeConflictSummary: mergeConflictProfile.conflictSummary
+    }
+  });
+  const mergeCandidate = createSemanticMergeCandidateRecord({
+    id: input.mergeCandidateId ?? `merge_candidate_${idPart}_native_source_diff`,
+    importResultId: after?.id ?? before?.id,
+    patchId: patch.id,
+    language,
+    sourcePath,
+    baseHash: beforeHash,
+    targetHash: afterHash,
+    touchedSymbols: changedSymbols.map(nativeChangeTouchedSymbol),
+    touchedSemanticNodes: [],
+    nativeSpans: nativeChangeSpans(changedSymbols, changedRegions, { language, sourcePath }),
+    conflictKeys,
+    readiness,
+    reasons,
+    evidence,
+    conflictClasses: mergeConflictProfile.conflictClasses,
+    conflictSummary: mergeConflictProfile.conflictSummary,
+    metadata: {
+      kind: 'native-source-change-set',
+      beforeImportId: before?.id,
+      afterImportId: after?.id,
+      sourceChanged,
+      changeSummary: nativeSourceChangeSummary(changedSymbols, changedRegions, sourceChanged),
+      changedRegionProjectionSummary,
+      conflictClasses: mergeConflictProfile.conflictClasses,
+      conflictSummary: mergeConflictProfile.conflictSummary
+    }
+  });
+  return {
+    kind: 'frontier.lang.nativeSourceChangeSet',
+    version: 1,
+    id: input.id ?? `native_source_change_${idPart}`,
+    language,
+    sourcePath,
+    before,
+    after,
+    beforeHash,
+    afterHash,
+    changedSymbols,
+    changedRegions,
+    patch,
+    mergeCandidate,
+    evidence,
+    readiness,
+    reasons,
+    sourceMaps: uniqueRecordsById([...(before?.sourceMaps ?? []), ...(after?.sourceMaps ?? [])]),
+    semanticIndex: after?.semanticIndex ?? before?.semanticIndex,
+    losses: uniqueByLossId([...(before?.losses ?? []), ...(after?.losses ?? [])]),
+    summary: nativeSourceChangeSummary(changedSymbols, changedRegions, sourceChanged),
+    metadata: {
+      beforeSidecarId: beforeSidecar?.id,
+      afterSidecarId: afterSidecar?.id,
+      beforeImportContract: before?.metadata?.importResultContract,
+      afterImportContract: after?.metadata?.importResultContract,
+      changedRegionProjectionSummary,
+      semanticMergeConflictSummary: mergeConflictProfile.conflictSummary,
+      ...input.metadata
+    }
+  };
+}

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

@@ -0,0 +1,25 @@
+import{diffNativeSourceImports}from'./diffNativeSourceImports.js';
+export function diffNativeSources(input) {
+  const language = input.language ?? input.before?.language ?? input.after?.language;
+  if (!language) throw new Error('diffNativeSources requires a language');
+  const sourcePath = input.sourcePath ?? input.before?.sourcePath ?? input.after?.sourcePath;
+  return diffNativeSourceImports({
+    ...input,
+    before: input.before ?? (input.beforeSourceText === undefined ? undefined : {
+      language,
+      sourcePath,
+      sourceText: input.beforeSourceText,
+      sourceHash: input.beforeSourceHash,
+      parser: input.parser,
+      metadata: input.beforeMetadata
+    }),
+    after: input.after ?? (input.afterSourceText === undefined ? undefined : {
+      language,
+      sourcePath,
+      sourceText: input.afterSourceText,
+      sourceHash: input.afterSourceHash,
+      parser: input.parser,
+      metadata: input.afterMetadata
+    })
+  });
+}

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

@@ -0,0 +1,41 @@
+import{maxSemanticMergeReadiness,uniqueStrings}from'../../native-import-utils.js';
+import{nativeDiffSymbolChanged}from'./nativeDiffSymbolChanged.js';
+export function diffNativeSymbols(beforeSymbols, afterSymbols) {
+  const keys = uniqueStrings([...beforeSymbols.keys(), ...afterSymbols.keys()]).sort();
+  const changed = [];
+  for (const key of keys) {
+    const before = beforeSymbols.get(key);
+    const after = afterSymbols.get(key);
+    const changeKind = !before ? 'added' : !after ? 'removed' : nativeDiffSymbolChanged(before, after) ? 'modified' : 'unchanged';
+    if (changeKind === 'unchanged') continue;
+    const current = after ?? before;
+    changed.push({
+      changeKind,
+      key,
+      id: current.id,
+      name: current.name,
+      kind: current.kind,
+      language: current.language,
+      nativeAstNodeId: current.nativeAstNodeId,
+      semanticOccurrenceId: current.semanticOccurrenceId,
+      sourceMapMappingId: current.sourceMapMappingId,
+      sourceSpan: current.sourceSpan,
+      beforeSignatureHash: before?.signatureHash,
+      afterSignatureHash: after?.signatureHash,
+      beforeSpanHash: before?.spanHash,
+      afterSpanHash: after?.spanHash,
+      beforeNativeAstNodeId: before?.nativeAstNodeId,
+      afterNativeAstNodeId: after?.nativeAstNodeId,
+      beforeSourceSpan: before?.sourceSpan,
+      afterSourceSpan: after?.sourceSpan,
+      beforeOwnershipKey: before?.ownershipKey,
+      afterOwnershipKey: after?.ownershipKey,
+      ownershipRegionId: current.ownershipRegionId,
+      ownershipKey: current.ownershipKey,
+      ownershipRegionKind: current.ownershipRegionKind,
+      conflictKey: current.ownershipKey ? `region:${current.ownershipKey}` : `symbol:${current.id ?? key}`,
+      readiness: maxSemanticMergeReadiness(before?.readiness ?? 'ready', after?.readiness ?? 'ready')
+    });
+  }
+  return changed;
+}

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

@@ -0,0 +1,6 @@
+import{nativeAstNodes}from'./nativeAstNodes.js';
+export function effectiveAdapterExactness(declared, observed) {
+  if (declared.exactAst || observed.exactAst) return declared.exactness ?? 'exact-parser-ast';
+  if (observed.nativeAstNodes > 0) return observed.exactness ?? 'adapter-reported-native-ast';
+  return declared.exactness ?? 'unknown';
+}

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

@@ -0,0 +1,21 @@
+import{effectiveAdapterExactness}from'./effectiveAdapterExactness.js';import{freezeNativeImporterAdapterCoverageSnapshot}from'./freezeNativeImporterAdapterCoverageSnapshot.js';import{maxSemanticCoverageLevel}from'./maxSemanticCoverageLevel.js';import{normalizeNativeImporterSemanticCoverage}from'./normalizeNativeImporterSemanticCoverage.js';
+export function effectiveNativeImporterAdapterCoverage(declared, observed) {
+  const semanticCoverage = normalizeNativeImporterSemanticCoverage({
+    level: maxSemanticCoverageLevel(declared.semanticCoverage?.level, observed.semanticCoverage?.level),
+    declarations: declared.semanticCoverage?.declarations || observed.semanticCoverage?.declarations,
+    symbols: declared.semanticCoverage?.symbols || observed.semanticCoverage?.symbols,
+    references: declared.semanticCoverage?.references || observed.semanticCoverage?.references,
+    types: declared.semanticCoverage?.types || observed.semanticCoverage?.types,
+    controlFlow: declared.semanticCoverage?.controlFlow || observed.semanticCoverage?.controlFlow
+  }, {});
+  return freezeNativeImporterAdapterCoverageSnapshot({
+    exactness: effectiveAdapterExactness(declared, observed),
+    exactAst: declared.exactAst || observed.exactAst,
+    tokens: declared.tokens || observed.tokens,
+    trivia: declared.trivia || observed.trivia,
+    diagnostics: declared.diagnostics || observed.parserDiagnostics > 0,
+    sourceRanges: declared.sourceRanges || observed.sourceRanges,
+    generatedRanges: declared.generatedRanges || observed.generatedRanges,
+    semanticCoverage
+  });
+}

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

@@ -0,0 +1,4 @@
+import{projectFrontierAst}from'./projectFrontierAst.js';import{renderTargetAst}from'./renderTargetAst.js';
+export function emitForTarget(document, target = 'typescript', options = {}) {
+  return renderTargetAst(projectFrontierAst(document, target, options), target);
+}

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

@@ -0,0 +1,11 @@
+import{idFragment}from'../../native-import-utils.js';
+import{normalizeCompileTarget}from'./normalizeCompileTarget.js';import{projectFrontierAst}from'./projectFrontierAst.js';import{renderTargetAstWithSourceMap}from'./renderTargetAstWithSourceMap.js';
+export function emitForTargetWithSourceMap(document, target = 'typescript', options = {}) {
+  const normalized = normalizeCompileTarget(target);
+  const ast = projectFrontierAst(document, normalized, options);
+  const result = renderTargetAstWithSourceMap(ast, normalized, {
+    sourceMapId: options.sourceMapId ?? `sourcemap_${idFragment(document.id)}_${normalized}`,
+    ...options
+  });
+  return { ...result, ast };
+}

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

@@ -0,0 +1,4 @@
+export function ensureTrailingNewline(value) {
+  const text = String(value ?? '');
+  return text.endsWith('\n') ? text : `${text}\n`;
+}

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

@@ -0,0 +1,51 @@
+import{addSet}from'./addSet.js';import{semanticSliceMappingTouchesSets}from'./semanticSliceMappingTouchesSets.js';import{semanticSliceNativeParentMap}from'./semanticSliceNativeParentMap.js';import{semanticSliceRegionTouchesSets}from'./semanticSliceRegionTouchesSets.js';import{semanticSliceSymbolTouchesSets}from'./semanticSliceSymbolTouchesSets.js';
+export function expandSemanticSliceSelection(records, selection) {
+  let changed = true;
+  let depth = 0;
+  const childToParent = semanticSliceNativeParentMap(records.nativeNodes);
+  while (changed && depth <= selection.maxDependencyDepth) {
+    changed = false;
+    for (const mapping of records.mappings) {
+      if (!semanticSliceMappingTouchesSets(mapping, selection)) continue;
+      changed = addSet(selection.selectedMappings, mapping.id) || changed;
+      if (mapping.semanticSymbolId) changed = addSet(selection.selectedSymbols, mapping.semanticSymbolId) || changed;
+      if (mapping.nativeAstNodeId) changed = addSet(selection.selectedNativeNodes, mapping.nativeAstNodeId) || changed;
+      if (mapping.ownershipRegionId) changed = addSet(selection.selectedRegions, mapping.ownershipRegionId) || changed;
+    }
+    for (const symbol of records.symbols) {
+      if (!semanticSliceSymbolTouchesSets(symbol, selection)) continue;
+      changed = addSet(selection.selectedSymbols, symbol.id) || changed;
+      if (symbol.nativeAstNodeId) changed = addSet(selection.selectedNativeNodes, symbol.nativeAstNodeId) || changed;
+      const regionId = symbol.ownershipRegionId ?? symbol.metadata?.ownershipRegionId;
+      if (regionId) changed = addSet(selection.selectedRegions, regionId) || changed;
+    }
+    for (const region of records.regions) {
+      if (!semanticSliceRegionTouchesSets(region, selection)) continue;
+      changed = addSet(selection.selectedRegions, region.id) || changed;
+      if (region.symbolId) changed = addSet(selection.selectedSymbols, region.symbolId) || changed;
+      if (region.nativeAstNodeId) changed = addSet(selection.selectedNativeNodes, region.nativeAstNodeId) || changed;
+    }
+    for (const occurrence of records.occurrences) {
+      if (!selection.selectedSymbols.has(occurrence.symbolId) && !selection.selectedNativeNodes.has(occurrence.nativeAstNodeId)) continue;
+      changed = addSet(selection.selectedOccurrences, occurrence.id) || changed;
+      if (occurrence.symbolId) changed = addSet(selection.selectedSymbols, occurrence.symbolId) || changed;
+      if (occurrence.nativeAstNodeId) changed = addSet(selection.selectedNativeNodes, occurrence.nativeAstNodeId) || changed;
+    }
+    if (selection.includeDependencies) {
+      for (const relation of records.relations) {
+        const touches = selection.selectedSymbols.has(relation.sourceId) || selection.selectedSymbols.has(relation.targetId);
+        if (!touches) continue;
+        changed = addSet(selection.selectedRelations, relation.id) || changed;
+        if (relation.sourceId && records.symbolById.has(relation.sourceId)) changed = addSet(selection.selectedSymbols, relation.sourceId) || changed;
+        if (relation.targetId && records.symbolById.has(relation.targetId)) changed = addSet(selection.selectedSymbols, relation.targetId) || changed;
+      }
+      for (const node of records.nativeNodes) {
+        if (!selection.selectedNativeNodes.has(node.id)) continue;
+        for (const child of node.children ?? []) changed = addSet(selection.selectedNativeNodes, child) || changed;
+        const parent = childToParent.get(node.id);
+        if (parent) changed = addSet(selection.selectedNativeNodes, parent) || changed;
+      }
+    }
+    depth += 1;
+  }
+}

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

@@ -0,0 +1,22 @@
+import{idFragment}from'../../native-import-utils.js';
+import{normalizeExternalSpan}from'./normalizeExternalSpan.js';
+export function externalDiagnosticFact(diagnostic, context, documentId, sourcePath, index) {
+  return {
+    id: diagnostic.id ? `fact_${idFragment(diagnostic.id)}_diagnostic` : `fact_${context.idPart}_${idFragment(sourcePath)}_diagnostic_${index + 1}`,
+    predicate: `${context.format}.diagnostic`,
+    subjectId: documentId,
+    value: {
+      severity: diagnostic.severity,
+      code: diagnostic.code,
+      message: diagnostic.message,
+      source: diagnostic.source,
+      tags: diagnostic.tags,
+      range: diagnostic.range,
+      span: normalizeExternalSpan(diagnostic.range ?? diagnostic.span, sourcePath, context.sourceHash)
+    },
+    metadata: {
+      format: context.format,
+      source: 'external-semantic-index'
+    }
+  };
+}

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

@@ -0,0 +1,20 @@
+import{idFragment}from'../../native-import-utils.js';
+import{externalDiagnosticSeverity}from'./externalDiagnosticSeverity.js';import{normalizeExternalSpan}from'./normalizeExternalSpan.js';
+export function externalDiagnosticLoss(diagnostic, context, sourcePath) {
+  const severity = externalDiagnosticSeverity(diagnostic.severity);
+  return {
+    id: diagnostic.id ?? `loss_${context.idPart}_${idFragment(diagnostic.code ?? diagnostic.message ?? severity)}_${idFragment(sourcePath)}`,
+    severity,
+    phase: 'index',
+    sourceFormat: context.format,
+    kind: severity === 'error' ? 'unsupportedSemantic' : 'partialSemanticIndex',
+    message: String(diagnostic.message ?? `${context.format} diagnostic reported ${severity}.`),
+    span: normalizeExternalSpan(diagnostic.range ?? diagnostic.span, sourcePath, context.sourceHash),
+    metadata: {
+      format: context.format,
+      code: diagnostic.code,
+      source: diagnostic.source,
+      tags: diagnostic.tags
+    }
+  };
+}

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

@@ -0,0 +1,7 @@
+export function externalDiagnosticSeverity(value) {
+  if (value === undefined || value === null || value === '') return 'error';
+  const raw = String(value).toLowerCase();
+  if (raw === '1' || raw.includes('error')) return 'error';
+  if (raw === '3' || raw.includes('info') || raw.includes('hint')) return 'info';
+  return 'warning';
+}

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

@@ -0,0 +1,12 @@
+import{idFragment}from'../../native-import-utils.js';
+import{normalizeExternalSemanticLanguage}from'./normalizeExternalSemanticLanguage.js';import{uriToPath}from'./uriToPath.js';
+export function externalDocument(document, context, index) {
+  const path = document.path ?? document.uri ?? document.relative_path ?? document.relativePath ?? context.sourcePath ?? `external-document-${index + 1}`;
+  return {
+    id: document.id ?? `doc_${idFragment(path)}`,
+    path: uriToPath(path) ?? path,
+    language: normalizeExternalSemanticLanguage(document.language ?? document.languageId ?? context.language),
+    sourceHash: document.sourceHash ?? document.md5 ?? context.sourceHash,
+    metadata: { format: context.format, ...document.metadata }
+  };
+}

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

@@ -0,0 +1,10 @@
+export function externalFact(fact, context, index) {
+  return {
+    ...fact,
+    id: fact.id ?? `fact_${context.idPart}_${index + 1}`,
+    predicate: fact.predicate ?? fact.kind ?? 'externalFact',
+    subjectId: fact.subjectId ?? fact.subject_id ?? fact.symbolId ?? fact.symbol_id ?? `external:${context.format}`,
+    value: fact.value ?? fact.data ?? fact,
+    metadata: { format: context.format, ...fact.metadata }
+  };
+}

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

@@ -0,0 +1,23 @@
+export const externalLanguageNameByNumber = Object.freeze({
+  1: 'csharp',
+  2: 'swift',
+  3: 'dart',
+  4: 'kotlin',
+  5: 'scala',
+  6: 'java',
+  15: 'python',
+  16: 'ruby',
+  17: 'elixir',
+  18: 'erlang',
+  19: 'php',
+  22: 'javascript',
+  23: 'typescript',
+  33: 'go',
+  34: 'c',
+  35: 'cpp',
+  38: 'zig',
+  40: 'rust',
+  44: 'haskell',
+  54: 'r',
+  69: 'sql'
+});

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

@@ -0,0 +1,13 @@
+import{idFragment}from'../../native-import-utils.js';
+import{normalizeExternalOccurrenceRole}from'./normalizeExternalOccurrenceRole.js';import{normalizeExternalSpan}from'./normalizeExternalSpan.js';
+export function externalOccurrence(occurrence, context, index) {
+  return {
+    ...occurrence,
+    id: occurrence.id ?? `occ_${context.idPart}_${index + 1}`,
+    documentId: occurrence.documentId ?? occurrence.document_id ?? `doc_${idFragment(occurrence.path ?? context.sourcePath ?? context.format)}`,
+    symbolId: occurrence.symbolId ?? occurrence.symbol_id ?? occurrence.symbol ?? `symbol:${context.format}:unknown`,
+    role: normalizeExternalOccurrenceRole(occurrence.role),
+    span: normalizeExternalSpan(occurrence.span ?? occurrence.range, occurrence.path ?? context.sourcePath, context.sourceHash),
+    metadata: { format: context.format, ...occurrence.metadata }
+  };
+}

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

@@ -0,0 +1,10 @@
+export function externalRelation(relation, context, index) {
+  return {
+    ...relation,
+    id: relation.id ?? `rel_${context.idPart}_${index + 1}`,
+    sourceId: relation.sourceId ?? relation.source_id ?? relation.subjectId ?? relation.subject_id ?? `external:${context.format}`,
+    predicate: relation.predicate ?? relation.label ?? relation.kind ?? 'related',
+    targetId: relation.targetId ?? relation.target_id ?? relation.objectId ?? relation.object_id ?? relation.symbol ?? `external:${context.format}`,
+    metadata: { format: context.format, ...relation.metadata }
+  };
+}

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

@@ -0,0 +1,8 @@
+export function externalRelationPredicateForOccurrence(occurrence) {
+  const role = String(occurrence.role ?? '').toLowerCase();
+  if (role === 'definition' || role === 'declaration') return 'defines';
+  if (role === 'import') return 'imports';
+  if (role === 'write') return 'writes';
+  if (role === 'read') return 'reads';
+  return 'references';
+}

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

@@ -0,0 +1,15 @@
+import{externalSemanticCoverageLoss}from'./externalSemanticCoverageLoss.js';import{externalSemanticEvidence}from'./externalSemanticEvidence.js';
+export function externalSemanticBase(context, metadata = {}) {
+  return {
+    repository: context.projectRoot ? { root: context.projectRoot } : undefined,
+    documents: [],
+    symbols: [],
+    occurrences: [],
+    relations: [],
+    facts: [],
+    evidence: [externalSemanticEvidence(context, 'passed', `Imported ${context.format} semantic index payload.`)],
+    losses: [externalSemanticCoverageLoss(context)],
+    semanticStatus: 'external-semantic-index',
+    metadata
+  };
+}

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

@@ -0,0 +1,17 @@
+import{idFragment}from'../../native-import-utils.js';
+export function externalSemanticCoverageLoss(context) {
+  return {
+    id: `loss_${context.idPart}_${idFragment(context.format)}_partial_semantic_index`,
+    severity: 'info',
+    phase: 'index',
+    sourceFormat: context.format,
+    kind: 'partialSemanticIndex',
+    message: `${context.format} payload imported symbols, occurrences, and facts as external semantic evidence; full parser AST, comments, trivia, and executable semantics still require a native parser adapter.`,
+    semanticIndexId: context.semanticIndexId,
+    metadata: {
+      format: context.format,
+      parser: context.parser,
+      source: 'external-semantic-index'
+    }
+  };
+}

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

@@ -0,0 +1,16 @@
+import{idFragment}from'../../native-import-utils.js';
+export function externalSemanticEvidence(context, status, summary, metadata = {}) {
+  return {
+    id: `evidence_${context.idPart}_${idFragment(context.format)}_external_semantic_index`,
+    kind: 'import',
+    status,
+    path: context.sourcePath,
+    summary,
+    metadata: {
+      format: context.format,
+      parser: context.parser,
+      projectRoot: context.projectRoot,
+      ...metadata
+    }
+  };
+}

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

@@ -0,0 +1,26 @@
+import{idFragment}from'../../native-import-utils.js';
+export function externalSemanticSourceMapMappings(semanticIndex, context) {
+  const symbolsById = new Map((semanticIndex.symbols ?? []).map((symbol) => [symbol.id, symbol]));
+  const evidenceIds = (context.evidence ?? []).map((record) => record.id).filter(Boolean);
+  const lossIds = (context.losses ?? []).map((loss) => loss.id).filter(Boolean);
+  return (semanticIndex.occurrences ?? [])
+    .filter((occurrence) => occurrence.span)
+    .map((occurrence, index) => {
+      const symbol = symbolsById.get(occurrence.symbolId);
+      return {
+        id: `map_${idFragment(occurrence.id ?? `${occurrence.symbolId}_${index + 1}`)}`,
+        semanticSymbolId: occurrence.symbolId,
+        semanticOccurrenceId: occurrence.id,
+        sourceSpan: occurrence.span,
+        evidenceIds,
+        lossIds,
+        ownershipRegionId: symbol?.metadata?.ownershipRegionId,
+        ownershipRegionKey: symbol?.metadata?.ownershipRegionKey,
+        ownershipRegionKind: symbol?.metadata?.ownershipRegionKind,
+        precision: occurrence.span ? 'declaration' : 'unknown',
+        metadata: {
+          source: 'external-semantic-index'
+        }
+      };
+    });
+}

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

@@ -0,0 +1,14 @@
+import{nameFromExternalSymbol}from'./nameFromExternalSymbol.js';import{normalizeExternalSemanticLanguage}from'./normalizeExternalSemanticLanguage.js';import{normalizeExternalSpan}from'./normalizeExternalSpan.js';import{normalizeExternalSymbolKind}from'./normalizeExternalSymbolKind.js';
+export function externalSymbol(symbol, context, index) {
+  const id = symbol.id ?? symbol.symbolId ?? symbol.symbol ?? `symbol:${context.format}:${index + 1}`;
+  return {
+    ...symbol,
+    id: String(id),
+    scheme: symbol.scheme ?? context.format,
+    name: symbol.name ?? symbol.display_name ?? symbol.displayName ?? nameFromExternalSymbol(id),
+    kind: normalizeExternalSymbolKind(symbol.kind),
+    language: normalizeExternalSemanticLanguage(symbol.language ?? context.language),
+    definitionSpan: normalizeExternalSpan(symbol.definitionSpan ?? symbol.span, context.sourcePath, context.sourceHash),
+    metadata: { format: context.format, rawSymbol: symbol.symbol, ...symbol.metadata }
+  };
+}

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

@@ -0,0 +1,32 @@
+export const externalSymbolKindByNumber = Object.freeze({
+  1: 'array',
+  2: 'assertion',
+  3: 'associatedType',
+  4: 'attribute',
+  7: 'class',
+  8: 'constant',
+  9: 'constructor',
+  11: 'enum',
+  12: 'enumMember',
+  13: 'event',
+  15: 'field',
+  16: 'file',
+  17: 'function',
+  21: 'interface',
+  25: 'macro',
+  26: 'method',
+  28: 'message',
+  29: 'module',
+  30: 'namespace',
+  35: 'package',
+  37: 'parameter',
+  41: 'property',
+  42: 'protocol',
+  49: 'struct',
+  53: 'trait',
+  54: 'type',
+  55: 'typeAlias',
+  58: 'typeParameter',
+  61: 'variable',
+  66: 'abstractMethod'
+});

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

@@ -0,0 +1,23 @@
+import{idFragment}from'../../native-import-utils.js';
+export function fileLevelNativeChangeRegion(input) {
+  const sourcePath = input.sourcePath ?? input.after?.sourcePath ?? input.before?.sourcePath;
+  const key = ['source', sourcePath ?? `${input.language}:memory`, 'file'].join('#');
+  return {
+    id: `region_${idFragment(key)}`,
+    key,
+    changeKind: 'modified',
+    regionKind: 'body',
+    granularity: 'file',
+    language: input.language,
+    sourcePath,
+    sourceHash: input.afterHash ?? input.beforeHash,
+    precision: 'unknown',
+    mergePolicy: 'file-level-review-required',
+    conflictKey: `region:${key}`,
+    metadata: {
+      reason: 'source-hash-changed-without-symbol-diff',
+      beforeHash: input.beforeHash,
+      afterHash: input.afterHash
+    }
+  };
+}

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

@@ -0,0 +1,6 @@
+export function findSemanticImportRegion(sidecar, region) {
+  return (sidecar?.ownershipRegions ?? []).find((candidate) => (
+    (region.id && candidate.id === region.id) ||
+    (region.key && candidate.key === region.key)
+  ));
+}