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

package/dist/universal-capability-matrix.js

@@ -0,0 +1,280 @@
+import {
+  maxSemanticMergeReadiness,
+  normalizeNativeLanguageId,
+  uniqueStrings
+} from './native-import-utils.js';
+import {
+  NativeImportLanguageProfiles
+} from './coverage-matrix-profiles.js';
+import { createNativeImportCoverageMatrix } from './native-import-coverage-matrix.js';
+import { createNativeParserAstFormatMatrix } from './native-parser-ast-format-matrix.js';
+import { createNativeParserFeatureMatrix } from './native-parser-feature-matrix.js';
+import { createProjectionReadinessMatrix } from './projection-readiness-matrix.js';
+import { createProjectionTargetLossMatrix } from './projection-target-loss-matrix.js';
+
+export function createUniversalCapabilityMatrix(input = {}, context = {}) {
+  const generatedAt = input.generatedAt ?? Date.now();
+  const imports = input.imports ?? [];
+  const adapters = input.adapters ?? [];
+  const targetAdapters = input.targetAdapters ?? [];
+  const languages = input.languages ?? NativeImportLanguageProfiles;
+  const targets = input.targets ?? context.compileTargets ?? [];
+  const importCoverage = createNativeImportCoverageMatrix({ languages, imports, adapters, generatedAt }, context);
+  const parserFormats = createNativeParserAstFormatMatrix({
+    formats: input.formats,
+    imports,
+    adapters,
+    generatedAt
+  }, context);
+  const parserFeatures = createNativeParserFeatureMatrix({
+    languages,
+    imports,
+    adapters,
+    requiredFeatures: input.requiredFeatures,
+    minimumReadiness: input.minimumReadiness,
+    includeEmptyParsers: input.includeEmptyParsers,
+    generatedAt
+  }, context);
+  const projectionTargets = createProjectionTargetLossMatrix({
+    languages,
+    imports,
+    adapters,
+    targetAdapters,
+    targets,
+    generatedAt
+  }, context);
+  const projectionReadiness = createProjectionReadinessMatrix({
+    projectionTargetMatrix: projectionTargets,
+    featureCategories: input.projectionFeatureCategories ?? input.featureCategories,
+    generatedAt
+  }, context);
+  const rows = importCoverage.languages.map((entry) => universalCapabilityLanguageRow(entry, {
+    parserFeatures,
+    projectionTargets
+  }));
+  return {
+    kind: 'frontier.lang.universalCapabilityMatrix',
+    version: 1,
+    generatedAt,
+    languages: rows,
+    summary: universalCapabilityMatrixSummary(rows),
+    matrices: {
+      importCoverage,
+      parserFormats,
+      parserFeatures,
+      projectionTargets,
+      projectionReadiness
+    },
+    metadata: {
+      requiredFeatures: parserFeatures.metadata.requiredFeatures,
+      minimumReadiness: parserFeatures.metadata.minimumReadiness,
+      compileTargets: projectionTargets.metadata.compileTargets,
+      note: 'Universal capability coverage composes import, parser, source-preservation, and projection evidence. It identifies gaps; it is not a proof that every language feature is losslessly portable.'
+    }
+  };
+}
+
+function universalCapabilityLanguageRow(importCoverage, context) {
+  const languageIds = universalLanguageIds(importCoverage);
+  const parserRows = (context.parserFeatures.parsers ?? []).filter((row) => universalLanguageIds(row).some((id) => languageIds.includes(id)));
+  const parserLanguage = (context.parserFeatures.languages ?? []).find((row) => universalLanguageIds(row).some((id) => languageIds.includes(id)));
+  const projection = (context.projectionTargets.languages ?? []).find((row) => universalLanguageIds(row).some((id) => languageIds.includes(id)));
+  const parserReadiness = parserRows.length
+    ? parserRows.reduce((current, row) => maxSemanticMergeReadiness(current, row.merge?.readiness ?? row.imports?.readiness ?? 'blocked'), 'ready')
+    : 'blocked';
+  const sourceProjectionReadiness = [projection?.sourceProjection?.exactSource, projection?.sourceProjection?.stubs]
+    .filter(Boolean)
+    .reduce((current, entry) => maxSemanticMergeReadiness(current, entry.readiness ?? 'blocked'), 'ready');
+  const targetReadiness = (projection?.targets ?? []).length
+    ? projection.targets.reduce((current, entry) => maxSemanticMergeReadiness(current, entry.readiness ?? 'blocked'), 'ready')
+    : 'blocked';
+  const projectionReadiness = maxSemanticMergeReadiness(sourceProjectionReadiness, targetReadiness);
+  const readiness = maxSemanticMergeReadiness(importCoverage.imports.readiness, maxSemanticMergeReadiness(parserReadiness, projectionReadiness));
+  const parserBlockingFeatures = uniqueStrings(parserRows.flatMap((row) => row.merge?.blockingFeatures ?? []));
+  const parserReviewFeatures = uniqueStrings(parserRows.flatMap((row) => row.merge?.reviewFeatures ?? []));
+  const missingTargets = (projection?.targets ?? []).filter((entry) => entry.lossClass === 'missingAdapter').map((entry) => entry.target);
+  const unsupportedTargets = (projection?.targets ?? []).filter((entry) => entry.lossClass === 'unsupportedTargetFeatures').map((entry) => entry.target);
+  const blockers = universalCapabilityBlockers({
+    importCoverage,
+    parserRows,
+    parserReadiness,
+    parserBlockingFeatures,
+    projection,
+    missingTargets,
+    readiness
+  });
+  const review = universalCapabilityReviewReasons({
+    importCoverage,
+    parserRows,
+    parserReviewFeatures,
+    unsupportedTargets,
+    readiness
+  });
+  return {
+    language: importCoverage.language,
+    aliases: importCoverage.aliases,
+    extensions: importCoverage.extensions,
+    readiness,
+    imports: {
+      total: importCoverage.imports.total,
+      readiness: importCoverage.imports.readiness,
+      symbols: importCoverage.imports.symbols,
+      sourceMaps: importCoverage.imports.sourceMaps,
+      sourceMapMappings: importCoverage.imports.sourceMapMappings,
+      losses: importCoverage.imports.losses,
+      lossKinds: importCoverage.imports.lossKinds,
+      readinessReasons: importCoverage.imports.readinessReasons
+    },
+    parser: {
+      readiness: parserReadiness,
+      rows: parserRows.length,
+      parsers: parserRows.map((row) => row.parser),
+      mergeReadyParsers: parserRows.filter((row) => row.merge?.mergeReady).map((row) => row.parser),
+      blockingFeatures: parserBlockingFeatures,
+      reviewFeatures: parserReviewFeatures,
+      languageSummary: parserLanguage
+    },
+    projection: {
+      readiness: projectionReadiness,
+      sourceProjection: projection?.sourceProjection,
+      targets: projection?.targets ?? [],
+      summary: projection?.summary ?? {
+        imports: 0,
+        parserAdapters: 0,
+        targetEntries: 0,
+        byLossClass: {},
+        exactSourceImports: 0,
+        stubDeclarationImports: 0
+      },
+      missingTargets,
+      unsupportedTargets
+    },
+    evidence: {
+      parserAdapters: importCoverage.parserAdapters.length,
+      adapterCoverageSummaries: importCoverage.adapterCoverage.total,
+      adapterCoverageGaps: importCoverage.adapterCoverage.gaps,
+      knownLossKinds: importCoverage.knownLossKinds,
+      sourceMapMappings: importCoverage.imports.sourceMapMappings
+    },
+    blockers,
+    review
+  };
+}
+
+function universalCapabilityBlockers(input) {
+  const blockers = [];
+  if ((input.importCoverage.imports.total ?? 0) === 0) {
+    blockers.push('No native import evidence observed for this language.');
+  }
+  if (!input.parserRows.length) {
+    blockers.push('No parser feature row matched this language.');
+  }
+  if (input.parserReadiness === 'blocked') {
+    blockers.push('Parser feature readiness is blocked.');
+  }
+  for (const feature of input.parserBlockingFeatures) {
+    blockers.push(`Required parser feature is not merge-ready: ${feature}.`);
+  }
+  if (!input.projection) {
+    blockers.push('No projection coverage row matched this language.');
+  }
+  for (const target of input.missingTargets) {
+    blockers.push(`Missing native-to-target projection adapter for ${target}.`);
+  }
+  if (input.readiness === 'blocked' && blockers.length === 0) {
+    blockers.push('Combined universal capability readiness is blocked.');
+  }
+  return uniqueStrings(blockers);
+}
+
+function universalCapabilityReviewReasons(input) {
+  const review = [];
+  if ((input.importCoverage.imports.losses ?? 0) > 0) {
+    review.push(`Native import evidence carries ${input.importCoverage.imports.losses} loss record(s).`);
+  }
+  for (const reason of input.importCoverage.imports.readinessReasons ?? []) {
+    review.push(reason);
+  }
+  for (const feature of input.parserReviewFeatures) {
+    review.push(`Parser feature needs review: ${feature}.`);
+  }
+  for (const target of input.unsupportedTargets) {
+    review.push(`Target projection has unsupported feature losses for ${target}.`);
+  }
+  if (input.readiness === 'needs-review') {
+    review.push('Combined universal capability readiness requires review.');
+  } else if (input.readiness === 'ready-with-losses') {
+    review.push('Combined universal capability readiness is ready with disclosed losses.');
+  }
+  return uniqueStrings(review);
+}
+
+function universalCapabilityMatrixSummary(rows) {
+  const byReadiness = {};
+  const byImportReadiness = {};
+  const byParserReadiness = {};
+  const byProjectionReadiness = {};
+  let imports = 0;
+  let symbols = 0;
+  let sourceMapMappings = 0;
+  let losses = 0;
+  let parserRows = 0;
+  let parserMergeReady = 0;
+  let targetEntries = 0;
+  let missingAdapters = 0;
+  let unsupportedTargetFeatures = 0;
+  let exactSourceProjection = 0;
+  let nativeSourceStubs = 0;
+  let blockers = 0;
+  let reviewReasons = 0;
+  for (const row of rows) {
+    byReadiness[row.readiness] = (byReadiness[row.readiness] ?? 0) + 1;
+    byImportReadiness[row.imports.readiness] = (byImportReadiness[row.imports.readiness] ?? 0) + 1;
+    byParserReadiness[row.parser.readiness] = (byParserReadiness[row.parser.readiness] ?? 0) + 1;
+    byProjectionReadiness[row.projection.readiness] = (byProjectionReadiness[row.projection.readiness] ?? 0) + 1;
+    imports += row.imports.total;
+    symbols += row.imports.symbols;
+    sourceMapMappings += row.imports.sourceMapMappings;
+    losses += row.imports.losses;
+    parserRows += row.parser.rows;
+    parserMergeReady += row.parser.mergeReadyParsers.length;
+    targetEntries += row.projection.targets.length;
+    missingAdapters += row.projection.missingTargets.length;
+    unsupportedTargetFeatures += row.projection.unsupportedTargets.length;
+    exactSourceProjection += row.projection.summary.byLossClass?.exactSourceProjection ?? 0;
+    nativeSourceStubs += row.projection.summary.byLossClass?.nativeSourceStubs ?? 0;
+    blockers += row.blockers.length;
+    reviewReasons += row.review.length;
+  }
+  return {
+    languages: rows.length,
+    imports,
+    symbols,
+    sourceMapMappings,
+    losses,
+    parserRows,
+    parserMergeReady,
+    targetEntries,
+    missingAdapters,
+    unsupportedTargetFeatures,
+    exactSourceProjection,
+    nativeSourceStubs,
+    blockers,
+    reviewReasons,
+    readyLanguages: rows.filter((row) => row.readiness === 'ready').length,
+    readyWithLossesLanguages: rows.filter((row) => row.readiness === 'ready-with-losses').length,
+    reviewLanguages: rows.filter((row) => row.readiness === 'needs-review').length,
+    blockedLanguages: rows.filter((row) => row.readiness === 'blocked').length,
+    byReadiness,
+    byImportReadiness,
+    byParserReadiness,
+    byProjectionReadiness
+  };
+}
+
+function universalLanguageIds(entry) {
+  return uniqueStrings([
+    entry?.language,
+    ...(entry?.aliases ?? [])
+  ].map(normalizeNativeLanguageId).filter(Boolean));
+}

