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

package/dist/semantic-import-contract-summary.js

@@ -0,0 +1,188 @@
+import { countBy, idFragment, maxSemanticMergeReadiness, normalizeStringList, uniqueRecordsById, uniqueStrings } from './native-import-utils.js';
+import { semanticImportSidecarEntry } from './semantic-import-sidecar-entry.js';
+import { summarizeSemanticImportRegionTaxonomy } from './semantic-import-regions.js';
+
+function collectImportSourceMaps(importResult, imports) {
+  return uniqueRecordsById([
+    ...(importResult?.sourceMaps ?? importResult?.universalAst?.sourceMaps ?? []),
+    ...imports.flatMap((imported) => imported?.sourceMaps ?? imported?.universalAst?.sourceMaps ?? [])
+  ]);
+}
+
+function summarizeImportSourceMaps(sourceMaps) {
+  const mappings = sourceMaps.flatMap((sourceMap) => sourceMap?.mappings ?? []);
+  return {
+    total: sourceMaps.length,
+    ids: sourceMaps.map((sourceMap) => sourceMap.id).filter(Boolean),
+    mappingCount: mappings.length,
+    sourcePaths: uniqueStrings([
+      ...sourceMaps.map((sourceMap) => sourceMap.sourcePath),
+      ...mappings.map((mapping) => mapping.sourceSpan?.path)
+    ].filter(Boolean)),
+    targetPaths: uniqueStrings([
+      ...sourceMaps.map((sourceMap) => sourceMap.targetPath ?? sourceMap.target?.emitPath),
+      ...mappings.map((mapping) => mapping.generatedSpan?.targetPath ?? mapping.target?.emitPath)
+    ].filter(Boolean)),
+    byPrecision: countBy(mappings.map((mapping) => mapping.precision ?? 'unknown')),
+    sourceRangeMappings: mappings.filter((mapping) => mapping.sourceSpan).length,
+    generatedRangeMappings: mappings.filter((mapping) => mapping.generatedSpan).length
+  };
+}
+
+function summarizeImportRegions(importResult, imports, options = {}) {
+  const entries = imports.map((imported, index) => semanticImportSidecarEntry(imported, index, options));
+  const regions = uniqueRecordsById(entries.flatMap((entry) => entry.ownershipRegions ?? []));
+  const taxonomy = summarizeSemanticImportRegionTaxonomy(regions);
+  return {
+    total: regions.length,
+    ids: regions.map((region) => region.id),
+    keys: regions.map((region) => region.key),
+    sourcePaths: uniqueStrings(regions.map((region) => region.sourcePath).filter(Boolean)),
+    byKind: taxonomy.byKind,
+    byGranularity: countBy(regions.map((region) => region.granularity ?? 'unknown')),
+    byPrecision: countBy(regions.map((region) => region.precision ?? 'unknown')),
+    byLanguage: countBy(regions.map((region) => region.language ?? importResult?.language ?? 'unknown')),
+    symbolIds: uniqueStrings(regions.map((region) => region.symbolId).filter(Boolean)),
+    taxonomy
+  };
+}
+
+function summarizeImportAdapterCoverage(importResult, imports) {
+  const records = uniqueAdapterCoverageRecords([
+    compactAdapterCoverageRecord(importResult),
+    ...imports.map((imported) => compactAdapterCoverageRecord(imported))
+  ].filter(Boolean));
+  const observed = records.reduce((totals, record) => {
+    for (const key of ['diagnostics', 'losses', 'nativeAstNodes', 'semanticSymbols', 'sourceMapMappings']) {
+      totals[key] += record.observed?.[key] ?? 0;
+    }
+    totals.sourceRanges = totals.sourceRanges || record.observed?.sourceRanges === true;
+    totals.generatedRanges = totals.generatedRanges || record.observed?.generatedRanges === true;
+    return totals;
+  }, {
+    diagnostics: 0,
+    losses: 0,
+    nativeAstNodes: 0,
+    semanticSymbols: 0,
+    sourceMapMappings: 0,
+    sourceRanges: false,
+    generatedRanges: false
+  });
+  return {
+    total: records.length,
+    adapterIds: uniqueStrings(records.map((record) => record.adapterId).filter(Boolean)),
+    parsers: uniqueStrings(records.map((record) => record.parser).filter(Boolean)),
+    exactness: uniqueStrings(records.map((record) => record.exactness).filter(Boolean)),
+    exactAst: records.filter((record) => record.exactAst).length,
+    tokens: records.filter((record) => record.tokens).length,
+    trivia: records.filter((record) => record.trivia).length,
+    diagnostics: records.filter((record) => record.diagnostics).length,
+    sourceRanges: records.filter((record) => record.sourceRanges).length,
+    generatedRanges: records.filter((record) => record.generatedRanges).length,
+    semanticCoverageLevels: uniqueStrings(records.map((record) => record.semanticCoverage?.level).filter(Boolean)),
+    observed,
+    records
+  };
+}
+
+function compactAdapterCoverageRecord(imported) {
+  const nativeAst = imported?.nativeAst ?? imported?.nativeSource?.ast;
+  const nativeSource = imported?.nativeSource;
+  const coverage = imported?.adapter?.coverage
+    ?? imported?.metadata?.adapterCoverage
+    ?? nativeAst?.metadata?.adapterCoverage
+    ?? nativeSource?.metadata?.adapterCoverage;
+  if (!coverage) return undefined;
+  return {
+    adapterId: imported?.adapter?.id ?? imported?.metadata?.adapterId ?? nativeAst?.metadata?.adapterId ?? nativeSource?.metadata?.adapterId,
+    adapterVersion: imported?.adapter?.version ?? imported?.metadata?.adapterVersion ?? nativeAst?.metadata?.adapterVersion ?? nativeSource?.metadata?.adapterVersion,
+    parser: imported?.adapter?.parser ?? nativeAst?.parser ?? nativeSource?.parser ?? imported?.metadata?.parser,
+    capabilities: uniqueStrings(imported?.adapter?.capabilities ?? imported?.metadata?.adapterCapabilities ?? []),
+    supportedExtensions: uniqueStrings(imported?.adapter?.supportedExtensions ?? imported?.metadata?.supportedExtensions ?? []),
+    exactness: coverage.exactness,
+    exactAst: Boolean(coverage.exactAst),
+    tokens: Boolean(coverage.tokens),
+    trivia: Boolean(coverage.trivia),
+    diagnostics: Boolean(coverage.diagnostics),
+    sourceRanges: Boolean(coverage.sourceRanges),
+    generatedRanges: Boolean(coverage.generatedRanges),
+    semanticCoverage: coverage.semanticCoverage,
+    observed: coverage.observed,
+    notes: uniqueStrings(coverage.notes ?? [])
+  };
+}
+
+function uniqueAdapterCoverageRecords(records) {
+  const seen = new Set();
+  const result = [];
+  for (const record of records) {
+    const key = [record.adapterId, record.adapterVersion, record.parser, record.exactness].join('#');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(record);
+  }
+  return result;
+}
+
+function compactImportContractSource(imported, index) {
+  const nativeAst = imported?.nativeAst ?? imported?.nativeSource?.ast;
+  const nativeSource = imported?.nativeSource;
+  const semanticIndex = imported?.semanticIndex ?? imported?.universalAst?.semanticIndex;
+  const sourceMaps = collectImportSourceMaps(imported, [imported].filter(Boolean));
+  return {
+    id: imported?.id ?? `import_${index + 1}`,
+    language: imported?.language ?? nativeSource?.language ?? nativeAst?.language,
+    sourcePath: imported?.sourcePath ?? nativeSource?.sourcePath ?? nativeAst?.sourcePath,
+    sourceHash: nativeSource?.sourceHash ?? nativeAst?.sourceHash,
+    parser: nativeAst?.parser ?? nativeSource?.parser,
+    nativeSourceId: nativeSource?.id,
+    nativeAstId: nativeAst?.id,
+    semanticIndexId: semanticIndex?.id,
+    universalAstId: imported?.universalAst?.id,
+    patchId: imported?.patch?.id,
+    sourceMapIds: sourceMaps.map((sourceMap) => sourceMap.id).filter(Boolean),
+    sourceMapMappings: sourceMaps.reduce((sum, sourceMap) => sum + (sourceMap.mappings?.length ?? 0), 0),
+    symbolCount: semanticIndex?.symbols?.length ?? 0,
+    lossCount: imported?.losses?.length ?? nativeAst?.losses?.length ?? 0,
+    evidenceCount: imported?.evidence?.length ?? 0,
+    readiness: imported?.metadata?.semanticMergeReadiness ?? imported?.mergeCandidates?.[0]?.readiness
+  };
+}
+
+function summarizeImportContractReadiness(importResult, mergeCandidates, lossSummary) {
+  const candidateReadiness = mergeCandidates.reduce(
+    (current, candidate) => maxSemanticMergeReadiness(current, candidate.readiness),
+    lossSummary.semanticMergeReadiness
+  );
+  const semanticMergeReadiness = maxSemanticMergeReadiness(
+    importResult?.metadata?.semanticMergeReadiness ?? lossSummary.semanticMergeReadiness,
+    candidateReadiness
+  );
+  return {
+    semanticMergeReadiness,
+    severityReadiness: lossSummary.semanticMergeReadiness,
+    reasons: uniqueStrings([
+      ...(lossSummary.readinessReasons ?? []),
+      ...mergeCandidates.flatMap((candidate) => candidate?.reasons ?? []),
+      ...normalizeStringList(importResult?.metadata?.readinessReasons)
+    ]),
+    failedEvidenceIds: lossSummary.failedEvidenceIds,
+    blockingLossIds: lossSummary.blockingLossIds,
+    reviewLossIds: lossSummary.reviewLossIds,
+    informationalLossIds: lossSummary.informationalLossIds
+  };
+}
+
+function defaultSemanticImportSidecarId(importResult, imports = []) {
+  return `semantic_import_${idFragment(importResult?.id ?? importResult?.projectRoot ?? imports[0]?.sourcePath ?? imports[0]?.language ?? 'source')}`;
+}
+
+export {
+  collectImportSourceMaps,
+  compactImportContractSource,
+  defaultSemanticImportSidecarId,
+  summarizeImportAdapterCoverage,
+  summarizeImportContractReadiness,
+  summarizeImportRegions,
+  summarizeImportSourceMaps
+};

