helixevo 0.8.1 → 0.9.0

package/dashboard/lib/proof.ts

@@ -10,6 +10,9 @@ import {
   loadResolvedTopologyReviewCandidates,
   loadResolvedOntologyExtensions,
   type PressureIntervention,
+  type PressureInterventionType,
+  type ProofSteeringInfluence,
+  type ProofSteeringTier,
   type ResolvedPressureSignal,
   type ResolvedPressureMotif,
   type ResolvedTransferEvent,
@@ -58,6 +61,8 @@ export interface ResolvedProofRecord {
   relatedMotifIds?: string[]
   relatedTransferEventIds?: string[]
   semanticConceptIds?: string[]
+  steeringRoutes?: PressureInterventionType[]
+  steeringConceptIds?: string[]
   recommendedAction?: string
 }
 
@@ -85,10 +90,43 @@ export interface ProofTargetBreakdown {
   insufficientEvidence: number
 }
 
+export interface ProofSteeringLaneSummary {
+  laneKey: string
+  laneKind: 'route' | 'semantic'
+  route?: PressureInterventionType
+  conceptId?: string
+  targetTypes: ProofTargetType[]
+  evidenceTier: ProofSteeringTier
+  score: number
+  summary: string
+  reasons: string[]
+  recordIds: string[]
+  trustedCount: number
+  cautionCount: number
+  boundedCount: number
+  candidateCount: number
+}
+
+export interface ProofSteeringSummary {
+  trustedLanes: number
+  cautionLanes: number
+  boundedLanes: number
+  candidateLanes: number
+  priorityReview: number
+  routeLanes: ProofSteeringLaneSummary[]
+  semanticLanes: ProofSteeringLaneSummary[]
+  byRoute: Partial<Record<PressureInterventionType, ProofSteeringLaneSummary>>
+  byConceptId: Record<string, ProofSteeringLaneSummary>
+  highestPriority: ResolvedProofRecord[]
+  candidateEvidence: ResolvedProofRecord[]
+}
+
 export interface ProofDashboardSummary {
   summary: ProofSummary
+  steering: ProofSteeringSummary
   records: ResolvedProofRecord[]
   reviewQueue: ResolvedProofRecord[]
+  candidateQueue: ResolvedProofRecord[]
   recentVerified: ResolvedProofRecord[]
   recentContested: ResolvedProofRecord[]
   byTargetType: ProofTargetBreakdown[]
@@ -186,8 +224,8 @@ function latestReviewByRecord(): Map<string, ProofReviewRecord> {
 }
 
 function buildInterventionProofRecords(): ResolvedProofRecord[] {
-  const signals = loadResolvedPressureSignals()
-  const motifs = loadPressureMotifs()
+  const signals = loadResolvedPressureSignals({ includeProofSteering: false })
+  const motifs = loadPressureMotifs({ includeProofSteering: false })
 
   return loadPressureInterventions().map((intervention) => {
     const linkedSignals = signals.filter((signal) =>
@@ -236,6 +274,7 @@ function buildInterventionProofRecords(): ResolvedProofRecord[] {
         linkedSignals: linkedSignals.length,
         linkedMotifs: linkedMotifs.length,
         addressed: lifecycleItems.filter((item) => item.lifecycle === 'addressed').length,
+        dryRun: intervention.status === 'dry-run' ? 1 : 0,
       },
       relatedProjectIds: uniqueStrings([intervention.projectId, ...linkedSignals.map((signal) => signal.projectId), ...linkedMotifs.flatMap((motif) => motif.projectIds)]),
       relatedSignalIds: linkedSignals.map((signal) => signal.id),
@@ -245,6 +284,7 @@ function buildInterventionProofRecords(): ResolvedProofRecord[] {
         ...linkedSignals.flatMap((signal) => signal.semanticConceptIds ?? []),
         ...linkedMotifs.flatMap((motif) => motif.semanticConceptIds ?? []),
       ]),
+      steeringRoutes: [intervention.interventionType],
       recommendedAction: outcomeState === 'effective'
         ? 'Verify if this resolving pattern should remain a trusted lane.'
         : outcomeState === 'mixed'
@@ -259,8 +299,8 @@ function buildInterventionProofRecords(): ResolvedProofRecord[] {
 }
 
 function buildTransferProofRecords(): ResolvedProofRecord[] {
-  const motifs = loadPressureMotifs()
-  const signals = loadResolvedPressureSignals()
+  const motifs = loadPressureMotifs({ includeProofSteering: false })
+  const signals = loadResolvedPressureSignals({ includeProofSteering: false })
 
   return loadTransferEvents()
     .filter((event) => event.status === 'realized')
@@ -306,6 +346,7 @@ function buildTransferProofRecords(): ResolvedProofRecord[] {
           ...linkedSignals.flatMap((signal) => signal.semanticConceptIds ?? []),
           ...linkedMotifs.flatMap((motif) => motif.semanticConceptIds ?? []),
         ]),
+        steeringRoutes: ['generalize'],
         recommendedAction: outcomeState === 'effective'
           ? 'Verify whether this transfer pattern should be treated as proven reusable evidence.'
           : outcomeState === 'mixed'
@@ -319,8 +360,8 @@ function buildTransferProofRecords(): ResolvedProofRecord[] {
 
 function buildTopologyProofRecords(): ResolvedProofRecord[] {
   const candidatesById = new Map(loadResolvedTopologyReviewCandidates().map((candidate) => [candidate.id, candidate]))
-  const signals = loadResolvedPressureSignals()
-  const motifs = loadPressureMotifs()
+  const signals = loadResolvedPressureSignals({ includeProofSteering: false })
+  const motifs = loadPressureMotifs({ includeProofSteering: false })
 
   return loadResolvedTopologyApplyPlans().map((plan) => {
     const candidate = candidatesById.get(plan.candidateId)
@@ -372,6 +413,7 @@ function buildTopologyProofRecords(): ResolvedProofRecord[] {
         ...linkedSignals.flatMap((signal) => signal.semanticConceptIds ?? []),
         ...linkedMotifs.flatMap((motif) => motif.semanticConceptIds ?? []),
       ]),
+      steeringRoutes: ['manual-review'],
       recommendedAction: outcomeState === 'effective'
         ? 'Verify this topology change if the structural relief looks durable.'
         : outcomeState === 'mixed'
@@ -386,12 +428,12 @@ function buildTopologyProofRecords(): ResolvedProofRecord[] {
 }
 
 function buildOntologyProofRecords(): ResolvedProofRecord[] {
-  const signals = loadResolvedPressureSignals()
-  const motifs = loadPressureMotifs()
+  const signals = loadResolvedPressureSignals({ includeProofSteering: false })
+  const motifs = loadPressureMotifs({ includeProofSteering: false })
   const transfers = loadTransferEvents()
   const topologyCandidates = loadResolvedTopologyReviewCandidates()
 
-  return loadResolvedOntologyExtensions()
+  return loadResolvedOntologyExtensions({ includeProofSteering: false })
     .filter((concept) => concept.status === 'active')
     .map((concept) => {
       const boundSignals = signals.filter((signal) => signal.semanticConceptIds?.includes(concept.id))
@@ -437,6 +479,7 @@ function buildOntologyProofRecords(): ResolvedProofRecord[] {
         relatedMotifIds: boundMotifs.map((motif) => motif.id),
         relatedTransferEventIds: boundTransfers.map((event) => event.id),
         semanticConceptIds: [concept.id],
+        steeringConceptIds: [concept.id],
         recommendedAction: outcomeState === 'effective'
           ? 'Verify this concept if semantic adoption looks stable enough to trust.'
           : outcomeState === 'mixed'
@@ -490,6 +533,7 @@ function buildEvolutionProofRecords(): ResolvedProofRecord[] {
         samplesBefore: impact.samplesBefore,
         samplesAfter: impact.samplesAfter,
       },
+      steeringRoutes: ['evolve'],
       recommendedAction: outcomeState === 'effective'
         ? 'Verify this evolution result if the lower correction rate looks durable.'
         : outcomeState === 'regressed'
@@ -501,6 +545,216 @@ function buildEvolutionProofRecords(): ResolvedProofRecord[] {
   })
 }
 
+
+function routeLabel(route: PressureInterventionType): string {
+  return route.replace(/-/g, ' ')
+}
+
+function steeringMetaForRecord(record: ResolvedProofRecord): { tier: ProofSteeringTier; score: number; summary: string } {
+  const dryRun = record.metrics?.dryRun === 1
+  if (dryRun) {
+    return {
+      tier: 'candidate',
+      score: 0,
+      summary: 'Dry-run proof remains candidate-only evidence until live downstream effects exist.',
+    }
+  }
+  if (record.reviewStatus === 'contested' && record.outcomeState === 'regressed') {
+    return {
+      tier: 'caution',
+      score: -4,
+      summary: 'Contested regressed proof strongly increases caution and review bias on this lane.',
+    }
+  }
+  if (record.reviewStatus === 'verified' && record.outcomeState === 'regressed') {
+    return {
+      tier: 'caution',
+      score: -4,
+      summary: 'Verified regressed proof strongly increases caution on this lane.',
+    }
+  }
+  if (record.reviewStatus === 'contested') {
+    return {
+      tier: 'caution',
+      score: -3,
+      summary: 'Contested proof should bias the system toward caution and re-review.',
+    }
+  }
+  if (record.outcomeState === 'regressed') {
+    return {
+      tier: 'caution',
+      score: -3,
+      summary: 'Regressed proof should make this lane less trusted until it is re-evaluated.',
+    }
+  }
+  if (record.reviewStatus === 'verified' && record.outcomeState === 'effective') {
+    return {
+      tier: 'trusted',
+      score: 4,
+      summary: 'Verified effective proof can strengthen trust in this lane.',
+    }
+  }
+  if (record.reviewStatus === 'verified' && record.outcomeState === 'mixed') {
+    return {
+      tier: 'bounded',
+      score: 1,
+      summary: 'Verified mixed proof adds signal, but still keeps steering bounded.',
+    }
+  }
+  if (record.outcomeState === 'effective') {
+    return {
+      tier: 'bounded',
+      score: 1,
+      summary: 'Effective evidence exists, but remains bounded until review strengthens trust.',
+    }
+  }
+  if (record.reviewStatus === 'deferred' || record.outcomeState === 'mixed' || record.outcomeState === 'measuring') {
+    return {
+      tier: 'bounded',
+      score: 0,
+      summary: 'This proof remains bounded and should guide review more than lane trust.',
+    }
+  }
+  return {
+    tier: 'candidate',
+    score: 0,
+    summary: 'Insufficient-evidence proof stays candidate-only until stronger downstream evidence appears.',
+  }
+}
+
+type MutableProofLane = {
+  laneKey: string
+  laneKind: 'route' | 'semantic'
+  route?: PressureInterventionType
+  conceptId?: string
+  targetTypes: Set<ProofTargetType>
+  recordIds: string[]
+  reasons: string[]
+  summaries: string[]
+  score: number
+  trustedCount: number
+  cautionCount: number
+  boundedCount: number
+  candidateCount: number
+}
+
+function laneTierWeight(tier: ProofSteeringTier): number {
+  return tier === 'caution' ? 4 : tier === 'trusted' ? 3 : tier === 'bounded' ? 2 : 1
+}
+
+function finalizeProofLane(lane: MutableProofLane): ProofSteeringLaneSummary {
+  const evidenceTier: ProofSteeringTier = lane.cautionCount > 0 && lane.score <= -2
+    ? 'caution'
+    : lane.trustedCount > 0 && lane.score >= 3
+      ? 'trusted'
+      : lane.candidateCount > 0 && lane.trustedCount === 0 && lane.cautionCount === 0 && lane.boundedCount === 0
+        ? 'candidate'
+        : 'bounded'
+  const label = lane.route ? routeLabel(lane.route) : lane.conceptId ?? lane.laneKey
+  const summary = evidenceTier === 'caution'
+    ? `${label} now carries regressed or contested proof and should be treated more cautiously.`
+    : evidenceTier === 'trusted'
+      ? `${label} now carries verified/effective proof that can strengthen trust modestly.`
+      : evidenceTier === 'candidate'
+        ? `${label} currently has only dry-run or insufficient evidence and should stay bounded.`
+        : `${label} has some proof history, but steering should remain bounded.`
+  return {
+    laneKey: lane.laneKey,
+    laneKind: lane.laneKind,
+    route: lane.route,
+    conceptId: lane.conceptId,
+    targetTypes: [...lane.targetTypes.values()].sort(),
+    evidenceTier,
+    score: lane.score,
+    summary,
+    reasons: [...new Set([...lane.summaries, ...lane.reasons])].slice(0, 4),
+    recordIds: lane.recordIds,
+    trustedCount: lane.trustedCount,
+    cautionCount: lane.cautionCount,
+    boundedCount: lane.boundedCount,
+    candidateCount: lane.candidateCount,
+  }
+}
+
+export function loadProofSteeringSummary(records = loadResolvedProofRecords()): ProofSteeringSummary {
+  const routeMap = new Map<string, MutableProofLane>()
+  const conceptMap = new Map<string, MutableProofLane>()
+  const openRecords = records.filter((record) => record.reviewStatus === 'open')
+  const priorityReview = openRecords.filter((record) => steeringMetaForRecord(record).tier !== 'candidate')
+  const candidateEvidence = openRecords.filter((record) => steeringMetaForRecord(record).tier === 'candidate')
+
+  function applyToLane(lane: MutableProofLane, record: ResolvedProofRecord) {
+    const meta = steeringMetaForRecord(record)
+    lane.targetTypes.add(record.targetType)
+    lane.recordIds.push(record.id)
+    lane.score += meta.score
+    lane.reasons.push(...record.reasons.slice(0, 2))
+    lane.summaries.push(meta.summary)
+    if (meta.tier === 'trusted') lane.trustedCount += 1
+    else if (meta.tier === 'caution') lane.cautionCount += 1
+    else if (meta.tier === 'bounded') lane.boundedCount += 1
+    else lane.candidateCount += 1
+  }
+
+  for (const record of records) {
+    for (const route of record.steeringRoutes ?? []) {
+      const laneKey = `route:${route}`
+      const lane = routeMap.get(laneKey) ?? {
+        laneKey,
+        laneKind: 'route',
+        route,
+        targetTypes: new Set<ProofTargetType>(),
+        recordIds: [],
+        reasons: [],
+        summaries: [],
+        score: 0,
+        trustedCount: 0,
+        cautionCount: 0,
+        boundedCount: 0,
+        candidateCount: 0,
+      }
+      applyToLane(lane, record)
+      routeMap.set(laneKey, lane)
+    }
+    for (const conceptId of record.steeringConceptIds ?? []) {
+      const laneKey = `semantic:${conceptId}`
+      const lane = conceptMap.get(laneKey) ?? {
+        laneKey,
+        laneKind: 'semantic',
+        conceptId,
+        targetTypes: new Set<ProofTargetType>(),
+        recordIds: [],
+        reasons: [],
+        summaries: [],
+        score: 0,
+        trustedCount: 0,
+        cautionCount: 0,
+        boundedCount: 0,
+        candidateCount: 0,
+      }
+      applyToLane(lane, record)
+      conceptMap.set(laneKey, lane)
+    }
+  }
+
+  const routeLanes = [...routeMap.values()].map(finalizeProofLane).sort((a, b) => laneTierWeight(b.evidenceTier) - laneTierWeight(a.evidenceTier) || Math.abs(b.score) - Math.abs(a.score) || a.laneKey.localeCompare(b.laneKey))
+  const semanticLanes = [...conceptMap.values()].map(finalizeProofLane).sort((a, b) => laneTierWeight(b.evidenceTier) - laneTierWeight(a.evidenceTier) || Math.abs(b.score) - Math.abs(a.score) || a.laneKey.localeCompare(b.laneKey))
+
+  return {
+    trustedLanes: [...routeLanes, ...semanticLanes].filter((lane) => lane.evidenceTier === 'trusted').length,
+    cautionLanes: [...routeLanes, ...semanticLanes].filter((lane) => lane.evidenceTier === 'caution').length,
+    boundedLanes: [...routeLanes, ...semanticLanes].filter((lane) => lane.evidenceTier === 'bounded').length,
+    candidateLanes: [...routeLanes, ...semanticLanes].filter((lane) => lane.evidenceTier === 'candidate').length,
+    priorityReview: priorityReview.length,
+    routeLanes,
+    semanticLanes,
+    byRoute: Object.fromEntries(routeLanes.filter((lane) => lane.route).map((lane) => [lane.route!, lane])) as Partial<Record<PressureInterventionType, ProofSteeringLaneSummary>>,
+    byConceptId: Object.fromEntries(semanticLanes.filter((lane) => lane.conceptId).map((lane) => [lane.conceptId!, lane])),
+    highestPriority: priorityReview.slice(0, 8),
+    candidateEvidence: candidateEvidence.slice(0, 8),
+  }
+}
+
 export function loadResolvedProofRecords(): ResolvedProofRecord[] {
   const latestReviews = latestReviewByRecord()
   const records = [
@@ -566,10 +820,13 @@ function buildTargetBreakdown(records: ResolvedProofRecord[]): ProofTargetBreakd
 
 export function loadProofDashboardSummary(): ProofDashboardSummary {
   const records = loadResolvedProofRecords()
+  const steering = loadProofSteeringSummary(records)
   return {
     summary: getProofSummary(records),
+    steering,
     records,
-    reviewQueue: records.filter((record) => record.reviewStatus === 'open').slice(0, 12),
+    reviewQueue: steering.highestPriority,
+    candidateQueue: steering.candidateEvidence,
     recentVerified: records.filter((record) => record.reviewStatus === 'verified').slice(0, 8),
     recentContested: records.filter((record) => record.reviewStatus === 'contested').slice(0, 8),
     byTargetType: buildTargetBreakdown(records),