@shapeshift-labs/frontier-lang-compiler 0.2.65 → 0.2.67

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

@@ -0,0 +1,314 @@
+import{idFragment,maxSemanticMergeReadiness,normalizeSemanticMergeReadiness,uniqueStrings}from'../../native-import-utils.js';
+import{semanticMergeConflictRiskScore}from'./semanticMergeConflicts.js';
+
+export const projectionRiskRank=Object.freeze({low:3,medium:2,unknown:1,high:0});
+const readinessSeverityRank=Object.freeze({ready:0,'ready-with-losses':1,'needs-review':2,blocked:3});
+const projectionRiskSeverityRank=Object.freeze({low:0,medium:1,unknown:2,high:3});
+const projectionRiskFromReadiness=Object.freeze({ready:'low','ready-with-losses':'medium','needs-review':'medium',blocked:'high'});
+const sourcePreservationRisk=Object.freeze({exact:'low',declaration:'medium',estimated:'medium',line:'medium',unknown:'medium',blocked:'high'});
+
+export function normalizeChangedSemanticRegions(input){
+  const records=[
+    ...input.changedRegions.map((region,index)=>regionFromChangedRegion(region,index,input)),
+    ...array(input.candidate.nativeSpans).map((span,index)=>regionFromNativeSpan(span,index,input)),
+    ...array(input.candidate.touchedSymbols).map((symbol,index)=>regionFromTouchedSymbol(symbol,index,input)),
+    ...array(input.candidate.touchedSemanticNodes).map((node,index)=>regionFromTouchedNode(node,index,input))
+  ].filter(Boolean);
+  const seen=new Set();
+  const result=[];
+  for(const record of records){
+    const key=[record.conflictKey,record.sourcePath,spanKey(record.sourceSpan),record.symbolId,record.semanticNodeId,record.nativeAstNodeId].join('|');
+    if(seen.has(key))continue;
+    seen.add(key);
+    result.push(record);
+  }
+  return result.sort((left,right)=>String(left.sourcePath??'').localeCompare(String(right.sourcePath??''))||String(left.conflictKey??left.key??left.id).localeCompare(String(right.conflictKey??right.key??right.id)));
+}
+
+function regionFromChangedRegion(region,index,input){
+  if(!region)return undefined;
+  const projection=region.metadata?.changedRegionProjection??region.projection;
+  const projected=projection?.region??{};
+  const before=projection?.before??{};
+  const after=projection?.after??{};
+  const key=firstString(region.key,region.ownershipKey,projected.key,region.conflictKey,region.id);
+  const readiness=normalizeSemanticMergeReadiness(projection?.admission?.readiness??region.admission?.readiness);
+  const sourceHash=firstString(region.sourceHash,after.sourceHash,before.sourceHash,input.sourceHash);
+  return compactRecord({
+    id:firstString(region.id,projected.id,`changed_region_${index+1}`),
+    key,
+    conflictKey:firstString(region.conflictKey,projection?.conflictKey,key),
+    changeKind:region.changeKind??projection?.changeKind,
+    regionKind:region.regionKind??region.ownershipRegionKind??projected.kind,
+    granularity:region.granularity??projected.granularity,
+    precision:region.precision??projected.precision,
+    projectionRisk:region.projectionRisk??riskForRegion(region,projection),
+    language:region.language??projection?.language??input.language,
+    sourcePath:region.sourcePath??projection?.sourcePath??region.sourceSpan?.path??input.sourcePath,
+    sourceHash,
+    baseHash:firstString(before.sourceHash,input.baseHash),
+    targetHash:firstString(after.sourceHash,input.targetHash),
+    symbolId:region.symbolId??projected.symbolId,
+    symbolName:region.symbolName??region.name??projected.symbolName,
+    symbolKind:region.symbolKind??projected.symbolKind,
+    semanticNodeId:region.semanticNodeId??projected.semanticNodeId,
+    nativeAstNodeId:region.nativeAstNodeId??projected.nativeAstNodeId,
+    sourceSpan:region.sourceSpan??projected.sourceSpan,
+    sourceMapLinkIds:uniqueStrings([...(region.sourceMapLinkIds??[]),...(projection?.sourceMapLinks??[]).map((link)=>link.id)]),
+    sourceMapIds:uniqueStrings([...(region.sourceMapIds??[]),...(projection?.sourceMapLinks??[]).map((link)=>link.sourceMapId)]),
+    sourceMapMappingIds:uniqueStrings([...(region.sourceMapMappingIds??[]),...(projection?.sourceMapLinks??[]).map((link)=>link.sourceMapMappingId)]),
+    admission:compactRecord({
+      readiness,
+      action:projection?.admission?.action??region.admission?.action,
+      reasonCodes:uniqueStrings([...(projection?.admission?.reasons??[]),...(region.admission?.reasonCodes??[])]),
+      conflictKeys:uniqueStrings([...(projection?.admission?.conflictKeys??[]),...(region.admission?.conflictKeys??[])])
+    })
+  });
+}
+
+function regionFromNativeSpan(span,index,input){
+  if(!span)return undefined;
+  const projection=span.metadata?.changedRegionProjection;
+  const readiness=normalizeSemanticMergeReadiness(projection?.admission?.readiness);
+  return compactRecord({
+    id:firstString(span.id,`native_span_region_${index+1}`),
+    key:firstString(span.metadata?.ownershipRegionKey,span.conflictKey,span.id),
+    conflictKey:firstString(span.conflictKey,span.metadata?.ownershipRegionKey,span.id),
+    changeKind:span.metadata?.changeKind,
+    regionKind:span.metadata?.regionKind??projection?.regionKind,
+    granularity:span.metadata?.granularity,
+    precision:span.metadata?.precision??projection?.precision,
+    projectionRisk:riskForRegion(span,projection),
+    language:span.language??input.language,
+    sourcePath:span.path??span.sourcePath??span.span?.path??input.sourcePath,
+    sourceHash:span.sourceHash??input.sourceHash,
+    baseHash:input.baseHash,
+    targetHash:input.targetHash,
+    symbolId:span.symbolId,
+    semanticNodeId:span.semanticNodeId,
+    nativeAstNodeId:span.nativeAstNodeId,
+    sourceSpan:span.span,
+    admission:compactRecord({readiness,action:projection?.admission?.action,reasonCodes:uniqueStrings(projection?.admission?.reasons),conflictKeys:uniqueStrings(projection?.admission?.conflictKeys)})
+  });
+}
+
+function regionFromTouchedSymbol(symbol,index,input){
+  if(!symbol)return undefined;
+  return compactRecord({
+    id:firstString(symbol.id,`symbol_region_${index+1}`),
+    key:firstString(symbol.metadata?.ownershipRegionKey,symbol.conflictKey,symbol.id),
+    conflictKey:firstString(symbol.conflictKey,symbol.metadata?.ownershipRegionKey,symbol.id),
+    regionKind:'symbol',
+    projectionRisk:riskForRegion(symbol),
+    language:input.language,
+    sourcePath:symbol.span?.path??input.sourcePath,
+    sourceHash:input.sourceHash,
+    baseHash:input.baseHash,
+    targetHash:input.targetHash,
+    symbolId:symbol.id,
+    symbolName:symbol.name,
+    symbolKind:symbol.kind,
+    semanticNodeId:symbol.semanticNodeId,
+    nativeAstNodeId:symbol.nativeAstNodeId,
+    sourceSpan:symbol.span
+  });
+}
+
+function regionFromTouchedNode(node,index,input){
+  if(!node)return undefined;
+  return compactRecord({
+    id:firstString(node.id,`semantic_node_region_${index+1}`),
+    key:firstString(node.conflictKey,node.id),
+    conflictKey:firstString(node.conflictKey,node.id),
+    regionKind:'semantic-node',
+    projectionRisk:'medium',
+    language:input.language,
+    sourcePath:input.sourcePath,
+    sourceHash:input.sourceHash,
+    baseHash:input.baseHash,
+    targetHash:input.targetHash,
+    semanticNodeId:node.id,
+    symbolName:node.name,
+    symbolKind:node.kind
+  });
+}
+
+function riskForRegion(region,projection){
+  const readiness=normalizeSemanticMergeReadiness(region?.admission?.readiness??projection?.admission?.readiness);
+  const explicit=normalizeProjectionRisk(region?.projectionRisk??projection?.projectionRisk);
+  if(explicit)return explicit;
+  if(readiness)return projectionRiskFromReadiness[readiness]??'medium';
+  const preservation=sourcePreservationRisk[String(region?.sourcePreservationLevel??projection?.sourcePreservationLevel??region?.precision??projection?.precision??'').toLowerCase()];
+  if(preservation)return preservation;
+  if((projection?.sourceMapLinks??region?.sourceMapLinks??[]).length)return 'low';
+  if(region?.sourceSpan||projection?.region?.sourceSpan)return 'medium';
+  return 'unknown';
+}
+
+export function inferProjectionRisk(input){
+  const regionRisk=input.changedSemanticRegions.reduce((current,region)=>maxProjectionRisk(current,normalizeProjectionRisk(region.projectionRisk)??riskForRegion(region)),'low');
+  const readinessRisk=projectionRiskFromReadiness[input.readiness]??'medium';
+  const conflictScore=semanticMergeConflictRiskScore(input.candidate);
+  const conflictRisk=conflictScore>=5000?'high':conflictScore>=3000?'medium':'low';
+  const patchRisk=normalizeProjectionRisk(input.patch?.risk??input.candidate?.risk)??'low';
+  const missingRegionRisk=input.conflictKeys.length&&!input.changedSemanticRegions.length?'medium':'low';
+  return [regionRisk,readinessRisk,conflictRisk,patchRisk,missingRegionRisk].reduce(maxProjectionRisk,'low');
+}
+
+function maxProjectionRisk(left,right){
+  return (projectionRiskSeverityRank[left]??2)>=(projectionRiskSeverityRank[right]??2)?left:right;
+}
+
+export function normalizeProjectionRisk(value){
+  const risk=String(value??'').toLowerCase();
+  return Object.prototype.hasOwnProperty.call(projectionRiskRank,risk)?risk:undefined;
+}
+
+export function internalOverlaps(regions){
+  const synthetic=regions.map((region,index)=>({id:`internal_${index+1}`,candidateId:`internal_${index+1}`,readiness:region.admission?.readiness??'ready',changedSemanticRegions:[region]}));
+  return queryInternalOverlaps(synthetic);
+}
+
+export function queryAdmissionOverlaps(list,query={}){
+  const result=[];
+  for(let leftIndex=0;leftIndex<list.length;leftIndex+=1){
+    for(let rightIndex=leftIndex+1;rightIndex<list.length;rightIndex+=1){
+      result.push(...candidateOverlaps(list[leftIndex],list[rightIndex]));
+    }
+  }
+  return result.filter((overlap)=>matchesOverlap(overlap,query)).sort(compareOverlapRecords);
+}
+
+function queryInternalOverlaps(records){
+  const result=[];
+  for(let left=0;left<records.length;left+=1){
+    for(let right=left+1;right<records.length;right+=1){
+      result.push(...candidateOverlaps(records[left],records[right]));
+    }
+  }
+  return result;
+}
+
+function candidateOverlaps(left,right){
+  const records=[];
+  for(const leftRegion of left.changedSemanticRegions??[]){
+    for(const rightRegion of right.changedSemanticRegions??[]){
+      const overlap=regionOverlap(left,right,leftRegion,rightRegion,records.length+1);
+      if(overlap)records.push(overlap);
+    }
+  }
+  return dedupeOverlaps(records);
+}
+
+function regionOverlap(left,right,leftRegion,rightRegion,index){
+  const sameConflictKey=Boolean(leftRegion.conflictKey&&rightRegion.conflictKey&&leftRegion.conflictKey===rightRegion.conflictKey);
+  const sameRegionKey=Boolean(leftRegion.key&&rightRegion.key&&leftRegion.key===rightRegion.key);
+  const spanOverlap=regionsSpanOverlap(leftRegion,rightRegion);
+  if(!sameConflictKey&&!sameRegionKey&&!spanOverlap)return undefined;
+  const overlapKind=sameConflictKey?'conflict-key':sameRegionKey?'region-key':'source-span';
+  const conflictKeys=uniqueStrings([leftRegion.conflictKey,rightRegion.conflictKey]);
+  return {
+    schema:'frontier.lang.semanticMergeCandidateOverlap.v1',
+    id:`overlap_${idFragment(left.id)}_${idFragment(right.id)}_${index}`,
+    overlapKind,
+    risk:overlapKind==='source-span'?'medium':'high',
+    readiness:maxSemanticMergeReadiness(left.readiness,right.readiness),
+    recordIds:[left.id,right.id],
+    candidateIds:uniqueStrings([left.candidateId,right.candidateId]),
+    regionIds:uniqueStrings([leftRegion.id,rightRegion.id]),
+    regionKeys:uniqueStrings([leftRegion.key,rightRegion.key]),
+    conflictKeys,
+    sourcePath:firstString(leftRegion.sourcePath,rightRegion.sourcePath),
+    leftRegion:compactOverlapRegion(leftRegion),
+    rightRegion:compactOverlapRegion(rightRegion)
+  };
+}
+
+export function summarizeOverlaps(overlaps){
+  return {
+    total:overlaps.length,
+    hasOverlaps:overlaps.length>0,
+    byKind:countBy(overlaps.map((overlap)=>overlap.overlapKind)),
+    conflictKeys:uniqueStrings(overlaps.flatMap((overlap)=>overlap.conflictKeys??[])),
+    pairs:overlaps
+  };
+}
+
+function matchesOverlap(overlap,query){
+  return matchAny(queryValues(query.id,query.ids),[overlap.id])
+    &&matchAny(queryValues(query.candidateId,query.candidateIds),overlap.candidateIds)
+    &&matchAny(queryValues(query.recordId,query.recordIds),overlap.recordIds)
+    &&matchAny(queryValues(query.regionId,query.regionIds),overlap.regionIds)
+    &&matchAny(queryValues(query.regionKey,query.regionKeys),overlap.regionKeys)
+    &&matchAny(queryValues(query.conflictKey,query.conflictKeys),overlap.conflictKeys)
+    &&matchAny(queryValues(query.sourcePath,query.sourcePaths),[overlap.sourcePath])
+    &&matchAny(queryValues(query.overlapKind,query.overlapKinds),[overlap.overlapKind])
+    &&matchAny(queryValues(query.readiness,query.readinesses),[overlap.readiness])
+    &&matchAny(queryValues(query.risk,query.risks),[overlap.risk]);
+}
+
+function compareOverlapRecords(left,right){
+  return (projectionRiskSeverityRank[right.risk]??1)-(projectionRiskSeverityRank[left.risk]??1)
+    ||(readinessSeverityRank[right.readiness]??1)-(readinessSeverityRank[left.readiness]??1)
+    ||String(left.id).localeCompare(String(right.id));
+}
+
+function regionsSpanOverlap(left,right){
+  const leftPath=left.sourcePath??left.sourceSpan?.path;
+  const rightPath=right.sourcePath??right.sourceSpan?.path;
+  if(leftPath&&rightPath&&leftPath!==rightPath)return false;
+  return spansOverlap(left.sourceSpan,right.sourceSpan);
+}
+
+function spansOverlap(left,right){
+  if(!left||!right)return false;
+  const leftRange=spanRange(left);
+  const rightRange=spanRange(right);
+  if(!leftRange||!rightRange)return false;
+  return leftRange.start<=rightRange.end&&rightRange.start<=leftRange.end;
+}
+
+function spanRange(span){
+  const startLine=numberValue(span.startLine??span.line??span.start?.line);
+  const endLine=numberValue(span.endLine??span.end?.line??startLine);
+  if(!Number.isFinite(startLine)||!Number.isFinite(endLine))return undefined;
+  const startColumn=numberValue(span.startColumn??span.column??span.start?.column??0);
+  const endColumn=numberValue(span.endColumn??span.end?.column??startColumn);
+  return {start:startLine*100000+startColumn,end:endLine*100000+Math.max(startColumn,endColumn)};
+}
+
+function dedupeOverlaps(records){
+  const seen=new Set();
+  const result=[];
+  for(const record of records){
+    const key=[record.overlapKind,record.recordIds.join('|'),record.regionIds.join('|'),record.conflictKeys.join('|')].join(':');
+    if(seen.has(key))continue;
+    seen.add(key);
+    result.push(record);
+  }
+  return result;
+}
+
+function compactOverlapRegion(region){
+  return compactRecord({
+    id:region.id,
+    key:region.key,
+    conflictKey:region.conflictKey,
+    sourcePath:region.sourcePath,
+    sourceSpan:region.sourceSpan,
+    symbolId:region.symbolId,
+    semanticNodeId:region.semanticNodeId,
+    nativeAstNodeId:region.nativeAstNodeId,
+    projectionRisk:region.projectionRisk
+  });
+}
+
+function countBy(values){const counts={};for(const value of values??[]){const key=String(value??'unknown');counts[key]=(counts[key]??0)+1;}return counts;}
+function queryValues(...values){return uniqueStrings(values.flatMap((value)=>strings(value)));}
+function matchAny(filters,values){if(filters.length===0)return true;const valueSet=new Set(strings(values));return filters.some((filter)=>valueSet.has(filter));}
+function spanKey(span){if(!span)return'';const range=spanRange(span);return range?`${range.start}-${range.end}`:'';}
+function numberValue(value){const number=Number(value);return Number.isFinite(number)?number:undefined;}
+function array(value){if(value===undefined||value===null)return[];return Array.isArray(value)?value:[value];}
+function strings(value){return array(value).map((entry)=>String(entry??'')).filter(Boolean);}
+function firstString(...values){return values.map((value)=>value===undefined||value===null?'':String(value)).find(Boolean);}
+function compactRecord(value){return Object.fromEntries(Object.entries(value??{}).filter(([,entry])=>entry!==undefined&&(!Array.isArray(entry)||entry.length>0)));}

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