package/dist/semantic-import-layers.js

@@ -0,0 +1,320 @@
+import { uniqueStrings } from './native-import-utils.js';
+
+function summarizeSemanticImportSidecarProofSpec(importEntries) {
+  const byStatus = {};
+  const byReadinessStatus = {};
+  const byContractKind = {};
+  const byArtifactKind = {};
+  const ids = [];
+  const contractKinds = [];
+  const artifactKinds = [];
+  const totals = {
+    total: 0,
+    contracts: 0,
+    refinements: 0,
+    invariants: 0,
+    termination: 0,
+    temporal: 0,
+    obligations: 0,
+    artifacts: 0,
+    assumptions: 0,
+    evidence: 0,
+    discharged: 0,
+    pending: 0,
+    failed: 0,
+    open: 0,
+    unknown: 0,
+    stale: 0,
+    assumed: 0,
+    externalToolRequired: 0
+  };
+  for (const entry of importEntries) {
+    const proof = entry.proofSpec ?? summarizeProofSpecLayer();
+    ids.push(...(proof.ids ?? []));
+    contractKinds.push(...(proof.contractKinds ?? []));
+    artifactKinds.push(...(proof.artifactKinds ?? []));
+    for (const key of Object.keys(totals)) {
+      totals[key] += proof[key] ?? 0;
+    }
+    for (const [status, count] of Object.entries(proof.byStatus ?? {})) {
+      byStatus[status] = (byStatus[status] ?? 0) + count;
+    }
+    for (const [status, count] of Object.entries(proof.byReadinessStatus ?? {})) {
+      byReadinessStatus[status] = (byReadinessStatus[status] ?? 0) + count;
+    }
+    for (const [kind, count] of Object.entries(proof.byContractKind ?? {})) {
+      byContractKind[kind] = (byContractKind[kind] ?? 0) + count;
+    }
+    for (const [kind, count] of Object.entries(proof.byArtifactKind ?? {})) {
+      byArtifactKind[kind] = (byArtifactKind[kind] ?? 0) + count;
+    }
+  }
+  return {
+    ...totals,
+    ids: uniqueStrings(ids),
+    contractKinds: uniqueStrings(contractKinds),
+    artifactKinds: uniqueStrings(artifactKinds),
+    byStatus,
+    byReadinessStatus,
+    byContractKind,
+    byArtifactKind,
+    empty: totals.total === 0
+  };
+}
+
+const ParadigmSemanticSummaryGroups = Object.freeze([
+  'bindingScopes',
+  'bindings',
+  'patterns',
+  'typeConstraints',
+  'evaluationModels',
+  'memoryLocations',
+  'effectRegions',
+  'controlRegions',
+  'logicPrograms',
+  'actorSystems',
+  'stackEffects',
+  'arrayShapes',
+  'numericKernels',
+  'dataflowNetworks',
+  'clockModels',
+  'objectModels',
+  'macroExpansions',
+  'reflectionBoundaries',
+  'loweringRecords'
+]);
+
+function summarizeSemanticImportSidecarParadigmSemantics(importEntries) {
+  const totals = emptyParadigmSemanticsSummary();
+  const ids = [];
+  const kinds = [];
+  const byGroup = {};
+  const byKind = {};
+  for (const entry of importEntries) {
+    const summary = entry.paradigmSemantics ?? summarizeParadigmSemanticsLayer();
+    ids.push(...(summary.ids ?? []));
+    kinds.push(...(summary.kinds ?? []));
+    totals.total += summary.total ?? 0;
+    totals.evidence += summary.evidence ?? 0;
+    for (const group of ParadigmSemanticSummaryGroups) {
+      totals[group] += summary[group] ?? 0;
+    }
+    for (const [group, count] of Object.entries(summary.byGroup ?? {})) {
+      byGroup[group] = (byGroup[group] ?? 0) + count;
+    }
+    for (const [kind, count] of Object.entries(summary.byKind ?? {})) {
+      byKind[kind] = (byKind[kind] ?? 0) + count;
+    }
+  }
+  return {
+    ...totals,
+    ids: uniqueStrings(ids),
+    groups: uniqueStrings(Object.keys(byGroup).filter((group) => byGroup[group] > 0)),
+    kinds: uniqueStrings(kinds),
+    byGroup,
+    byKind,
+    hasRuntimeSemantics: hasAnyParadigmCount(totals, ['evaluationModels', 'memoryLocations', 'effectRegions', 'controlRegions', 'actorSystems', 'clockModels']),
+    hasLogicSemantics: totals.logicPrograms > 0,
+    hasStackSemantics: totals.stackEffects > 0,
+    hasArraySemantics: totals.arrayShapes > 0 || totals.numericKernels > 0,
+    hasMacroOrReflection: totals.macroExpansions > 0 || totals.reflectionBoundaries > 0,
+    hasLowering: totals.loweringRecords > 0,
+    empty: totals.total === 0
+  };
+}
+
+function summarizeParadigmSemanticsLayer(paradigmSemantics = {}) {
+  const totals = emptyParadigmSemanticsSummary();
+  const ids = [];
+  const kinds = [];
+  const byGroup = {};
+  const byKind = {};
+  ids.push(paradigmSemantics?.id);
+  for (const group of ParadigmSemanticSummaryGroups) {
+    const records = paradigmSemantics?.[group] ?? [];
+    totals[group] = records.length;
+    totals.total += records.length;
+    if (records.length > 0) {
+      byGroup[group] = records.length;
+    }
+    for (const record of records) {
+      ids.push(record?.id);
+      if (record?.kind) {
+        kinds.push(record.kind);
+        byKind[record.kind] = (byKind[record.kind] ?? 0) + 1;
+      }
+    }
+  }
+  totals.evidence = (paradigmSemantics?.evidence ?? []).length;
+  ids.push(...(paradigmSemantics?.evidence ?? []).map((record) => record?.id));
+  return {
+    ...totals,
+    ids: uniqueStrings(ids.filter(Boolean)),
+    groups: uniqueStrings(Object.keys(byGroup)),
+    kinds: uniqueStrings(kinds),
+    byGroup,
+    byKind,
+    hasRuntimeSemantics: hasAnyParadigmCount(totals, ['evaluationModels', 'memoryLocations', 'effectRegions', 'controlRegions', 'actorSystems', 'clockModels']),
+    hasLogicSemantics: totals.logicPrograms > 0,
+    hasStackSemantics: totals.stackEffects > 0,
+    hasArraySemantics: totals.arrayShapes > 0 || totals.numericKernels > 0,
+    hasMacroOrReflection: totals.macroExpansions > 0 || totals.reflectionBoundaries > 0,
+    hasLowering: totals.loweringRecords > 0,
+    empty: totals.total === 0
+  };
+}
+
+function emptyParadigmSemanticsSummary() {
+  return {
+    total: 0,
+    evidence: 0,
+    ...Object.fromEntries(ParadigmSemanticSummaryGroups.map((group) => [group, 0]))
+  };
+}
+
+function hasAnyParadigmCount(summary, groups) {
+  return groups.some((group) => (summary[group] ?? 0) > 0);
+}
+
+const ProofObligationStatusAliases = Object.freeze({
+  accepted: 'discharged', checked: 'discharged', ok: 'discharged', passed: 'discharged',
+  proved: 'discharged', qed: 'discharged', success: 'discharged', succeeded: 'discharged',
+  valid: 'discharged', verified: 'discharged',
+  counterexample: 'failed', cex: 'failed', error: 'failed', falsified: 'failed',
+  invalid: 'failed', rejected: 'failed', violated: 'failed',
+  pending: 'pending', todo: 'pending', unproved: 'pending', unverified: 'pending',
+  obsolete: 'stale', outdated: 'stale', admit: 'assumed', admitted: 'assumed',
+  assume: 'assumed', axiom: 'assumed', trusted: 'assumed', unchecked: 'assumed',
+  'solver-required': 'external-tool-required', 'prover-required': 'external-tool-required', 'tool-required': 'external-tool-required', 'external-tool-required': 'external-tool-required'
+});
+
+function proofObligationStatusKey(status) {
+  return String(status ?? 'unknown').trim().toLowerCase().replace(/[\s_]+/g, '-') || 'unknown';
+}
+
+function proofObligationReadinessStatus(status) {
+  const key = proofObligationStatusKey(status);
+  const known = ['discharged', 'failed', 'pending', 'open', 'unknown', 'stale', 'assumed', 'external-tool-required'];
+  return ProofObligationStatusAliases[key] ?? (known.includes(key) ? key : 'unknown');
+}
+
+function summarizeProofSpecLayer(proof = {}) {
+  const contracts = proof?.contracts ?? [];
+  const refinements = proof?.refinements ?? [];
+  const invariants = proof?.invariants ?? [];
+  const termination = proof?.termination ?? [];
+  const temporal = proof?.temporal ?? [];
+  const obligations = proof?.obligations ?? [];
+  const artifacts = proof?.artifacts ?? [];
+  const assumptions = proof?.assumptions ?? [];
+  const evidence = proof?.evidence ?? [];
+  const allContracts = [...contracts, ...refinements, ...invariants, ...termination, ...temporal];
+  const byStatus = {};
+  const byReadinessStatus = {};
+  for (const obligation of obligations) {
+    const status = proofObligationStatusKey(obligation?.status);
+    const readinessStatus = proofObligationReadinessStatus(status);
+    byStatus[status] = (byStatus[status] ?? 0) + 1;
+    byReadinessStatus[readinessStatus] = (byReadinessStatus[readinessStatus] ?? 0) + 1;
+  }
+  const byContractKind = {};
+  for (const contract of allContracts) {
+    const kind = contract?.kind ?? 'unknown';
+    byContractKind[kind] = (byContractKind[kind] ?? 0) + 1;
+  }
+  const byArtifactKind = {};
+  for (const artifact of artifacts) {
+    const kind = artifact?.kind ?? 'unknown';
+    byArtifactKind[kind] = (byArtifactKind[kind] ?? 0) + 1;
+  }
+  const recordGroups = [allContracts, obligations, artifacts, assumptions];
+  const ids = uniqueStrings([
+    proof?.id,
+    ...recordGroups.flatMap((records) => records.map((record) => record?.id)),
+    ...evidence.map((record) => record?.id)
+  ].filter(Boolean));
+  const total = allContracts.length + obligations.length + artifacts.length + assumptions.length;
+  return {
+    total,
+    ids,
+    contracts: contracts.length,
+    refinements: refinements.length,
+    invariants: invariants.length,
+    termination: termination.length,
+    temporal: temporal.length,
+    obligations: obligations.length,
+    artifacts: artifacts.length,
+    assumptions: assumptions.length,
+    evidence: evidence.length,
+    discharged: byReadinessStatus.discharged ?? 0,
+    pending: byReadinessStatus.pending ?? 0,
+    failed: byReadinessStatus.failed ?? 0,
+    open: (byReadinessStatus.open ?? 0) + (byReadinessStatus.pending ?? 0),
+    unknown: byReadinessStatus.unknown ?? 0,
+    stale: byReadinessStatus.stale ?? 0,
+    assumed: byReadinessStatus.assumed ?? 0,
+    externalToolRequired: byReadinessStatus['external-tool-required'] ?? 0,
+    contractKinds: uniqueStrings(allContracts.map((record) => record?.kind).filter(Boolean)),
+    artifactKinds: uniqueStrings(artifacts.map((record) => record?.kind).filter(Boolean)),
+    byStatus,
+    byReadinessStatus,
+    byContractKind,
+    byArtifactKind,
+    empty: total === 0
+  };
+}
+
+function summarizeSemanticImportSidecarUniversalAstLayers(importEntries) {
+  const names = [];
+  const ids = [];
+  const byName = {};
+  for (const entry of importEntries) {
+    names.push(...(entry.universalAstLayerNames ?? []));
+    ids.push(...(entry.universalAstLayerIds ?? []));
+    for (const name of entry.universalAstLayerNames ?? []) {
+      byName[name] = (byName[name] ?? 0) + 1;
+    }
+  }
+  const uniqueNames = uniqueStrings(names);
+  return {
+    total: ids.length,
+    names: uniqueNames,
+    ids: uniqueStrings(ids),
+    byName,
+    empty: ids.length === 0
+  };
+}
+
+function summarizeUniversalAstLayers(universalAst) {
+  const layers = collectUniversalAstLayerRecords(universalAst?.layers);
+  const names = uniqueStrings(layers.map((layer) => layer.layer).filter(Boolean));
+  const ids = uniqueStrings(layers.map((layer) => layer.id).filter(Boolean));
+  const byName = {};
+  for (const layer of layers) {
+    if (!layer?.layer) continue;
+    byName[layer.layer] = (byName[layer.layer] ?? 0) + 1;
+  }
+  return {
+    total: layers.length,
+    names,
+    ids,
+    byName,
+    empty: layers.length === 0
+  };
+}
+
+function collectUniversalAstLayerRecords(layers) {
+  if (!layers) return [];
+  if (Array.isArray(layers)) return layers.filter(Boolean);
+  if (typeof layers !== 'object') return [];
+  return Object.values(layers).flatMap((value) => Array.isArray(value) ? value : [value]).filter(Boolean);
+}
+
+export {
+  summarizeParadigmSemanticsLayer,
+  summarizeProofSpecLayer,
+  summarizeSemanticImportSidecarParadigmSemantics,
+  summarizeSemanticImportSidecarProofSpec,
+  summarizeSemanticImportSidecarUniversalAstLayers,
+  summarizeUniversalAstLayers
+};