package/dist/universal-dialect-layer.js

@@ -0,0 +1,74 @@
+import { uniqueStrings } from './native-import-utils.js';
+
+function createUniversalDialectLayer(universalAst, registry) {
+  const records = [...registry.dialects, ...registry.externs];
+  const references = uniqueReferences([
+    { kind: 'dialectRegistry', id: registry.id, layer: 'dialects' },
+    ...registry.dialects.map((record) => ({ kind: 'dialectRecord', id: record.id, layer: 'dialects' })),
+    ...registry.externs.map((record) => ({ kind: 'externRecord', id: record.id, layer: 'dialects' })),
+    ...records.flatMap(recordReferences)
+  ]);
+  return {
+    kind: 'frontier.lang.universalAstLayer',
+    version: 1,
+    id: `layer:${registry.id}:dialects`,
+    layer: 'dialects',
+    nativeSourceIds: uniqueStrings(records.map((record) => record.nativeSourceId).filter(Boolean)),
+    nativeAstIds: uniqueStrings(records.map((record) => record.nativeAstId).filter(Boolean)),
+    nativeAstNodeIds: uniqueStrings(records.map((record) => record.nativeAstNodeId).filter(Boolean)),
+    semanticNodeIds: uniqueStrings(records.map((record) => record.semanticNodeId).filter(Boolean)),
+    semanticIndexId: universalAst.semanticIndex?.id,
+    semanticSymbolIds: uniqueStrings(records.map((record) => record.semanticSymbolId).filter(Boolean)),
+    semanticOccurrenceIds: uniqueStrings(records.map((record) => record.semanticOccurrenceId).filter(Boolean)),
+    sourceMapIds: registry.summary.sourceMapIds,
+    sourceMapMappingIds: uniqueStrings(records.flatMap((record) => [
+      record.sourceMapMappingId,
+      ...(record.projection?.sourceMapMappingIds ?? [])
+    ]).filter(Boolean)),
+    lossIds: registry.summary.lossIds,
+    evidenceIds: registry.summary.evidenceIds,
+    references,
+    records: [registry],
+    metadata: {
+      registryId: registry.id,
+      dialectRecords: registry.summary.dialects,
+      externRecords: registry.summary.externs,
+      constructKinds: registry.summary.constructKinds,
+      externKinds: registry.summary.externKinds,
+      projectionReadiness: registry.summary.projectionReadiness,
+      note: 'Dialect records preserve language-specific constructs with explicit loss and projection evidence instead of lowering them into generic stubs.'
+    }
+  };
+}
+
+function recordReferences(record) {
+  return [
+    record.nativeSourceId ? { kind: 'nativeSource', id: record.nativeSourceId } : undefined,
+    record.nativeAstId ? { kind: 'nativeAst', id: record.nativeAstId } : undefined,
+    record.nativeAstNodeId ? { kind: 'nativeAstNode', id: record.nativeAstNodeId } : undefined,
+    record.semanticNodeId ? { kind: 'semanticNode', id: record.semanticNodeId } : undefined,
+    record.semanticSymbolId ? { kind: 'semanticSymbol', id: record.semanticSymbolId } : undefined,
+    record.semanticOccurrenceId ? { kind: 'semanticOccurrence', id: record.semanticOccurrenceId } : undefined,
+    record.sourceMapId ? { kind: 'sourceMap', id: record.sourceMapId } : undefined,
+    record.sourceMapMappingId ? { kind: 'sourceMapMapping', id: record.sourceMapMappingId } : undefined,
+    ...(record.lossIds ?? []).map((id) => ({ kind: 'loss', id })),
+    ...(record.evidenceIds ?? []).map((id) => ({ kind: 'evidence', id })),
+    ...(record.projection?.sourceMapIds ?? []).map((id) => ({ kind: 'sourceMap', id })),
+    ...(record.projection?.sourceMapMappingIds ?? []).map((id) => ({ kind: 'sourceMapMapping', id }))
+  ].filter(Boolean);
+}
+
+function uniqueReferences(references) {
+  const seen = new Set();
+  const result = [];
+  for (const reference of references) {
+    if (!reference?.id) continue;
+    const key = `${reference.kind}:${reference.id}:${reference.layer ?? ''}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(reference);
+  }
+  return result;
+}
+
+export { createUniversalDialectLayer };

package/dist/universal-dialect-registry.js

@@ -0,0 +1,204 @@
+import { idFragment, maxSemanticMergeReadiness, uniqueStrings } from './native-import-utils.js';
+import { createUniversalDialectLayer } from './universal-dialect-layer.js';
+import {
+  countByPresent,
+  dialectRecordId,
+  externRecordId,
+  normalizeDialectProjection,
+  normalizeOptionalString,
+  objectValue,
+  projectionDispositionReadiness,
+  uniqueRecordsById,
+  withoutUndefined
+} from './universal-dialect-utils.js';
+
+export const UniversalDialectConstructKinds = Object.freeze([
+  'macro',
+  'reflection',
+  'generator',
+  'runtime',
+  'extern',
+  'attribute',
+  'decorator',
+  'preprocessor',
+  'conditionalCompilation',
+  'syntaxExtension',
+  'toolchain'
+]);
+
+export const UniversalDialectProjectionDispositions = Object.freeze([
+  'preserved',
+  'lossless',
+  'lossy',
+  'opaque',
+  'declaration-only',
+  'stub-only',
+  'unsupported',
+  'runtime-required',
+  'review-required'
+]);
+
+export function createUniversalDialectRecord(input = {}, context = {}) {
+  const language = normalizeOptionalString(input.language ?? context.language);
+  const dialect = normalizeOptionalString(input.dialect ?? context.dialect ?? language ?? 'unknown');
+  const constructKind = normalizeOptionalString(input.constructKind ?? context.constructKind ?? 'extern');
+  const name = normalizeOptionalString(input.name ?? input.symbol ?? input.nativeKind ?? constructKind);
+  const lossIds = uniqueStrings([...(input.lossIds ?? []), input.lossId].filter(Boolean));
+  const evidenceIds = uniqueStrings([...(input.evidenceIds ?? []), input.evidenceId].filter(Boolean));
+  return withoutUndefined({
+    kind: 'frontier.lang.universalDialectRecord',
+    version: 1,
+    id: normalizeOptionalString(input.id) ?? dialectRecordId({ language, dialect, constructKind, name, index: context.index }),
+    language,
+    dialect,
+    constructKind,
+    name,
+    nativeKind: normalizeOptionalString(input.nativeKind),
+    sourcePath: normalizeOptionalString(input.sourcePath ?? context.sourcePath),
+    sourceSpan: input.sourceSpan,
+    nativeSourceId: normalizeOptionalString(input.nativeSourceId),
+    nativeAstId: normalizeOptionalString(input.nativeAstId),
+    nativeAstNodeId: normalizeOptionalString(input.nativeAstNodeId ?? input.nodeId),
+    semanticNodeId: normalizeOptionalString(input.semanticNodeId),
+    semanticSymbolId: normalizeOptionalString(input.semanticSymbolId),
+    semanticOccurrenceId: normalizeOptionalString(input.semanticOccurrenceId),
+    sourceMapId: normalizeOptionalString(input.sourceMapId),
+    sourceMapMappingId: normalizeOptionalString(input.sourceMapMappingId),
+    externIds: uniqueStrings([...(input.externIds ?? []), input.externId].filter(Boolean)),
+    lossIds,
+    evidenceIds,
+    projection: normalizeDialectProjection(input.projection ?? input.projectionEvidence, { lossIds, evidenceIds }),
+    payload: input.payload,
+    metadata: input.metadata ? { ...input.metadata } : undefined
+  });
+}
+
+export function createUniversalExternRecord(input = {}, context = {}) {
+  const language = normalizeOptionalString(input.language ?? context.language);
+  const dialect = normalizeOptionalString(input.dialect ?? context.dialect ?? language ?? 'extern');
+  const externKind = normalizeOptionalString(input.externKind ?? input.constructKind ?? context.externKind ?? 'foreignSymbol');
+  const name = normalizeOptionalString(input.name ?? input.symbol ?? input.binding?.symbol ?? externKind);
+  const lossIds = uniqueStrings([...(input.lossIds ?? []), input.lossId].filter(Boolean));
+  const evidenceIds = uniqueStrings([...(input.evidenceIds ?? []), input.evidenceId].filter(Boolean));
+  return withoutUndefined({
+    kind: 'frontier.lang.universalExternRecord',
+    version: 1,
+    id: normalizeOptionalString(input.id) ?? externRecordId({ language, dialect, externKind, name, index: context.index }),
+    language,
+    dialect,
+    externKind,
+    name,
+    binding: input.binding ? { ...input.binding } : undefined,
+    sourcePath: normalizeOptionalString(input.sourcePath ?? context.sourcePath),
+    sourceSpan: input.sourceSpan,
+    nativeSourceId: normalizeOptionalString(input.nativeSourceId),
+    nativeAstId: normalizeOptionalString(input.nativeAstId),
+    nativeAstNodeId: normalizeOptionalString(input.nativeAstNodeId ?? input.nodeId),
+    semanticNodeId: normalizeOptionalString(input.semanticNodeId),
+    semanticSymbolId: normalizeOptionalString(input.semanticSymbolId),
+    semanticOccurrenceId: normalizeOptionalString(input.semanticOccurrenceId),
+    sourceMapId: normalizeOptionalString(input.sourceMapId),
+    sourceMapMappingId: normalizeOptionalString(input.sourceMapMappingId),
+    lossIds,
+    evidenceIds,
+    projection: normalizeDialectProjection(input.projection ?? input.projectionEvidence, { lossIds, evidenceIds }),
+    payload: input.payload,
+    metadata: input.metadata ? { ...input.metadata } : undefined
+  });
+}
+
+export function createUniversalDialectRegistry(input = {}, context = {}) {
+  const source = input?.kind === 'frontier.lang.universalDialectRegistry' ? input : input ?? {};
+  const dialects = uniqueRecordsById((source.dialects ?? source.records ?? []).map((record, index) => createUniversalDialectRecord(record, {
+    language: source.language ?? context.language,
+    dialect: source.dialect ?? context.dialect,
+    sourcePath: source.sourcePath ?? context.sourcePath,
+    index
+  })));
+  const externs = uniqueRecordsById((source.externs ?? []).map((record, index) => createUniversalExternRecord(record, {
+    language: source.language ?? context.language,
+    dialect: source.dialect ?? context.dialect,
+    sourcePath: source.sourcePath ?? context.sourcePath,
+    index
+  })));
+  const language = normalizeOptionalString(source.language ?? context.language);
+  const id = normalizeOptionalString(source.id)
+    ?? `dialect_registry_${idFragment(language ?? source.sourcePath ?? context.sourcePath ?? dialects[0]?.dialect ?? externs[0]?.dialect ?? 'mixed')}`;
+  const registry = {
+    kind: 'frontier.lang.universalDialectRegistry',
+    version: 1,
+    id,
+    language,
+    dialects,
+    externs,
+    metadata: source.metadata ? { ...source.metadata } : undefined
+  };
+  return withoutUndefined({ ...registry, summary: summarizeUniversalDialectRegistry(registry) });
+}
+
+export function summarizeUniversalDialectRegistry(input = {}) {
+  const dialects = input.dialects ?? [];
+  const externs = input.externs ?? [];
+  const records = [...dialects, ...externs];
+  return {
+    dialects: dialects.length,
+    externs: externs.length,
+    records: records.length,
+    languages: uniqueStrings(records.map((record) => record.language).filter(Boolean)),
+    dialectNames: uniqueStrings(records.map((record) => record.dialect).filter(Boolean)),
+    constructKinds: countByPresent(dialects.map((record) => record.constructKind)),
+    externKinds: countByPresent(externs.map((record) => record.externKind)),
+    lossIds: uniqueStrings(records.flatMap((record) => record.lossIds ?? [])),
+    evidenceIds: uniqueStrings(records.flatMap((record) => record.evidenceIds ?? [])),
+    sourceMapIds: uniqueStrings(records.flatMap((record) => [record.sourceMapId, ...(record.projection?.sourceMapIds ?? [])]).filter(Boolean)),
+    projectionDispositions: countByPresent(records.map((record) => record.projection?.disposition)),
+    projectionReadiness: records.reduce(
+      (readiness, record) => maxSemanticMergeReadiness(readiness, projectionDispositionReadiness(record.projection?.disposition)),
+      'ready'
+    ),
+    recordsWithLosses: records.filter((record) => (record.lossIds ?? []).length > 0).length,
+    recordsWithProjectionEvidence: records.filter((record) => (record.projection?.evidenceIds ?? []).length > 0).length
+  };
+}
+
+export function attachUniversalDialectRegistry(universalAst, input = {}) {
+  if (!universalAst || typeof universalAst !== 'object') {
+    throw new Error('attachUniversalDialectRegistry requires a universal AST envelope');
+  }
+  const existing = universalAst.metadata?.dialects;
+  const registry = createUniversalDialectRegistry({
+    ...(existing && typeof existing === 'object' ? existing : {}),
+    ...input,
+    dialects: [...((existing && typeof existing === 'object' ? existing.dialects : []) ?? []), ...(input.dialects ?? input.records ?? [])],
+    externs: [...((existing && typeof existing === 'object' ? existing.externs : []) ?? []), ...(input.externs ?? [])]
+  }, {
+    language: universalAst.metadata?.sourceLanguage,
+    sourcePath: universalAst.metadata?.sourcePath
+  });
+  const metadata = {
+    ...(universalAst.metadata ?? {}),
+    dialects: registry,
+    language: { ...objectValue(universalAst.metadata?.language), externs: registry.externs }
+  };
+  return { ...universalAst, metadata, layers: { ...(universalAst.layers ?? {}), dialects: createUniversalDialectLayer(universalAst, registry) } };
+}
+
+export function attachInputUniversalDialectRegistry(universalAst, input = {}, context = {}) {
+  if (!hasUniversalDialectRegistryInput(input)) return universalAst;
+  const registryInput = input.universalDialectRegistry ?? {};
+  return attachUniversalDialectRegistry(universalAst, {
+    ...registryInput,
+    language: context.language ?? input.language,
+    sourcePath: context.sourcePath ?? input.sourcePath,
+    dialects: [...(registryInput.dialects ?? registryInput.records ?? []), ...(input.dialects ?? [])],
+    externs: [...(registryInput.externs ?? []), ...(input.externs ?? [])]
+  });
+}
+
+export function hasUniversalDialectRegistryInput(input) {
+  return Boolean(
+    input?.universalDialectRegistry
+    || (input?.dialects && input.dialects.length)
+    || (input?.externs && input.externs.length)
+  );
+}

package/dist/universal-dialect-utils.js

@@ -0,0 +1,110 @@
+import { idFragment, normalizeStringList, uniqueStrings } from './native-import-utils.js';
+
+function normalizeDialectProjection(input = {}, context = {}) {
+  const projection = input && typeof input === 'object' ? input : {};
+  const lossIds = uniqueStrings([...(projection.lossIds ?? []), ...(context.lossIds ?? [])]);
+  const evidenceIds = uniqueStrings([...(projection.evidenceIds ?? []), ...(context.evidenceIds ?? [])]);
+  const disposition = normalizeProjectionDisposition(projection.disposition, lossIds);
+  return withoutUndefined({
+    disposition,
+    readiness: projection.readiness ?? projectionDispositionReadiness(disposition),
+    targets: normalizeStringList(projection.targets ?? projection.target),
+    lossIds,
+    evidenceIds,
+    sourceMapIds: uniqueStrings([...(projection.sourceMapIds ?? []), projection.sourceMapId].filter(Boolean)),
+    sourceMapMappingIds: uniqueStrings([...(projection.sourceMapMappingIds ?? []), projection.sourceMapMappingId].filter(Boolean)),
+    notes: normalizeStringList(projection.notes ?? projection.note),
+    metadata: projection.metadata ? { ...projection.metadata } : undefined
+  });
+}
+
+function projectionDispositionReadiness(disposition) {
+  switch (disposition) {
+    case 'preserved':
+    case 'lossless':
+      return 'ready';
+    case 'lossy':
+    case 'declaration-only':
+      return 'ready-with-losses';
+    case 'stub-only':
+    case 'unsupported':
+      return 'blocked';
+    default:
+      return 'needs-review';
+  }
+}
+
+function dialectRecordId(input) {
+  return [
+    'dialect',
+    idFragment(input.language ?? 'mixed'),
+    idFragment(input.dialect ?? 'unknown'),
+    idFragment(input.constructKind ?? 'construct'),
+    idFragment(input.name ?? input.index ?? 'record')
+  ].join('_');
+}
+
+function externRecordId(input) {
+  return [
+    'extern',
+    idFragment(input.language ?? 'mixed'),
+    idFragment(input.dialect ?? 'unknown'),
+    idFragment(input.externKind ?? 'extern'),
+    idFragment(input.name ?? input.index ?? 'record')
+  ].join('_');
+}
+
+function countByPresent(values) {
+  const counts = {};
+  for (const value of values ?? []) {
+    if (value === undefined || value === null || value === '') continue;
+    const key = String(value);
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function normalizeProjectionDisposition(value, lossIds) {
+  const normalized = normalizeOptionalString(value);
+  return normalized ?? (lossIds.length ? 'review-required' : 'preserved');
+}
+
+function normalizeOptionalString(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  return String(value);
+}
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function uniqueRecordsById(records) {
+  const seen = new Set();
+  const result = [];
+  for (const record of records ?? []) {
+    if (!record?.id || seen.has(record.id)) continue;
+    seen.add(record.id);
+    result.push(record);
+  }
+  return result;
+}
+
+function withoutUndefined(value) {
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry !== undefined) result[key] = entry;
+  }
+  return result;
+}
+
+export {
+  countByPresent,
+  dialectRecordId,
+  externRecordId,
+  normalizeDialectProjection,
+  normalizeOptionalString,
+  objectValue,
+  projectionDispositionReadiness,
+  uniqueRecordsById,
+  withoutUndefined
+};