@shapeshift-labs/frontier-lang-compiler 0.2.103 → 0.2.104

package/dist/semantic-import-effect-regions.js

@@ -0,0 +1,283 @@
+import { caseSensitiveIdFragment, idFragment, uniqueRecordsById, uniqueStrings } from './native-import-utils.js';
+
+const semanticFactRegionKinds = new Set(['controlFlow', 'effect', 'mutation']);
+
+export function semanticEffectRegionRecordsForImport(imported, semanticIndex, options = {}) {
+  const symbolsById = new Map((semanticIndex?.symbols ?? []).map((symbol) => [symbol.id, symbol]));
+  const facts = (semanticIndex?.facts ?? []).filter((fact) => semanticFactRegionKinds.has(fact?.predicate)
+    && semanticFactSubjectCanOwnRuntimeRegion(symbolsById.get(fact.subjectId)));
+  if (!facts.length) return { symbols: [], ownershipRegions: [] };
+  const sourceText = nativeImportSourceText(imported);
+  const groups = semanticFactRegionGroups(facts);
+  const ordinals = new Map();
+  const records = groups.map((group, index) => {
+    const fact = group.facts[0];
+    const spanInfo = semanticFactSpanInfo(sourceText, group, fact, imported);
+    const owner = symbolsById.get(fact.subjectId);
+    const sourcePath = fact.value?.sourcePath ?? imported?.sourcePath ?? imported?.nativeSource?.sourcePath;
+    const language = imported?.language ?? imported?.nativeSource?.language ?? imported?.nativeAst?.language;
+    const signature = semanticFactRegionSignature(group);
+    const ordinal = nextSemanticFactOrdinal(ordinals, group, fact, signature);
+    const symbolName = `${owner?.name ?? fact.subjectId}:${group.regionKind}:${signature}#${ordinal}`;
+    const key = semanticFactRegionKey(options.regionPrefix, sourcePath, group.regionKind, symbolName, index);
+    const region = {
+      id: `region_${caseSensitiveIdFragment(key)}`,
+      key,
+      regionKind: group.regionKind,
+      granularity: 'semantic-fact-line',
+      language,
+      sourcePath,
+      sourceHash: imported?.nativeSource?.sourceHash ?? imported?.nativeAst?.sourceHash ?? imported?.sourceHash,
+      symbolId: `symbol:${language ?? 'source'}:${group.regionKind}:${idFragment(key)}`,
+      symbolName,
+      symbolKind: group.regionKind,
+      nativeAstNodeId: owner?.nativeAstNodeId,
+      sourceSpan: spanInfo.span,
+      precision: spanInfo.precision,
+      mergePolicy: semanticFactRegionMergePolicy(group.regionKind),
+      metadata: {
+        semanticRegionTaxonomy: true,
+        factIds: group.facts.map((item) => item.id).filter(Boolean),
+        factKinds: group.factKinds,
+        factLine: group.line,
+        predicate: group.regionKind,
+        spanKind: spanInfo.kind,
+        occurrenceOrdinal: ordinal,
+        subjectId: fact.subjectId,
+        subjectName: owner?.name
+      }
+    };
+    return {
+      region,
+      symbol: {
+        id: region.symbolId,
+        name: symbolName,
+        kind: group.regionKind,
+        language,
+        nativeAstNodeId: region.nativeAstNodeId,
+        sourceSpan: region.sourceSpan,
+        ownershipRegionId: region.id,
+        ownershipKey: region.key,
+        ownershipRegionKind: group.regionKind,
+        readiness: 'needs-review'
+      }
+    };
+  });
+  return {
+    symbols: uniqueRecordsById(records.map((record) => record.symbol)),
+    ownershipRegions: uniqueRecordsById(records.map((record) => record.region))
+  };
+}
+
+function semanticFactRegionGroups(facts) {
+  const groups = new Map();
+  for (const fact of facts) {
+    const line = Number(fact?.value?.line);
+    if (!Number.isFinite(line)) continue;
+    const regionKind = String(fact.predicate);
+    const key = [regionKind, fact.subjectId, fact.value?.sourcePath, line].join('\0');
+    const group = groups.get(key) ?? { regionKind, line, sourcePath: fact.value?.sourcePath, facts: [] };
+    group.facts.push(fact);
+    group.factKinds = uniqueStrings(group.facts.map((item) => item.value?.kind).filter(Boolean));
+    groups.set(key, group);
+  }
+  return [...groups.values()].flatMap(splitSemanticFactGroup);
+}
+
+function splitSemanticFactGroup(group) {
+  if (group.regionKind === 'effect') return splitEffectFactGroup(group);
+  return group.factKinds.map((factKind) => ({
+    ...group,
+    facts: group.facts.filter((fact) => fact.value?.kind === factKind),
+    factKinds: [factKind]
+  }));
+}
+
+function splitEffectFactGroup(group) {
+  const concreteKinds = group.factKinds.filter((kind) => kind !== 'async');
+  if (!concreteKinds.length) return [group];
+  return concreteKinds.map((factKind, index) => ({
+    ...group,
+    facts: group.facts.filter((fact) => fact.value?.kind === factKind
+      || (index === 0 && fact.value?.kind === 'async')),
+    factKinds: uniqueStrings([factKind, index === 0 && group.factKinds.includes('async') ? 'async' : undefined])
+  }));
+}
+
+function semanticFactRegionSignature(group) {
+  return (group.factKinds?.length ? group.factKinds : [group.regionKind]).join('+');
+}
+
+function nextSemanticFactOrdinal(ordinals, group, fact, signature) {
+  const key = [group.regionKind, fact.subjectId, group.sourcePath, signature].join('\0');
+  const next = (ordinals.get(key) ?? 0) + 1;
+  ordinals.set(key, next);
+  return next;
+}
+
+function semanticFactSubjectCanOwnRuntimeRegion(symbol) {
+  if (!symbol) return true;
+  if (symbol.metadata?.ownershipRegionKind === 'body') return true;
+  return /function|method|action|effect|handler|constructor/
+    .test(String(symbol.kind ?? '').toLowerCase());
+}
+
+function semanticFactSpanInfo(sourceText, group, fact, imported) {
+  const lineNumber = Number(fact?.value?.line);
+  if (!Number.isFinite(lineNumber)) return { span: undefined, precision: 'unknown', kind: 'unknown' };
+  const line = String(sourceText ?? '').split(/\r\n|\n|\r/)[lineNumber - 1] ?? '';
+  const leading = line.match(/^\s*/)?.[0].length ?? 0;
+  const expression = semanticFactExpressionRange(line, group) ?? { start: leading, end: line.length, kind: 'line' };
+  return {
+    span: {
+      sourceId: imported?.nativeSource?.sourceHash ?? imported?.nativeAst?.sourceHash ?? imported?.sourceHash,
+      path: fact.value?.sourcePath ?? imported?.sourcePath ?? imported?.nativeSource?.sourcePath,
+      startLine: lineNumber,
+      endLine: lineNumber,
+      startColumn: expression.start + 1,
+      endColumn: expression.end + 1
+    },
+    precision: expression.kind === 'line' ? 'line' : 'expression',
+    kind: expression.kind
+  };
+}
+
+function semanticFactExpressionRange(line, group) {
+  if (group.regionKind === 'effect') return effectRange(line, group.factKinds);
+  if (group.regionKind === 'mutation') return mutationRange(line, group.factKinds);
+  if (group.regionKind === 'controlFlow') return controlFlowRange(line, group.factKinds);
+  return undefined;
+}
+
+function effectRange(line, kinds) {
+  if (kinds.includes('network')) return namedCallRange(line, ['fetch', 'XMLHttpRequest', 'WebSocket', 'EventSource'], 'network-call');
+  if (kinds.includes('scheduler')) return namedCallRange(line, ['setTimeout', 'setInterval', 'requestAnimationFrame', 'queueMicrotask'], 'scheduler-call');
+  if (kinds.includes('storage')) return tokenExpressionRange(line, ['localStorage', 'sessionStorage', 'indexedDB', 'caches', 'cookie'], 'storage-effect');
+  if (kinds.includes('host')) return tokenExpressionRange(line, ['console', 'process', 'Deno', 'Bun'], 'host-effect');
+  if (kinds.includes('browser')) return tokenExpressionRange(line, ['document', 'window', 'navigator', 'location', 'history'], 'browser-effect');
+  if (kinds.includes('async')) return keywordExpressionRange(line, 'await', 'async-effect');
+  return undefined;
+}
+
+function mutationRange(line, kinds) {
+  if (kinds.includes('mutating-call')) return mutatingCallRange(line);
+  if (kinds.includes('delete')) return keywordExpressionRange(line, 'delete', 'delete-mutation');
+  if (kinds.includes('assignment')) return assignmentRange(line);
+  if (kinds.includes('update')) return updateRange(line);
+  return undefined;
+}
+
+function controlFlowRange(line, kinds) {
+  if (kinds.includes('exit')) return keywordExpressionRange(line, /(return|yield)\b/, 'control-exit');
+  if (kinds.includes('branch')) return controlHeadRange(line, /(if|switch)\b/, 'control-branch')
+    ?? caseHeadRange(line) ?? keywordExpressionRange(line, /else\b/, 'control-branch');
+  if (kinds.includes('loop')) return controlHeadRange(line, /(for|while)\b/, 'control-loop')
+    ?? keywordExpressionRange(line, /do\b/, 'control-loop');
+  if (kinds.includes('exception')) return keywordExpressionRange(line, /(throw|catch|finally|try)\b/, 'control-exception');
+  if (kinds.includes('async')) return keywordExpressionRange(line, /(await|async)\b/, 'control-async');
+  return undefined;
+}
+
+function namedCallRange(line, names, kind) {
+  for (const name of names) {
+    const pattern = new RegExp(`(?:^|[^\\w$.])((?:window|globalThis|self)\\s*\\.\\s*)?${name}\\s*\\(`);
+    const match = pattern.exec(line);
+    if (!match) continue;
+    const start = match.index + match[0].search(new RegExp(`((?:window|globalThis|self)\\s*\\.\\s*)?${name}\\s*\\(`));
+    const open = line.indexOf('(', start);
+    const close = matchingParenIndex(line, open);
+    return { start, end: close === undefined ? statementEnd(line, open) : close + 1, kind };
+  }
+  return undefined;
+}
+
+function controlHeadRange(line, keyword, kind) {
+  const match = keyword.exec(line);
+  if (!match) return undefined;
+  const open = line.indexOf('(', match.index);
+  const close = matchingParenIndex(line, open);
+  return close === undefined ? undefined : { start: match.index, end: close + 1, kind };
+}
+
+function caseHeadRange(line) {
+  const match = /\b(case|default)\b/.exec(line);
+  if (!match) return undefined;
+  const colon = line.indexOf(':', match.index);
+  return { start: match.index, end: colon === -1 ? statementEnd(line, match.index) : colon + 1, kind: 'control-branch' };
+}
+
+function mutatingCallRange(line) {
+  const match = /[A-Za-z_$][\w$.[\]]*(?:\s*\.\s*[A-Za-z_$][\w$.[\]]*)*\s*\.\s*(?:push|pop|shift|unshift|splice|sort|reverse|set|add|delete|clear)\s*\(/.exec(line);
+  if (!match) return undefined;
+  const open = line.indexOf('(', match.index);
+  const close = matchingParenIndex(line, open);
+  return { start: match.index, end: close === undefined ? statementEnd(line, open) : close + 1, kind: 'mutating-call' };
+}
+
+function assignmentRange(line) {
+  const match = /\b[A-Za-z_$][\w$.[\]]*\s*=(?!=|>)/.exec(line);
+  return match ? { start: match.index, end: statementEnd(line, match.index), kind: 'assignment' } : undefined;
+}
+
+function updateRange(line) {
+  const match = /\b[A-Za-z_$][\w$.[\]]*(?:\+\+|--|\s*(?:\+=|-=|\*=|\/=|%=|\|\|=|&&=|\?\?=))/.exec(line);
+  return match ? { start: match.index, end: statementEnd(line, match.index), kind: 'update' } : undefined;
+}
+
+function tokenExpressionRange(line, tokens, kind) {
+  const pattern = new RegExp(`\\b(?:${tokens.join('|')})\\b`);
+  const match = pattern.exec(line);
+  return match ? { start: match.index, end: statementEnd(line, match.index), kind } : undefined;
+}
+
+function keywordExpressionRange(line, keyword, kind) {
+  const match = keyword instanceof RegExp ? keyword.exec(line) : new RegExp(`\\b${keyword}\\b`).exec(line);
+  return match ? { start: match.index, end: statementEnd(line, match.index), kind } : undefined;
+}
+
+function statementEnd(line, start) {
+  const semicolon = line.indexOf(';', Math.max(0, start));
+  return semicolon === -1 ? line.length : semicolon + 1;
+}
+
+function matchingParenIndex(line, open) {
+  if (open < 0) return undefined;
+  let depth = 0;
+  let quote;
+  let escaped = false;
+  for (let index = open; index < line.length; index += 1) {
+    const char = line[index];
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === quote) quote = undefined;
+      continue;
+    }
+    if (char === '\'' || char === '"' || char === '`') {
+      quote = char;
+      continue;
+    }
+    if (char === '(') depth += 1;
+    else if (char === ')' && --depth === 0) return index;
+  }
+  return undefined;
+}
+
+function semanticFactRegionKey(prefix = 'source', sourcePath, regionKind, symbolName, index) {
+  return [prefix, sourcePath ?? 'memory', regionKind, symbolName || `unknown#${index + 1}`]
+    .map((part) => String(part).replace(/\s+/g, ' ').trim())
+    .join('#');
+}
+
+function semanticFactRegionMergePolicy(regionKind) {
+  if (regionKind === 'controlFlow') return 'control-flow-review-required';
+  if (regionKind === 'mutation') return 'mutation-boundary-review-required';
+  return 'effect-boundary-review-required';
+}
+
+function nativeImportSourceText(imported) {
+  return imported?.metadata?.sourcePreservation?.sourceText
+    ?? imported?.nativeSource?.metadata?.sourcePreservation?.sourceText
+    ?? imported?.nativeAst?.metadata?.sourcePreservation?.sourceText
+    ?? imported?.universalAst?.metadata?.sourcePreservation?.sourceText;
+}

