@shapeshift-labs/frontier-lang-compiler 0.2.66 → 0.2.68

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

@@ -1,8 +1,10 @@
 import{countBy,maxSemanticMergeReadiness,uniqueRecordsById,uniqueStrings}from'../../native-import-utils.js';
 import{createSemanticMergeCandidateAdmissionRecord,querySemanticMergeCandidateAdmissionOverlaps,sortSemanticMergeCandidateAdmissionRecords}from'./semanticMergeCandidateRecords.js';
+import{compactAdmissionSource,importLosses,sourceLossClasses,summarizeImportPreservation,summarizeParserEvidence}from'./projectImportAdmissionImportEvidence.js';
+import{sourceMissingEvidence,sourceMissingTasks,sourceSemanticMergeScore}from'./projectImportAdmissionTasks.js';
+import{candidateRisk,maxPreservationQuality,maxRisk,normalizeRisk}from'./projectImportAdmissionRanks.js';
 
-const riskRank=Object.freeze({low:0,medium:1,unknown:2,high:3});
-const preservationRank=Object.freeze({exact:0,lossy:1,missing:2,stale:3,empty:4});
+export{admissionLanguages}from'./projectImportAdmissionLanguageSummaries.js';
 
 export function projectAdmissionImports(imports,sourceRows,mergeCandidates){
   return imports.map((imported,index)=>{
@@ -18,49 +20,59 @@ export function projectAdmissionImports(imports,sourceRows,mergeCandidates){
       relations:semanticIndex?.relations?.length??0,
       facts:semanticIndex?.facts?.length??0
     };
+    const readiness=source.readiness??imported?.metadata?.semanticMergeReadiness??candidates[0]?.readiness??'ready';
+    const emptySemanticEvidence=Object.values(semanticCounts).reduce((sum,value)=>sum+value,0)===0;
+    const sourcePreservation=summarizeImportPreservation(imported,source);
+    const losses=importLosses(imported);
+    const lossClasses=sourceLossClasses(imported,losses);
+    const parserEvidence=summarizeParserEvidence(imported,source,losses);
+    const missingEvidence=sourceMissingEvidence({
+      imported,
+      source,
+      losses,
+      semanticCounts,
+      emptySemanticEvidence,
+      sourcePreservation,
+      parserEvidence
+    });
+    const nextMissingTasks=sourceMissingTasks({
+      source,
+      readiness,
+      semanticCounts,
+      emptySemanticEvidence,
+      sourcePreservation,
+      parserEvidence,
+      lossClasses,
+      losses,
+      missingEvidence,
+      candidates
+    });
     return {
       id:source.id??imported?.id,
       language:source.language??imported?.language??'unknown',
       sourcePath,
       sourceHash:source.sourceHash,
-      readiness:source.readiness??imported?.metadata?.semanticMergeReadiness??candidates[0]?.readiness??'ready',
+      readiness,
       semanticCounts,
-      emptySemanticEvidence:Object.values(semanticCounts).reduce((sum,value)=>sum+value,0)===0,
-      sourcePreservation:summarizeImportPreservation(imported,source),
+      emptySemanticEvidence,
+      parserEvidence,
+      lossClasses,
+      missingEvidence,
+      nextMissingTasks,
+      semanticMergeScore:sourceSemanticMergeScore({
+        readiness,
+        emptySemanticEvidence,
+        sourcePreservation,
+        parserEvidence,
+        missingEvidence,
+        candidates
+      }),
+      sourcePreservation,
       mergeCandidates:candidates
     };
   });
 }
 