@@ -0,0 +1,241 @@
+import{idFragment,normalizeSemanticMergeReadiness,uniqueStrings}from'../../native-import-utils.js';
+import{semanticMergeConflictRiskScore}from'./semanticMergeConflicts.js';
+import{inferProjectionRisk,internalOverlaps,normalizeChangedSemanticRegions,normalizeProjectionRisk,projectionRiskRank,queryAdmissionOverlaps,summarizeOverlaps}from'./semanticMergeCandidateRecordInternals.js';
+
+export const SemanticMergeCandidateProjectionRisks=Object.freeze(['low','medium','high','unknown']);
+
+const readinessRank=Object.freeze({ready:3,'ready-with-losses':2,'needs-review':1,blocked:0});
+
+export function createSemanticMergeCandidateAdmissionRecord(input={},options={}){
+  const source=input?.kind==='frontier.lang.nativeSourceChangeSet'?input:options.changeSet??input;
+  const candidate=options.candidate??source.mergeCandidate??source.candidate??input;
+  const patch=options.patch??source.patch??candidate.patch;
+  const readiness=normalizeSemanticMergeReadiness(options.readiness??candidate.readiness??source.readiness)
+    ??options.readiness??candidate.readiness??source.readiness??'needs-review';
+  const evidenceRecords=uniqueRecords([
+    ...array(options.evidence),
+    ...array(source.evidence),
+    ...array(candidate.evidence),
+    ...array(patch?.evidence)
+  ]);
+  const evidenceIds=uniqueStrings([
+    ...strings(options.evidenceIds),
+    ...strings(source.evidenceIds),
+    ...strings(candidate.evidenceIds),
+    ...evidenceRecords.map((record)=>record?.id)
+  ]);
+  const proofIds=uniqueStrings([
+    ...strings(options.proofIds),
+    ...strings(source.proofIds),
+    ...strings(candidate.proofIds),
+    ...evidenceRecords.filter((record)=>isProofEvidence(record)).map((record)=>record.id)
+  ]);
+  const changedSemanticRegions=normalizeChangedSemanticRegions({
+    candidate,
+    changedRegions:[
+      ...array(options.changedRegions),
+      ...array(source.changedRegions),
+      ...array(candidate.changedSemanticRegions),
+      ...array(candidate.changedRegions),
+      ...array(candidate.metadata?.changedSemanticRegions),
+      ...array(candidate.metadata?.changedRegions)
+    ],
+    language:options.language??candidate.language??source.language,
+    sourcePath:options.sourcePath??candidate.sourcePath??source.sourcePath,
+    baseHash:firstString(options.baseHash,source.beforeHash,source.baseHash,patch?.baseHash,candidate.baseHash),
+    targetHash:firstString(options.targetHash,source.afterHash,source.targetHash,patch?.targetHash,candidate.targetHash),
+    sourceHash:firstString(options.sourceHash,source.afterHash,source.targetHash,candidate.targetHash,source.beforeHash,source.baseHash,candidate.baseHash)
+  });
+  const conflictKeys=uniqueStrings([
+    ...strings(options.conflictKeys),
+    ...strings(source.conflictKeys),
+    ...strings(candidate.conflictKeys),
+    ...changedSemanticRegions.flatMap((region)=>[region.conflictKey,...array(region.admission?.conflictKeys)]),
+    ...array(candidate.conflictClasses).flatMap((record)=>record?.conflictKeys??[]),
+    ...(candidate.conflictSummary?.conflictKeys??candidate.metadata?.conflictSummary?.conflictKeys??[]),
+    ...(source.metadata?.semanticMergeConflictSummary?.conflictKeys??[])
+  ]);
+  const baseHash=firstString(options.baseHash,source.beforeHash,source.baseHash,patch?.baseHash,candidate.baseHash,...changedSemanticRegions.map((region)=>region.baseHash));
+  const targetHash=firstString(options.targetHash,source.afterHash,source.targetHash,patch?.targetHash,candidate.targetHash,...changedSemanticRegions.map((region)=>region.targetHash));
+  const sourceHashes=uniqueStrings([
+    ...strings(options.sourceHashes),
+    ...sourceHashValues(source.sourceHashes),
+    ...sourceHashValues(candidate.sourceHashes),
+    source.beforeHash,
+    source.afterHash,
+    source.baseHash,
+    source.targetHash,
+    candidate.baseHash,
+    candidate.targetHash,
+    patch?.baseHash,
+    patch?.targetHash,
+    ...changedSemanticRegions.flatMap((region)=>[region.sourceHash,region.baseHash,region.targetHash])
+  ]);
+  const projectionRisk=normalizeProjectionRisk(options.projectionRisk??candidate.projectionRisk??candidate.risk)
+    ??inferProjectionRisk({readiness,candidate,patch,changedSemanticRegions,conflictKeys});
+  const overlaps=internalOverlaps(changedSemanticRegions);
+  const readinessSortKey=semanticMergeCandidateReadinessSortKey({
+    readiness,
+    projectionRisk,
+    evidenceIds,
+    proofIds,
+    changedSemanticRegions,
+    overlaps
+  });
+  const candidateId=firstString(options.candidateId,candidate.id,source.mergeCandidateId);
+  const id=options.id??(source.kind==='frontier.lang.semanticMergeCandidateAdmissionRecord'?source.id:undefined)
+    ??`semantic_merge_candidate_${idFragment(firstString(candidateId,source.id,source.sourcePath,source.language,'candidate'))}`;
+  return {
+    kind:'frontier.lang.semanticMergeCandidateAdmissionRecord',
+    version:1,
+    schema:'frontier.lang.semanticMergeCandidateAdmissionRecord.v1',
+    id,
+    candidateId,
+    importResultId:firstString(options.importResultId,candidate.importResultId,source.importResultId,source.after?.id,source.before?.id),
+    patchId:firstString(options.patchId,candidate.patchId,patch?.id,source.patchId),
+    language:options.language??candidate.language??source.language,
+    sourcePath:options.sourcePath??candidate.sourcePath??source.sourcePath,
+    readiness,
+    readinessSortKey,
+    projectionRisk,
+    sourceHashes:{baseHash,targetHash,values:sourceHashes},
+    baseHash,
+    targetHash,
+    changedSemanticRegions,
+    conflictKeys,
+    evidenceIds,
+    proofIds,
+    overlapSummary:summarizeOverlaps(overlaps),
+    admission:{
+      readiness,
+      reviewRequired:readiness!=='ready'||projectionRisk!=='low'||overlaps.length>0,
+      action:admissionAction({readiness,projectionRisk,overlaps}),
+      sortKey:readinessSortKey,
+      reasonCodes:uniqueStrings([
+        ...strings(options.reasonCodes),
+        ...strings(source.reasons),
+        ...strings(candidate.reasons),
+        ...(projectionRisk!=='low'?[`projection-risk:${projectionRisk}`]:[]),
+        ...(overlaps.length?['overlapping-semantic-regions']:[])
+      ]),
+      conflictKeys
+    },
+    index:{
+      candidateIds:uniqueStrings([candidateId]),
+      importResultIds:uniqueStrings([candidate.importResultId,source.importResultId,source.after?.id,source.before?.id]),
+      patchIds:uniqueStrings([candidate.patchId,patch?.id,source.patchId]),
+      sourcePaths:uniqueStrings([options.sourcePath,candidate.sourcePath,source.sourcePath,...changedSemanticRegions.map((region)=>region.sourcePath)]),
+      sourceHashes,
+      baseHashes:uniqueStrings([baseHash]),
+      targetHashes:uniqueStrings([targetHash]),
+      regionIds:uniqueStrings(changedSemanticRegions.map((region)=>region.id)),
+      regionKeys:uniqueStrings(changedSemanticRegions.map((region)=>region.key)),
+      regionKinds:uniqueStrings(changedSemanticRegions.map((region)=>region.regionKind)),
+      conflictKeys,
+      evidenceIds,
+      proofIds,
+      readinesses:uniqueStrings([readiness,...changedSemanticRegions.map((region)=>region.admission?.readiness)]),
+      projectionRisks:uniqueStrings([projectionRisk,...changedSemanticRegions.map((region)=>region.projectionRisk)])
+    },
+    summary:{
+      changedSemanticRegions:changedSemanticRegions.length,
+      conflictKeys:conflictKeys.length,
+      evidenceIds:evidenceIds.length,
+      proofIds:proofIds.length,
+      overlaps:overlaps.length,
+      readiness,
+      projectionRisk,
+      reviewRequired:readiness!=='ready'||projectionRisk!=='low'||overlaps.length>0
+    },
+    metadata:compactRecord({
+      sourceChangeSetId:source.kind==='frontier.lang.nativeSourceChangeSet'?source.id:undefined,
+      conflictRiskScore:semanticMergeConflictRiskScore(candidate),
+      conflictSummary:candidate.conflictSummary??candidate.metadata?.conflictSummary??source.metadata?.semanticMergeConflictSummary,
+      changedRegionProjectionSummary:source.metadata?.changedRegionProjectionSummary??candidate.metadata?.changedRegionProjectionSummary,
+      compact:true,
+      note:'Semantic merge candidate admission records normalize changed regions, hashes, evidence, conflict keys, readiness, projection risk, and overlap signals for coordinator merge admission.',
+      ...options.metadata
+    })
+  };
+}
+
+export function decorateSemanticMergeCandidateForAdmission(input={},options={}){
+  const admissionRecord=createSemanticMergeCandidateAdmissionRecord(input,options);
+  const candidate=options.candidate??(input?.kind==='frontier.lang.nativeSourceChangeSet'?input.mergeCandidate:input);
+  return {
+    ...candidate,
+    changedSemanticRegions:admissionRecord.changedSemanticRegions,
+    sourceHashes:admissionRecord.sourceHashes,
+    evidenceIds:admissionRecord.evidenceIds,
+    proofIds:admissionRecord.proofIds,
+    projectionRisk:admissionRecord.projectionRisk,
+    readinessSortKey:admissionRecord.readinessSortKey,
+    mergeAdmission:admissionRecord
+  };
+}
+
+export function sortSemanticMergeCandidateAdmissionRecords(records,options={}){
+  const normalized=array(records).filter(Boolean).map((record)=>
+    record.kind==='frontier.lang.semanticMergeCandidateAdmissionRecord'?record:createSemanticMergeCandidateAdmissionRecord(record)
+  );
+  const sorted=normalized.sort((left,right)=>
+    right.readinessSortKey-left.readinessSortKey
+    ||(projectionRiskRank[right.projectionRisk]??1)-(projectionRiskRank[left.projectionRisk]??1)
+    ||String(left.candidateId??left.id??'').localeCompare(String(right.candidateId??right.id??''))
+  );
+  return options.desc===false?sorted.reverse():sorted;
+}
+
+export function querySemanticMergeCandidateAdmissionOverlaps(records,query={}){
+  const list=array(records).filter(Boolean).map((record)=>
+    record.kind==='frontier.lang.semanticMergeCandidateAdmissionRecord'?record:createSemanticMergeCandidateAdmissionRecord(record)
+  );
+  return queryAdmissionOverlaps(list,query);
+}
+
+export function semanticMergeCandidateReadinessSortKey(candidateOrRecord){
+  const readiness=normalizeSemanticMergeReadiness(candidateOrRecord?.readiness)??candidateOrRecord?.readiness??'needs-review';
+  const projectionRisk=normalizeProjectionRisk(candidateOrRecord?.projectionRisk)??'unknown';
+  const evidenceIds=array(candidateOrRecord?.evidenceIds);
+  const proofIds=array(candidateOrRecord?.proofIds);
+  const changedSemanticRegions=array(candidateOrRecord?.changedSemanticRegions);
+  const overlaps=array(candidateOrRecord?.overlaps??candidateOrRecord?.overlapSummary?.pairs);
+  return (readinessRank[readiness]??readinessRank['needs-review'])*100000
+    +(projectionRiskRank[projectionRisk]??1)*10000
+    +Math.min(99,evidenceIds.length)*100
+    +Math.min(99,proofIds.length)*25
+    -Math.min(99,changedSemanticRegions.length)
+    -Math.min(99,overlaps.length)*250;
+}
+
+function admissionAction(input){
+  if(input.readiness==='blocked'||input.projectionRisk==='high')return'block';
+  if(input.readiness==='needs-review'||input.projectionRisk!=='low'||input.overlaps.length)return'prioritize-review';
+  return'admit';
+}
+
+function uniqueRecords(records){
+  const seen=new Set();
+  const result=[];
+  for(const record of records.filter(Boolean)){
+    const id=record.id??`record_${result.length+1}`;
+    if(seen.has(id))continue;
+    seen.add(id);
+    result.push(record.id?record:{...record,id});
+  }
+  return result;
+}
+
+function sourceHashValues(value){
+  if(value&&typeof value==='object'&&!Array.isArray(value))return [value.baseHash,value.targetHash,...array(value.values)].filter(Boolean);
+  return strings(value);
+}
+
+function isProofEvidence(record){
+  return /proof|test|trace|verify|verification|benchmark|behavior|contract/i.test(String(record?.kind??record?.metadata?.kind??record?.type??''));
+}
+
+function array(value){if(value===undefined||value===null)return[];return Array.isArray(value)?value:[value];}
+function strings(value){return array(value).map((entry)=>String(entry??'')).filter(Boolean);}
+function firstString(...values){return values.map((value)=>value===undefined||value===null?'':String(value)).find(Boolean);}
+function compactRecord(value){return Object.fromEntries(Object.entries(value??{}).filter(([,entry])=>entry!==undefined&&(!Array.isArray(entry)||entry.length>0)));}