package/dist/semantic-import-regions.js

@@ -4,10 +4,13 @@ const NativeImportRegionTaxonomyKinds = Object.freeze([
   'symbol',
   'declaration',
   'import',
+  'export',
   'body',
   'call',
   'type',
+  'controlFlow',
   'effect',
+  'mutation',
   'property',
   'config',
   'content',
@@ -52,9 +55,10 @@ function semanticOwnershipRegionForDeclaration(input, declaration, documentId) {
   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('#');
+  const key = declaration.metadata?.ownershipRegionKey
+    ?? ['source', sourcePath, regionKind, name].map((part) => String(part).replace(/\s+/g, ' ').trim()).join('#');
   return {
-    id: `region_${caseSensitiveIdFragment(key)}`,
+    id: declaration.metadata?.ownershipRegionId ?? `region_${caseSensitiveIdFragment(key)}`,
     key,
     regionKind,
     granularity: 'symbol',
@@ -131,17 +135,22 @@ function semanticRegionMergePolicy(regionKind) {
   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 === 'controlFlow') return 'control-flow-review-required';
   if (regionKind === 'effect') return 'effect-boundary-review-required';
+  if (regionKind === 'mutation') return 'mutation-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 === 'export') return ['replace-export', 'insert-export-before', 'insert-export-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 === 'controlFlow') return ['replace-control-flow', 'review-control-flow'];
   if (region.regionKind === 'effect') return ['route-effect', 'replace-effect-boundary', 'review-effect-policy'];
+  if (region.regionKind === 'mutation') return ['replace-mutation', 'review-mutation'];
   if (region.regionKind === 'generatedOutput') return ['replace-generated-output', 'attach-generated-source-map', 'review-generator-input'];
   return ['replace-region', 'insert-before-region', 'insert-after-region'];
 }

package/dist/semantic-import-sidecar-entry.js

@@ -1,5 +1,7 @@
 import { uniqueRecordsById, uniqueStrings } from './native-import-utils.js';
+import { semanticCallsiteRecordsForImport } from './semantic-import-callsite-regions.js';
 import { summarizeSemanticImportDependencyRelations } from './semantic-import-dependencies.js';
+import { semanticEffectRegionRecordsForImport } from './semantic-import-effect-regions.js';
 import { semanticOwnershipRegionForSymbol, semanticPatchHintForRegion, summarizeSemanticImportRegionTaxonomy } from './semantic-import-regions.js';
 import { collectKernelSourcePreservationFromImport } from './semantic-import-source-preservation.js';
 import {
@@ -23,16 +25,22 @@ function semanticImportSidecarEntry(imported, index, options) {
   const dependencies = summarizeSemanticImportDependencyRelations(semanticIndex?.relations ?? []);
   const factSummary = summarizeSemanticFacts(semanticFacts);
   const readiness = semanticImportEntryReadiness(imported);
+  const callsites = semanticCallsiteRecordsForImport(imported, semanticIndex, options);
+  const effectRegions = semanticEffectRegionRecordsForImport(imported, semanticIndex, options);
   const mappingsBySymbolId = new Map();
+  const mappingsBySymbolAndNode = new Map();
   for (const mapping of sourceMapMappings) {
     if (mapping.semanticSymbolId && !mappingsBySymbolId.has(mapping.semanticSymbolId)) {
       mappingsBySymbolId.set(mapping.semanticSymbolId, mapping);
     }
+    if (mapping.semanticSymbolId && mapping.nativeAstNodeId) {
+      mappingsBySymbolAndNode.set(`${mapping.semanticSymbolId}\0${mapping.nativeAstNodeId}`, mapping);
+    }
   }
   const symbols = [];
   const regions = [];
   for (const symbol of semanticSymbols) {
-    const mapping = mappingsBySymbolId.get(symbol.id);
+    const mapping = mappingsBySymbolAndNode.get(`${symbol.id}\0${symbol.nativeAstNodeId}`) ?? mappingsBySymbolId.get(symbol.id);
     const nativeNode = symbol.nativeAstNodeId ? nativeAst?.nodes?.[symbol.nativeAstNodeId] : undefined;
     const generatedRegion = semanticOwnershipRegionForSymbol(imported, symbol, mapping, nativeNode, options);
     const region = mergeSemanticOwnershipRegion(
@@ -48,8 +56,10 @@ function semanticImportSidecarEntry(imported, index, options) {
       nativeAstNodeId: symbol.nativeAstNodeId,
       semanticOccurrenceId: mapping?.semanticOccurrenceId,
       sourceMapMappingId: mapping?.id,
-      sourceSpan: region.sourceSpan ?? mapping?.sourceSpan ?? symbol.definitionSpan ?? nativeNode?.span,
+      sourceSpan: mapping?.sourceSpan ?? symbol.definitionSpan ?? nativeNode?.span ?? region.sourceSpan,
       signatureHash: symbol.signatureHash,
+      signatureOnly: symbol.metadata?.signatureOnly === true || undefined,
+      hasBody: typeof symbol.metadata?.hasBody === 'boolean' ? symbol.metadata.hasBody : undefined,
       ownershipRegionId: region.id,
       ownershipKey: region.key,
       ownershipRegionKind: region.regionKind,
@@ -59,6 +69,10 @@ function semanticImportSidecarEntry(imported, index, options) {
   for (const [regionIndex, region] of importedOwnershipRegions.entries()) {
     regions.push(normalizeImportedOwnershipRegion(imported, region, regionIndex, options));
   }
+  regions.push(...callsites.ownershipRegions);
+  regions.push(...effectRegions.ownershipRegions);
+  symbols.push(...callsites.symbols.map((symbol) => ({ ...symbol, readiness })));
+  symbols.push(...effectRegions.symbols.map((symbol) => ({ ...symbol, readiness })));
   const ownershipRegions = uniqueRecordsById(regions);
   const regionTaxonomy = summarizeSemanticImportRegionTaxonomy(ownershipRegions);
   const patchHints = ownershipRegions.map((region) => semanticPatchHintForRegion(region, readiness, options));

package/dist/semantic-import-sidecar-types.d.ts

@@ -37,6 +37,8 @@ export interface SemanticImportSidecarSymbol {
   readonly sourceMapMappingId?: string;
   readonly sourceSpan?: SourceSpan;
   readonly signatureHash?: string;
+  readonly signatureOnly?: boolean;
+  readonly hasBody?: boolean;
   readonly ownershipRegionId: string;
   readonly ownershipKey: string;
   readonly ownershipRegionKind?: NativeImportRegionTaxonomyKind;

package/dist/semantic-sidecar-example.js

@@ -0,0 +1,68 @@
+import { createSemanticImportSidecar } from './internal/index-impl/createSemanticImportSidecar.js';
+
+const compactExampleSource = Object.freeze({
+  schema: 'frontier.lang.semanticImportSidecar.example.compact.v1',
+  baseSource: {
+    path: 'src/compact-sidecar.ts',
+    hash: 'sha256:base-compact-sidecar-v1',
+    identityHash: 'sha256:identity-compact-sidecar-example-v1',
+    text: 'export function compactSidecarExample(value: number) {\n  return value + 1;\n}\n'
+  },
+  headSource: {
+    path: 'src/compact-sidecar.ts',
+    hash: 'sha256:head-compact-sidecar-v2',
+    identityHash: 'sha256:identity-compact-sidecar-example-v1',
+    text: 'export function compactSidecarExample(value: number) {\n  return value + 2;\n}\n'
+  },
+  identityHashes: {
+    source: 'sha256:identity-compact-sidecar-example-v1',
+    symbol: 'sha256:symbol-compact-sidecar-example-v1',
+    signature: 'sha256:signature-compact-sidecar-example-v1'
+  }
+});
+
+const compactExampleImport = Object.freeze({
+  id: 'compact_sidecar_example_import',
+  language: 'typescript',
+  sourcePath: compactExampleSource.headSource.path,
+  sourceHash: compactExampleSource.headSource.hash,
+  semanticIndex: {
+    id: 'semantic_index_compact_sidecar_example',
+    symbols: [{
+      id: 'symbol:compactSidecarExample',
+      name: 'compactSidecarExample',
+      kind: 'function',
+      language: 'typescript',
+      definitionSpan: {
+        path: compactExampleSource.headSource.path,
+        startLine: 1,
+        startColumn: 1,
+        endLine: 3,
+        endColumn: 2
+      },
+      signatureHash: compactExampleSource.identityHashes.signature,
+      metadata: { ownershipRegionKind: 'body' }
+    }],
+    relations: [],
+    facts: []
+  },
+  evidence: [{
+    id: 'evidence_compact_sidecar_example',
+    kind: 'semantic-sidecar-example',
+    status: 'passed'
+  }]
+});
+
+export const compactSemanticSidecarExample = Object.freeze({
+  ...compactExampleSource,
+  sidecar: createSemanticImportSidecar(compactExampleImport, {
+    id: 'semantic_import_compact_sidecar_example',
+    generatedAt: 132,
+    targetPath: 'dist/compact-sidecar.js',
+    metadata: {
+      baseSource: compactExampleSource.baseSource,
+      headSource: compactExampleSource.headSource,
+      identityHashes: compactExampleSource.identityHashes
+    }
+  })
+});

package/dist/universal-capability-matrix.js

@@ -11,6 +11,7 @@ import { createNativeParserAstFormatMatrix } from './native-parser-ast-format-ma
 import { createNativeParserFeatureMatrix } from './native-parser-feature-matrix.js';
 import { createProjectionReadinessMatrix } from './projection-readiness-matrix.js';
 import { createProjectionTargetLossMatrix } from './projection-target-loss-matrix.js';
+import { createUniversalRepresentationCoverage } from './universal-representation-coverage.js';
 
 export function createUniversalCapabilityMatrix(input = {}, context = {}) {
   const generatedAt = input.generatedAt ?? Date.now();
@@ -110,6 +111,21 @@ function universalCapabilityLanguageRow(importCoverage, context) {
     unsupportedTargets,
     readiness
   });
+  const representation = createUniversalRepresentationCoverage({
+    sourceLanguage: importCoverage.language,
+    imports: importCoverage.imports,
+    parser: {
+      rows: parserRows.length,
+      mergeReadyParsers: parserRows.filter((row) => row.merge?.mergeReady).map((row) => row.parser),
+      reviewFeatures: parserReviewFeatures
+    },
+    projection: {
+      sourceProjection: projection?.sourceProjection,
+      targets: projection?.targets ?? [],
+      missingTargets,
+      unsupportedTargets
+    }
+  });
   return {
     language: importCoverage.language,
     aliases: importCoverage.aliases,
@@ -156,6 +172,7 @@ function universalCapabilityLanguageRow(importCoverage, context) {
       knownLossKinds: importCoverage.knownLossKinds,
       sourceMapMappings: importCoverage.imports.sourceMapMappings
     },
+    representation,
     blockers,
     review
   };
@@ -225,6 +242,8 @@ function universalCapabilityMatrixSummary(rows) {
   let unsupportedTargetFeatures = 0;
   let exactSourceProjection = 0;
   let nativeSourceStubs = 0;
+  let representationConstructs = 0;
+  let representationMissing = 0;
   let blockers = 0;
   let reviewReasons = 0;
   for (const row of rows) {
@@ -243,6 +262,8 @@ function universalCapabilityMatrixSummary(rows) {
     unsupportedTargetFeatures += row.projection.unsupportedTargets.length;
     exactSourceProjection += row.projection.summary.byLossClass?.exactSourceProjection ?? 0;
     nativeSourceStubs += row.projection.summary.byLossClass?.nativeSourceStubs ?? 0;
+    representationConstructs += row.representation?.summary?.representedConstructs ?? 0;
+    representationMissing += row.representation?.summary?.missing ?? 0;
     blockers += row.blockers.length;
     reviewReasons += row.review.length;
   }
@@ -259,6 +280,8 @@ function universalCapabilityMatrixSummary(rows) {
     unsupportedTargetFeatures,
     exactSourceProjection,
     nativeSourceStubs,
+    representationConstructs,
+    representationMissing,
     blockers,
     reviewReasons,
     readyLanguages: rows.filter((row) => row.readiness === 'ready').length,

package/dist/universal-conversion-artifact-query.js

@@ -1,4 +1,5 @@
 import { uniqueStrings } from './native-import-utils.js';
+import { artifactSemanticEditIndex } from './universal-conversion-artifact-semantic-edit.js';
 
 export function queryUniversalConversionArtifacts(records, query = {}) {
   return artifactRecords(records)
@@ -8,6 +9,7 @@ export function queryUniversalConversionArtifacts(records, query = {}) {
 }
 
 export function artifactIndex(routeArtifacts) {
+  const semanticEditIndexes = routeArtifacts.map(artifactSemanticEditIndex);
   return {
     routeIds: uniqueStrings(routeArtifacts.map((artifact) => artifact.routeId)),
     historyIds: uniqueStrings(routeArtifacts.map((artifact) => artifact.history.id)),
@@ -27,7 +29,28 @@ export function artifactIndex(routeArtifacts) {
     evidenceIds: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.history.evidenceIds)),
     proofIds: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.history.proofIds)),
     semanticOperationIds: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.semanticOperations?.operations ?? []).map((operation) => operation.id)),
-    semanticOperationKinds: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.semanticOperations?.operations ?? []).map((operation) => operation.operationKind))
+    semanticOperationKinds: uniqueStrings(routeArtifacts.flatMap((artifact) => artifact.semanticOperations?.operations ?? []).map((operation) => operation.operationKind)),
+    semanticEditStatuses: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditStatuses)),
+    semanticEditScriptIds: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditScriptIds)),
+    semanticEditProjectionIds: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditProjectionIds)),
+    semanticEditReplayIds: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditReplayIds)),
+    semanticEditReplayStatuses: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditReplayStatuses)),
+    semanticEditReplayActions: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditReplayActions)),
+    semanticEditAdmissionStatuses: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditAdmissionStatuses)),
+    semanticEditAdmissionActions: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditAdmissionActions)),
+    semanticEditAdmissionReadinesses: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditAdmissionReadinesses)),
+    semanticEditReplayCurrentHashes: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditReplayCurrentHashes)),
+    semanticEditReplayOutputHashes: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditReplayOutputHashes)),
+    semanticEditKeys: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditKeys)),
+    semanticEditHashes: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticEditHashes)),
+    semanticIdentityHashes: uniqueStrings(semanticEditIndexes.flatMap((index) => index.semanticIdentityHashes)),
+    sourceIdentityHashes: uniqueStrings(semanticEditIndexes.flatMap((index) => index.sourceIdentityHashes)),
+    operationContentHashes: uniqueStrings(semanticEditIndexes.flatMap((index) => index.operationContentHashes)),
+    editContentHashes: uniqueStrings(semanticEditIndexes.flatMap((index) => index.editContentHashes)),
+    representationConstructKinds: uniqueStrings(routeArtifacts.flatMap(artifactConstructKinds)),
+    runtimeCapabilities: uniqueStrings(routeArtifacts.flatMap(artifactRuntimeCapabilities)),
+    sourceMapPrecisions: uniqueStrings(routeArtifacts.flatMap(artifactSourceMapPrecisions)),
+    transformIdentityHashes: uniqueStrings(routeArtifacts.flatMap(artifactTransformIdentityHashes))
   };
 }
 