-export function admissionLanguages(importSummaries){
-  const grouped=new Map();
-  for(const entry of importSummaries){
-    const key=entry.language??'unknown';
-    if(!grouped.has(key)) grouped.set(key,emptyLanguageRow(key));
-    const row=grouped.get(key);
-    row.sourceCount+=1;
-    row.sourcePaths.push(entry.sourcePath);
-    row.readiness=maxSemanticMergeReadiness(row.readiness,entry.readiness);
-    row.semanticSymbols+=entry.semanticCounts.symbols;
-    if(entry.emptySemanticEvidence) row.emptySemanticEvidenceSources+=1;
-    row.sourcePreservationQuality=maxPreservationQuality(row.sourcePreservationQuality,entry.sourcePreservation.quality);
-    if(entry.sourcePreservation.stale&&entry.sourcePath) row.staleSourcePaths.push(entry.sourcePath);
-    row.mergeCandidates+=entry.mergeCandidates.length;
-    row.highestRisk=maxRisk(row.highestRisk,entry.mergeCandidates.reduce((current,candidate)=>maxRisk(current,candidateRisk(candidate)),'low'));
-  }
-  const rows=[...grouped.values()].map((row)=>({
-    ...row,
-    sourcePaths:uniqueStrings(row.sourcePaths.filter(Boolean)),
-    staleSourcePaths:uniqueStrings(row.staleSourcePaths.filter(Boolean))
-  })).sort((left,right)=>left.language.localeCompare(right.language));
-  return {
-    total:rows.length,
-    byReadiness:countBy(rows.map((row)=>row.readiness)),
-    bySourcePreservationQuality:countBy(rows.map((row)=>row.sourcePreservationQuality)),
-    rows
-  };
-}
-
 export function admissionSemanticEvidence(projectResult,imports,importSummaries){
   const projectIndex=projectResult?.semanticIndex??projectResult?.universalAst?.semanticIndex;
   const indexes=projectIndex?[projectIndex]:imports.flatMap((imported)=>[
@@ -198,80 +210,3 @@ export function admissionMergeCandidates(projectResult,imports,mergeCandidates,l
     patchRisk:normalizeRisk(projectResult?.patch?.risk)
   };
 }
-
-export function candidateRisk(candidate,patch){
-  return normalizeRisk(candidate?.risk)??normalizeRisk(patch?.risk)??readinessRisk(candidate?.readiness);
-}
-
-export function maxRisk(left,right){
-  return riskRank[left]>=riskRank[right]?left:right;
-}
-
-export function maxPreservationQuality(left,right){
-  return preservationRank[left]>=preservationRank[right]?left:right;
-}
-
-function compactAdmissionSource(imported,index){
-  const semanticIndex=imported?.semanticIndex??imported?.universalAst?.semanticIndex;
-  const nativeAst=imported?.nativeAst??imported?.nativeSource?.ast;
-  const sourceMaps=imported?.sourceMaps??imported?.universalAst?.sourceMaps??[];
-  return {
-    id:imported?.id??`import_${index+1}`,
-    language:imported?.language??imported?.nativeSource?.language??nativeAst?.language,
-    sourcePath:imported?.sourcePath??imported?.nativeSource?.sourcePath??nativeAst?.sourcePath,
-    sourceHash:imported?.nativeSource?.sourceHash??nativeAst?.sourceHash,
-    parser:nativeAst?.parser??imported?.nativeSource?.parser,
-    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 summarizeImportPreservation(imported,source){
-  const nativeAst=imported?.nativeAst??imported?.nativeSource?.ast;
-  const record=imported?.metadata?.sourcePreservation
-    ??imported?.nativeSource?.metadata?.sourcePreservation
-    ??nativeAst?.metadata?.sourcePreservation
-    ??imported?.universalAst?.metadata?.sourcePreservation;
-  const sourceHash=source?.sourceHash??imported?.nativeSource?.sourceHash??nativeAst?.sourceHash;
-  const sourcePreservationLosses=(imported?.losses??nativeAst?.losses??[]).filter((loss)=>loss.kind==='sourcePreservation');
-  const stale=imported?.metadata?.sourceHashVerified===false
-    ||imported?.nativeSource?.metadata?.sourceHashVerified===false
-    ||nativeAst?.metadata?.sourceHashVerified===false
-    ||record?.metadata?.sourceHashVerified===false
-    ||Boolean(record?.sourceHash&&sourceHash&&record.sourceHash!==sourceHash);
-  const missing=!record;
-  const truncated=record?.summary?.truncated===true;
-  const exactSourceAvailable=record?.summary?.exactSourceAvailable===true;
-  const quality=stale?'stale':missing?'missing':truncated||!exactSourceAvailable||sourcePreservationLosses.length?'lossy':'exact';
-  return {quality,missing,stale,truncated,exactSourceAvailable,lossCount:sourcePreservationLosses.length,id:record?.id};
-}
-
-function emptyLanguageRow(language){
-  return {
-    language,
-    sourceCount:0,
-    sourcePaths:[],
-    readiness:'ready',
-    semanticSymbols:0,
-    emptySemanticEvidenceSources:0,
-    sourcePreservationQuality:'exact',
-    staleSourcePaths:[],
-    mergeCandidates:0,
-    highestRisk:'low'
-  };
-}
-
-function readinessRisk(readiness){
-  if(readiness==='blocked') return 'high';
-  if(readiness==='needs-review'||readiness==='ready-with-losses') return 'medium';
-  return 'low';
-}
-
-function normalizeRisk(value){
-  const risk=String(value??'').toLowerCase();
-  return Object.prototype.hasOwnProperty.call(riskRank,risk)?risk:undefined;
-}

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

@@ -0,0 +1,239 @@
+import{maxSemanticMergeReadiness,uniqueStrings}from'../../native-import-utils.js';
+import{nativeImportCategoryForLossKind}from'./nativeImportCategoryForLossKind.js';
+import{candidateRisk,clampScore,maxRisk,maxTaskPriority,readinessSort,sourceScoreByReadiness,taskPriorityForReadiness,taskPriorityRank}from'./projectImportAdmissionRanks.js';
+
+export function sourceMissingEvidence(input){
+  const lossSummary=input.imported?.metadata?.nativeImportLossSummary
+    ??input.imported?.nativeSource?.metadata?.nativeImportLossSummary
+    ??input.imported?.nativeAst?.metadata?.nativeImportLossSummary
+    ??input.imported?.universalAst?.metadata?.nativeImportLossSummary;
+  const sourcePath=input.source?.sourcePath??input.imported?.sourcePath;
+  const language=input.source?.language??input.imported?.language??'unknown';
+  const hints=[];
+  for(const missing of lossSummary?.featureEvidence?.missingRequiredEvidence??[]){
+    const lossClass=nativeImportCategoryForLossKind(missing.kind??missing.policyKind);
+    hints.push(evidenceHint({
+      evidenceKey:missing.evidenceKey,
+      task:`Add ${missing.evidenceKey} evidence for ${missing.kind??missing.policyKind}.`,
+      sourcePath,
+      language,
+      lossId:missing.lossId,
+      lossKind:missing.kind??missing.policyKind,
+      lossClass,
+      readiness:'needs-review'
+    }));
+  }
+  if(input.emptySemanticEvidence){
+    hints.push(evidenceHint({
+      evidenceKey:'semantic-index',
+      task:'Import semantic symbols for sources with empty semantic indexes.',
+      sourcePath,
+      language,
+      lossKind:'partialSemanticIndex',
+      lossClass:'partialSemanticIndex',
+      readiness:'blocked'
+    }));
+  }
+  if(input.parserEvidence.missing){
+    hints.push(evidenceHint({
+      evidenceKey:'parser-result',
+      task:'Attach a native parser AST instead of missing-parser fallback evidence.',
+      sourcePath,
+      language,
+      lossKind:'unsupportedSyntax',
+      lossClass:'parserDiagnostics',
+      readiness:'blocked'
+    }));
+  }
+  if(input.sourcePreservation.stale){
+    hints.push(evidenceHint({
+      evidenceKey:'source-hash-verification',
+      task:'Refresh source hashes or re-import the stale source text.',
+      sourcePath,
+      language,
+      lossKind:'sourcePreservation',
+      lossClass:'sourcePreservation',
+      readiness:'blocked'
+    }));
+  }else if(input.sourcePreservation.quality==='missing'||input.sourcePreservation.quality==='lossy'){
+    hints.push(evidenceHint({
+      evidenceKey:'source-preservation',
+      task:'Attach exact source-preservation evidence for lossy or missing source text.',
+      sourcePath,
+      language,
+      lossKind:'sourcePreservation',
+      lossClass:'sourcePreservation',
+      readiness:'needs-review'
+    }));
+  }
+  return uniqueEvidenceHints(hints);
+}
+
+export function sourceMissingTasks(input){
+  const sourcePath=input.source?.sourcePath;
+  const language=input.source?.language??'unknown';
+  const tasks=[];
+  for(const hint of input.missingEvidence??[]){
+    tasks.push(taskHint({
+      id:`evidence:${hint.evidenceKey}`,
+      task:hint.task,
+      reason:'missing-evidence',
+      priority:taskPriorityForReadiness(hint.readiness),
+      readiness:hint.readiness,
+      sourcePath,
+      language,
+      lossClasses:hint.lossClasses,
+      evidenceKeys:[hint.evidenceKey]
+    }));
+  }
+  for(const lossClass of input.lossClasses??[]){
+    const task=taskForLossClass(lossClass);
+    if(task){
+      tasks.push(taskHint({
+        ...task,
+        sourcePath,
+        language,
+        readiness:input.readiness,
+        lossClasses:[lossClass]
+      }));
+    }
+  }
+  const reviewCandidates=(input.candidates??[]).filter((candidate)=>
+    candidate.readiness==='needs-review'
+    || candidate.readiness==='blocked'
+    || candidateRisk(candidate)!=='low'
+  );
+  if(reviewCandidates.length){
+    tasks.push(taskHint({
+      id:'semantic-merge-review',
+      task:'Review semantic merge candidates that carry elevated risk or review readiness.',
+      reason:'merge-candidate-risk',
+      priority:reviewCandidates.some((candidate)=>candidateRisk(candidate)==='high'||candidate.readiness==='blocked')?'critical':'high',
+      readiness:reviewCandidates.reduce((current,candidate)=>maxSemanticMergeReadiness(current,candidate.readiness??'ready'),input.readiness),
+      sourcePath,
+      language,
+      lossClasses:[],
+      evidenceKeys:[]
+    }));
+  }
+  if(!tasks.length&&input.readiness!=='ready'){
+    tasks.push(taskHint({
+      id:'native-import-review',
+      task:'Review native import losses before admitting this source.',
+      reason:'readiness-review',
+      priority:taskPriorityForReadiness(input.readiness),
+      readiness:input.readiness,
+      sourcePath,
+      language,
+      lossClasses:input.lossClasses,
+      evidenceKeys:[]
+    }));
+  }
+  return uniqueTaskHints(tasks);
+}
+
+function taskForLossClass(lossClass){
+  if(lossClass==='exactAstImport'||lossClass==='none') return undefined;
+  if(lossClass==='partialSemanticIndex'){
+    return {id:'semantic-index-completeness',task:'Complete semantic index coverage for partial imports.',reason:'partial-semantic-index',priority:'high',evidenceKeys:['semantic-index']};
+  }
+  if(lossClass==='declarationsOnly'||lossClass==='opaqueBodies'){
+    return {id:'body-semantics',task:'Import body-level semantic evidence beyond declaration-only coverage.',reason:'declaration-only-or-opaque-body',priority:'normal',evidenceKeys:['body-semantics']};
+  }
+  if(lossClass==='sourceMapApproximation'){
+    return {id:'source-map-ranges',task:'Attach precise source-map ranges for approximated native mappings.',reason:'source-map-approximation',priority:'normal',evidenceKeys:['source-map']};
+  }
+  if(lossClass==='sourcePreservation'||lossClass==='commentsTrivia'){
+    return {id:'source-preservation',task:'Attach exact source-preservation evidence for lossy or missing source text.',reason:'source-preservation-loss',priority:'high',evidenceKeys:['source-preservation']};
+  }
+  if(lossClass==='parserDiagnostics'||lossClass==='unsupportedSyntax'){
+    return {id:'parser-evidence',task:'Resolve parser diagnostics or attach exact parser evidence.',reason:'parser-loss',priority:'blocker',evidenceKeys:['parser-result']};
+  }
+  if(lossClass==='unsupportedSyntax'||lossClass==='unsupportedSemantic'){
+    return {id:'unsupported-language-feature',task:'Add host semantic evidence for unsupported native language features.',reason:'unsupported-feature-loss',priority:'high',evidenceKeys:['host-semantics']};
+  }
+  if(lossClass==='targetProjectionLoss'||lossClass==='missingAdapter'||lossClass==='unsupportedTargetFeatures'||lossClass==='nativeSourceStubs'){
+    return {id:'target-projection-coverage',task:'Add target projection adapter coverage or mark unsupported target features.',reason:'target-projection-loss',priority:'high',evidenceKeys:['target-projection']};
+  }
+  if(lossClass==='macroExpansion'||lossClass==='preprocessor'||lossClass==='conditionalCompilation'||lossClass==='metaprogramming'||lossClass==='overloadTypeInference'||lossClass==='generatedCode'){
+    return {id:`host-evidence:${lossClass}`,task:`Attach host ${lossClass} evidence for native import losses.`,reason:'host-evidence-loss',priority:'high',evidenceKeys:[lossClass]};
+  }
+  return {id:`loss-class:${lossClass}`,task:`Review ${lossClass} native import loss evidence.`,reason:'native-loss-class',priority:'normal',evidenceKeys:[lossClass]};
+}
+
+function evidenceHint(input){
+  return {
+    evidenceKey:input.evidenceKey,
+    task:input.task,
+    count:1,
+    sourcePaths:uniqueStrings([input.sourcePath].filter(Boolean)),
+    languages:uniqueStrings([input.language].filter(Boolean)),
+    lossIds:uniqueStrings([input.lossId].filter(Boolean)),
+    lossKinds:uniqueStrings([input.lossKind].filter(Boolean)),
+    lossClasses:uniqueStrings([input.lossClass].filter(Boolean)),
+    readiness:input.readiness??'needs-review'
+  };
+}
+
+function taskHint(input){
+  return {
+    id:input.id,
+    task:input.task,
+    reason:input.reason,
+    priority:input.priority??'normal',
+    readiness:input.readiness??'needs-review',
+    count:1,
+    sourcePaths:uniqueStrings([input.sourcePath].filter(Boolean)),
+    languages:uniqueStrings([input.language].filter(Boolean)),
+    lossClasses:uniqueStrings(input.lossClasses??[]),
+    evidenceKeys:uniqueStrings(input.evidenceKeys??[])
+  };
+}
+
+function uniqueEvidenceHints(hints){
+  const grouped=new Map();
+  for(const hint of hints){
+    const key=`${hint.evidenceKey}\u0000${hint.lossIds.join('|')}\u0000${hint.sourcePaths.join('|')}`;
+    if(!grouped.has(key)) grouped.set(key,hint);
+  }
+  return [...grouped.values()];
+}
+
+function uniqueTaskHints(tasks){
+  const grouped=new Map();
+  for(const task of tasks){
+    const key=task.id??task.task;
+    if(!grouped.has(key)){
+      grouped.set(key,{...task});
+      continue;
+    }
+    const entry=grouped.get(key);
+    entry.count+=task.count??1;
+    entry.priority=maxTaskPriority(entry.priority,task.priority);
+    entry.readiness=maxSemanticMergeReadiness(entry.readiness,task.readiness);
+    entry.sourcePaths=uniqueStrings([...entry.sourcePaths,...task.sourcePaths]);
+    entry.languages=uniqueStrings([...entry.languages,...task.languages]);
+    entry.lossClasses=uniqueStrings([...entry.lossClasses,...task.lossClasses]);
+    entry.evidenceKeys=uniqueStrings([...entry.evidenceKeys,...task.evidenceKeys]);
+  }
+  return [...grouped.values()].sort((left,right)=>
+    taskPriorityRank[right.priority]-taskPriorityRank[left.priority]
+    || readinessSort(right.readiness)-readinessSort(left.readiness)
+    || String(left.task).localeCompare(String(right.task))
+  );
+}
+
+export function sourceSemanticMergeScore(input){
+  const readinessScore=sourceScoreByReadiness[input.readiness]??sourceScoreByReadiness['needs-review'];
+  const preservationPenalty=input.sourcePreservation.quality==='stale'?35
+    :input.sourcePreservation.quality==='missing'?26
+      :input.sourcePreservation.quality==='lossy'?12
+        :input.sourcePreservation.quality==='empty'?18
+          :0;
+  const risk=(input.candidates??[]).reduce((current,candidate)=>maxRisk(current,candidateRisk(candidate)),'low');
+  const riskPenalty=risk==='high'?24:risk==='medium'?10:risk==='unknown'?8:0;
+  const parserPenalty=input.parserEvidence.missing?25:Math.min(16,(input.parserEvidence.diagnosticCount??0)*4);
+  const missingEvidencePenalty=Math.min(24,(input.missingEvidence?.length??0)*6);
+  const semanticBonus=input.emptySemanticEvidence?-25:5;
+  return clampScore(readinessScore+semanticBonus-preservationPenalty-riskPenalty-parserPenalty-missingEvidencePenalty);
+}

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

@@ -0,0 +1,151 @@
+import{hashSemanticValue}from'@shapeshift-labs/frontier-lang-kernel';
+import{idFragment,normalizeSemanticMergeReadiness,uniqueStrings as uniqueRawStrings}from'../../native-import-utils.js';
+
+export function normalizeSources(input,imported){
+  const entries=[...(array(input.sources)),...(array(input.sourceRefs)),...(array(input.source)),...(array(imported))];
+  if(entries.length===0&&(input.sourcePath||input.sourceHash||input.baseHash||input.targetHash||input.sourceId||input.importId)){
+    entries.push(input);
+  }
+  return entries.map((source,index)=>compactRecord({
+    id:source?.id??source?.sourceId,
+    importId:source?.importId??source?.importResultId??(source?.kind==='frontier.lang.importResult'?source.id:undefined),
+    language:source?.language??input.language,
+    sourcePath:source?.sourcePath??source?.path??input.sourcePath,
+    sourceHash:source?.sourceHash??source?.hash,
+    baseHash:source?.baseHash??source?.beforeHash??input.baseHash??input.beforeHash,
+    targetHash:source?.targetHash??source?.afterHash??input.targetHash??input.afterHash,
+    metadata:source?.metadata,
+    ordinal:index
+  })).filter((source)=>source.id||source.importId||source.sourcePath||source.sourceHash||source.baseHash||source.targetHash);
+}
+
+export function normalizeOwnershipRegions(regions){
+  const seen=new Set();
+  const normalized=[];
+  for(const region of regions){
+    const key=firstString(region?.key,region?.ownershipKey,region?.conflictKey,region?.id);
+    if(!key||seen.has(key))continue;
+    seen.add(key);
+    normalized.push(compactRecord({
+      id:region?.id,
+      key,
+      regionKind:region?.regionKind??region?.ownershipRegionKind,
+      granularity:region?.granularity??'semantic',
+      language:region?.language,
+      sourcePath:region?.sourcePath,
+      sourceHash:region?.sourceHash,
+      symbolId:region?.symbolId,
+      symbolName:region?.symbolName??region?.name,
+      sourceSpan:region?.sourceSpan??region?.span,
+      metadata:region?.metadata
+    }));
+  }
+  return normalized;
+}
+
+export function normalizeSemanticCandidates(candidates){
+  return candidates.filter(Boolean).map((candidate,index)=>compactRecord({
+    id:candidate.id??candidate.candidateId??`semantic_candidate_${index+1}`,
+    importResultId:candidate.importResultId,
+    patchId:candidate.patchId,
+    sourcePath:candidate.sourcePath,
+    baseHash:candidate.baseHash,
+    targetHash:candidate.targetHash,
+    readiness:normalizeSemanticMergeReadiness(candidate.readiness)??candidate.readiness,
+    conflictKeys:uniqueStrings([...(strings(candidate.conflictKeys)),...(array(candidate.touchedSymbols)).map((entry)=>entry?.conflictKey),...(array(candidate.touchedSemanticNodes)).map((entry)=>entry?.conflictKey),...(array(candidate.nativeSpans)).map((entry)=>entry?.conflictKey),...(array(candidate.conflictClasses??candidate.metadata?.conflictClasses)).flatMap((entry)=>entry?.conflictKeys??[]),...(candidate.conflictSummary?.conflictKeys??candidate.metadata?.conflictSummary?.conflictKeys??[])]),
+    ownershipKeys:uniqueStrings([...(strings(candidate.ownershipKeys)),...(strings(candidate.regionKeys))]),
+    evidenceIds:uniqueStrings([...(strings(candidate.evidenceIds)),...(array(candidate.evidence)).map((record)=>record?.id),...(array(candidate.conflictClasses??candidate.metadata?.conflictClasses)).flatMap((entry)=>entry?.evidenceIds??[])]),
+    proofIds:uniqueStrings([...(strings(candidate.proofIds)),...(array(candidate.evidence)).filter((record)=>record?.kind==='proof').map((record)=>record?.id)]),
+    replayIds:uniqueStrings([...(strings(candidate.replayIds)),...(array(candidate.evidence)).filter((record)=>record?.kind==='replay').map((record)=>record?.id)]),
+    metadata:compactRecord({risk:candidate.risk,reasons:candidate.reasons,...candidate.metadata})
+  }));
+}
+
+export function normalizeSemanticClaims(claims,defaults){
+  return claims.filter(Boolean).map((claim,index)=>{
+    const text=typeof claim==='string'?claim:undefined;
+    const source=typeof claim==='string'?{}:claim;
+    const record=compactRecord({
+      kind:'frontier.lang.semanticHistoryClaim',
+      version:1,
+      claimKind:source.claimKind??source.semanticClaimKind??source.kind??defaults.claimKind,
+      status:source.status??defaults.status,
+      subject:firstString(source.subject,source.symbolId,source.semanticNodeId,source.conflictKey,source.key,text),
+      predicate:source.predicate??source.relation,
+      object:source.object??source.value??source.expected,
+      text,
+      language:source.language??defaults.language,
+      sourcePath:source.sourcePath??defaults.sourcePath,
+      sourceHash:source.sourceHash??defaults.sourceHash,
+      baseHash:source.baseHash??defaults.baseHash,
+      targetHash:source.targetHash??defaults.targetHash,
+      conflictKeys:uniqueStrings([...(strings(source.conflictKeys)),source.conflictKey,source.key]),
+      evidenceIds:uniqueStrings(source.evidenceIds),
+      proofIds:uniqueStrings(source.proofIds),
+      replayIds:uniqueStrings(source.replayIds),
+      actor:normalizeActor(source.actor)??defaults.actor,
+      recordSource:normalizeRecordSource(source.recordSource??source.historySource??defaults.recordSource,defaults),
+      metadata:source.metadata
+    });
+    return withStableSubrecordIdentity(defaults.prefix??'semantic_claim',record,source,index);
+  });
+}
+
+export function semanticClaimsByStatus(input,status){
+  return [...array(input.semanticClaims),...array(input.claims)].filter((claim)=>{
+    const claimStatus=String(claim?.status??'').toLowerCase();
+    if(claimStatus===status)return true;
+    if(status==='accepted'&&claim?.accepted===true)return true;
+    if(status==='rejected'&&(claim?.rejected===true||claim?.status===false))return true;
+    return false;
+  });
+}
+function withStableSubrecordIdentity(prefix,record,source,index){
+  const hash=source.hash??hashSemanticValue(record);
+  return{
+    ...record,
+    id:source.id??`${prefix}_${idFragment(firstString(record.subject,record.evidenceId,record.proofId,record.patchId,record.decision,hash,index+1))}`,
+    hash
+  };
+}
+
+function normalizeActor(value){
+  const actor=typeof value==='string'?{id:value}:value;
+  const normalized=compactRecord({
+    id:actor?.id??actor?.actorId,
+    kind:actor?.kind??actor?.actorKind??actor?.type,
+    role:actor?.role,
+    displayName:actor?.displayName??actor?.name,
+    runId:actor?.runId,
+    lane:actor?.lane,
+    taskId:actor?.taskId,
+    metadata:actor?.metadata
+  });
+  return nonEmptyRecord(normalized);
+}
+
+function normalizeRecordSource(value,context={}){
+  const source=typeof value==='string'?{id:value}:value;
+  const normalized=compactRecord({
+    id:source?.id??source?.sourceId??context.recordSourceId??context.historySourceId,
+    sourceId:source?.sourceId??source?.id??context.recordSourceId??context.historySourceId,
+    sourceKind:source?.sourceKind??source?.kind??source?.type,
+    sourcePath:source?.sourcePath??source?.path,
+    sourceHash:source?.sourceHash??source?.hash,
+    href:source?.href??source?.url,
+    importId:source?.importId??context.importId??context.importResultId,
+    runId:source?.runId??context.runId,
+    jobId:source?.jobId??context.jobId,
+    lane:source?.lane??context.lane,
+    taskId:source?.taskId??context.taskId,
+    metadata:source?.metadata
+  });
+  return nonEmptyRecord(normalized);
+}
+
+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 uniqueStrings(values){return uniqueRawStrings((values??[]).filter((entry)=>entry!==undefined&&entry!==null&&String(entry)!==''));}
+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)));}
+function nonEmptyRecord(value){return Object.keys(value??{}).length?value:undefined;}