package/dist/semantic-import-regions.js

@@ -0,0 +1,181 @@
+import { idFragment, uniqueStrings } from './native-import-utils.js';
+
+const NativeImportRegionTaxonomyKinds = Object.freeze([
+  'symbol',
+  'declaration',
+  'import',
+  'body',
+  'call',
+  'type',
+  'effect',
+  'property',
+  'config',
+  'content',
+  'route',
+  'generatedOutput'
+]);
+
+function semanticOwnershipRegionForSymbol(imported, symbol, mapping, nativeNode, options = {}) {
+  const sourcePath = mapping?.sourceSpan?.path ?? symbol.definitionSpan?.path ?? nativeNode?.span?.path ?? imported?.sourcePath ?? imported?.nativeSource?.sourcePath ?? imported?.nativeAst?.sourcePath;
+  const language = symbol.language ?? imported?.language ?? imported?.nativeAst?.language ?? imported?.nativeSource?.language;
+  const sourceSpan = mapping?.sourceSpan ?? symbol.definitionSpan ?? nativeNode?.span;
+  const regionKind = semanticRegionKindForSymbol(symbol, mapping, nativeNode);
+  const key = [
+    options.regionPrefix ?? 'source',
+    sourcePath ?? `${language}:memory`,
+    regionKind,
+    symbol.name ?? symbol.id
+  ].map((part) => String(part).replace(/\s+/g, ' ').trim()).join('#');
+  return {
+    id: `region_${idFragment(key)}`,
+    key,
+    regionKind,
+    granularity: 'symbol',
+    language,
+    sourcePath,
+    sourceHash: imported?.nativeSource?.sourceHash ?? imported?.nativeAst?.sourceHash,
+    symbolId: symbol.id,
+    symbolName: symbol.name,
+    symbolKind: symbol.kind,
+    nativeAstNodeId: symbol.nativeAstNodeId ?? nativeNode?.id,
+    sourceSpan,
+    precision: mapping?.precision ?? (sourceSpan ? 'declaration' : 'unknown'),
+    mergePolicy: semanticRegionMergePolicy(regionKind),
+    metadata: {
+      semanticRegionTaxonomy: true
+    }
+  };
+}
+
+function semanticOwnershipRegionForDeclaration(input, declaration, documentId) {
+  const name = declaration.name ?? declaration.importPath ?? declaration.nodeId ?? declaration.nativeNode?.id;
+  const kind = declaration.symbolKind ?? declaration.kind ?? declaration.nativeNode?.kind ?? 'symbol';
+  const sourcePath = declaration.span?.path ?? declaration.nativeNode?.span?.path ?? input.sourcePath ?? `${input.language}:memory`;
+  const regionKind = semanticRegionKindForDeclaration(declaration);
+  const key = ['source', sourcePath, regionKind, name].map((part) => String(part).replace(/\s+/g, ' ').trim()).join('#');
+  return {
+    id: `region_${idFragment(key)}`,
+    key,
+    regionKind,
+    granularity: 'symbol',
+    language: input.language,
+    documentId,
+    sourcePath,
+    sourceHash: input.sourceHash,
+    symbolId: declaration.symbolId,
+    symbolName: name,
+    symbolKind: kind,
+    nativeAstNodeId: declaration.nodeId ?? declaration.nativeNode?.id,
+    sourceSpan: declaration.span ?? declaration.nativeNode?.span,
+    precision: declaration.span || declaration.nativeNode?.span ? 'declaration' : 'unknown',
+    mergePolicy: semanticRegionMergePolicy(regionKind),
+    metadata: {
+      semanticRegionTaxonomy: true
+    }
+  };
+}
+
+function semanticPatchHintForRegion(region, readiness, options = {}) {
+  return {
+    id: `hint_${idFragment(region.id)}`,
+    kind: 'source-region-patch',
+    ownershipRegionId: region.id,
+    ownershipKey: region.key,
+    sourcePath: region.sourcePath,
+    sourceHash: region.sourceHash,
+    sourceSpan: region.sourceSpan,
+    readiness,
+    precision: region.precision,
+    supportedOperations: semanticRegionSupportedOperations(region),
+    projection: {
+      sourceLanguage: region.language,
+      targetPath: options.targetPath ?? region.sourcePath,
+      requiresSourceMap: true
+    }
+  };
+}
+
+function semanticRegionKindForDeclaration(declaration) {
+  if (declaration.role === 'import' || declaration.importPath) return 'import';
+  if (declaration.regionKind) return normalizeNativeImportRegionKind(declaration.regionKind);
+  if (declaration.metadata?.ownershipRegionKind) return normalizeNativeImportRegionKind(declaration.metadata.ownershipRegionKind);
+  const kind = declaration.symbolKind ?? declaration.kind ?? declaration.nativeNode?.kind;
+  if (semanticKindIsType(kind)) return 'type';
+  if (semanticKindCanOwnBody(kind, declaration.span ?? declaration.nativeNode?.span)) return 'body';
+  return 'declaration';
+}
+
+function semanticRegionKindForSymbol(symbol, mapping, nativeNode) {
+  if (mapping?.generatedSpan || mapping?.generatedName || mapping?.target?.emitPath) return 'generatedOutput';
+  if (symbol?.metadata?.ownershipRegionKind) return normalizeNativeImportRegionKind(symbol.metadata.ownershipRegionKind);
+  if (String(symbol?.id ?? '').includes(':import:') || symbol?.metadata?.role === 'import') return 'import';
+  if (semanticKindIsType(symbol?.kind ?? nativeNode?.kind)) return 'type';
+  if (semanticKindCanOwnBody(symbol?.kind ?? nativeNode?.kind, nativeNode?.span ?? symbol?.definitionSpan)) return 'body';
+  return 'declaration';
+}
+
+function semanticKindIsType(kind) {
+  return ['type', 'class', 'interface', 'trait', 'protocol', 'struct', 'enum', 'record'].includes(String(kind ?? '').toLowerCase());
+}
+
+function semanticKindCanOwnBody(kind, span) {
+  const text = String(kind ?? '').toLowerCase();
+  if (/function|method|class|implementation|module|namespace|package|action|effect|capability/.test(text)) return true;
+  return typeof span?.startLine === 'number' && typeof span?.endLine === 'number' && span.endLine > span.startLine;
+}
+
+function semanticRegionMergePolicy(regionKind) {
+  if (regionKind === 'import') return 'module-edge-review-required';
+  if (regionKind === 'body') return 'implementation-single-writer-review-required';
+  if (regionKind === 'call') return 'callsite-overlap-review-required';
+  if (regionKind === 'type') return 'type-surface-review-required';
+  if (regionKind === 'effect') return 'effect-boundary-review-required';
+  if (regionKind === 'generatedOutput') return 'generated-output-source-map-review-required';
+  return 'single-writer-review-required';
+}
+
+function semanticRegionSupportedOperations(region) {
+  if (region.regionKind === 'import') return ['replace-import', 'insert-import-before', 'insert-import-after', 'replace-region'];
+  if (region.regionKind === 'body') return ['replace-body', 'insert-before-body', 'insert-after-body'];
+  if (region.regionKind === 'call') return ['replace-callsite', 'review-callsite'];
+  if (region.regionKind === 'type') return ['replace-type-declaration', 'merge-type-members', 'replace-region'];
+  if (region.regionKind === 'effect') return ['route-effect', 'replace-effect-boundary', 'review-effect-policy'];
+  if (region.regionKind === 'generatedOutput') return ['replace-generated-output', 'attach-generated-source-map', 'review-generator-input'];
+  return ['replace-region', 'insert-before-region', 'insert-after-region'];
+}
+
+function normalizeNativeImportRegionKind(value) {
+  const text = String(value ?? 'symbol').trim();
+  if (text === 'generated' || text === 'generated-output' || text === 'generated_output') return 'generatedOutput';
+  if (NativeImportRegionTaxonomyKinds.includes(text)) return text;
+  return text || 'symbol';
+}
+
+function summarizeSemanticImportRegionTaxonomy(regions) {
+  const byKind = {};
+  const keysByKind = {};
+  const keys = [];
+  for (const region of regions ?? []) {
+    const kind = normalizeNativeImportRegionKind(region.regionKind ?? region.granularity);
+    byKind[kind] = (byKind[kind] ?? 0) + 1;
+    keysByKind[kind] = [...(keysByKind[kind] ?? []), region.key].filter(Boolean);
+    if (region.key) keys.push(region.key);
+  }
+  return {
+    kinds: [...NativeImportRegionTaxonomyKinds],
+    presentKinds: uniqueStrings(Object.keys(byKind)),
+    byKind,
+    keys,
+    keysByKind
+  };
+}
+
+export {
+  NativeImportRegionTaxonomyKinds,
+  semanticOwnershipRegionForDeclaration,
+  semanticOwnershipRegionForSymbol,
+  semanticPatchHintForRegion,
+  semanticRegionKindForSymbol,
+  semanticRegionMergePolicy,
+  summarizeSemanticImportRegionTaxonomy
+};