@@ -39,6 +62,7 @@ function artifactRecords(records) {
 }
 
 function matchesArtifact(record, query) {
+  const semanticEditIndex = artifactSemanticEditIndex(record);
   return match(query.routeId, [record.routeId])
     && match(query.historyId, [record.history.id])
     && match(query.patchBundleId, [record.patchBundle.id])
@@ -59,7 +83,60 @@ function matchesArtifact(record, query) {
     && match(query.evidenceId, record.history.evidenceIds)
     && match(query.proofId, record.history.proofIds)
     && match(query.semanticOperationId, (record.semanticOperations?.operations ?? []).map((operation) => operation.id))
-    && match(query.semanticOperationKind, (record.semanticOperations?.operations ?? []).map((operation) => operation.operationKind));
+    && match(query.semanticOperationKind, (record.semanticOperations?.operations ?? []).map((operation) => operation.operationKind))
+    && match(query.semanticEditStatus ?? query.semanticEditStatuses, semanticEditIndex.semanticEditStatuses)
+    && match(query.semanticEditScriptId ?? query.semanticEditScriptIds, semanticEditIndex.semanticEditScriptIds)
+    && match(query.semanticEditProjectionId ?? query.semanticEditProjectionIds, semanticEditIndex.semanticEditProjectionIds)
+    && match(query.semanticEditReplayId ?? query.semanticEditReplayIds, semanticEditIndex.semanticEditReplayIds)
+    && match(query.semanticEditReplayStatus ?? query.semanticEditReplayStatuses, semanticEditIndex.semanticEditReplayStatuses)
+    && match(query.semanticEditReplayAction ?? query.semanticEditReplayActions, semanticEditIndex.semanticEditReplayActions)
+    && match(query.semanticEditAdmission ?? query.semanticEditAdmissionStatus ?? query.semanticEditAdmissionStatuses, semanticEditIndex.semanticEditAdmissionStatuses)
+    && match(query.semanticEditAdmissionAction ?? query.semanticEditAdmissionActions, semanticEditIndex.semanticEditAdmissionActions)
+    && match(query.semanticEditAdmissionReadiness ?? query.semanticEditAdmissionReadinesses, semanticEditIndex.semanticEditAdmissionReadinesses)
+    && match(query.semanticEditReplayCurrentHash ?? query.semanticEditReplayCurrentHashes, semanticEditIndex.semanticEditReplayCurrentHashes)
+    && match(query.semanticEditReplayOutputHash ?? query.semanticEditReplayOutputHashes, semanticEditIndex.semanticEditReplayOutputHashes)
+    && match(query.semanticEditKey ?? query.semanticEditKeys, semanticEditIndex.semanticEditKeys)
+    && match(query.semanticEditHash ?? query.semanticEditHashes, semanticEditIndex.semanticEditHashes)
+    && match(query.semanticIdentityHash ?? query.semanticIdentityHashes, semanticEditIndex.semanticIdentityHashes)
+    && match(query.sourceIdentityHash ?? query.sourceIdentityHashes, semanticEditIndex.sourceIdentityHashes)
+    && match(query.operationContentHash ?? query.operationContentHashes, semanticEditIndex.operationContentHashes)
+    && match(query.editContentHash ?? query.editContentHashes, semanticEditIndex.editContentHashes)
+    && match(query.constructKind ?? query.representationConstructKind, artifactConstructKinds(record))
+    && match(query.runtimeCapability, artifactRuntimeCapabilities(record))
+    && match(query.sourceMapPrecision, artifactSourceMapPrecisions(record))
+    && match(query.transformIdentityHash, artifactTransformIdentityHashes(record));
+}
+
+function artifactConstructKinds(record) {
+  return uniqueStrings([
+    ...(record.metadata?.representation?.constructKinds ?? []),
+    ...(record.mergeScore?.components?.representationCoverage?.signals?.constructKinds ?? []),
+    ...(record.semanticOperations?.operations ?? []).flatMap((operation) => operation.metadata?.representation?.constructKinds ?? [])
+  ]);
+}
+
+function artifactRuntimeCapabilities(record) {
+  return uniqueStrings([
+    ...(record.metadata?.representation?.runtimeCapabilities ?? []),
+    ...(record.mergeScore?.components?.representationCoverage?.signals?.runtimeCapabilities ?? []),
+    ...(record.semanticOperations?.operations ?? []).flatMap((operation) => operation.metadata?.representation?.runtimeCapabilities ?? [])
+  ]);
+}
+
+function artifactSourceMapPrecisions(record) {
+  return uniqueStrings([
+    ...(record.metadata?.representation?.sourceMapPrecisions ?? []),
+    ...(record.mergeScore?.components?.representationCoverage?.signals?.sourceMapPrecisions ?? []),
+    ...(record.semanticOperations?.operations ?? []).flatMap((operation) => operation.metadata?.representation?.sourceMapPrecisions ?? [])
+  ]);
+}
+
+function artifactTransformIdentityHashes(record) {
+  return uniqueStrings([
+    ...(record.metadata?.representation?.transformIdentityHashes ?? []),
+    ...(record.patchBundle?.index?.transformIdentityHashes ?? []),
+    ...(record.history?.index?.transformIdentityHashes ?? [])
+  ]);
 }
 
 function match(filter, values) {