@cyber-dash-tech/revela 0.12.0 → 0.14.0

package/lib/inspect/prompt.ts

@@ -4,23 +4,31 @@ export function buildInspectionPrompt(input: {
   requestId: string
   file: string
   projection: InspectionPromptProjection
+  language?: string
 }): string {
+  const language = normalizeInspectLanguage(input.language)
   return `A user selected slide content in Revela Evidence Inspector. The selection may contain one referenced element, a whole slide, or multiple referenced elements selected with Cmd/Ctrl-click.
 
 Target file: ${input.file}
 Inspection request id: ${input.requestId}
+Display language: ${language}
 
-Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries: answer the selected object's purpose and source credibility only. Do not edit files. Do not mutate DECKS.json. Do not invent sources, quotes, URLs, page references, caveats, or evidence not present in the projection.
+Use the structured projection below to produce the final inspector cards. This is LLM judgment with grounded boundaries: explain the selected object's narrative reading context, bounded exploratory reading context, purpose, and source credibility only. Do not edit files. Do not mutate DECKS.json. Do not invent claim ids, evidence binding ids, sources, quotes, URLs, page references, caveats, objections, risks, artifact coverage, or evidence not present in the projection.
+
+Language boundary: the selected display language affects only human-readable card copy. Preserve all claim ids, canonical claim ids, evidence binding ids, source paths, findings files, URLs, numbers, quoted/source facts, caveats, artifact ids, and coverage statuses exactly as grounded in the projection. If the display language is Auto, use projection.deck.language when available; otherwise follow the user's/browser context or default to English.
 
 Return the result only by calling the \`revela-inspection-result\` tool with this request id. Do not answer in chat.
 
 Required card model:
+- Narrative Reading: when the projection includes a matched claim, preserve its claim id, canonical claim id, evidence binding ids, supported scope, unsupported scope, caveats, related objections, related risks, and artifact coverage. Artifact coverage must come only from projection.cards.artifacts; do not invent where a claim appears or whether an artifact is stale/current/partial/missing. If canonical narrative linkage is missing, say so and fall back to the matched slide claim; do not invent canonical ids.
+- Candidate boundary: when projection.match.claim is absent but projection.match.candidateClaims is present, explain the selected child element only within those candidate claim boundaries. You may describe that the child element functions as a detail, prerequisite, source note, risk cue, or evidence cue inside the slide, but you must not select one candidate claim id by semantic guess. If projection.match.confidence is none or candidateClaims is empty, explain the mapping gap instead of inventing a plausible claim.
+- Exploratory Reading: provide bounded, non-official reading cues for objection prep, audience reframing, appendix leads, and meeting prep only from the projection. Mark official as false. Keep missing evidence, caveats, unsupported scope, and stale artifacts visible. Do not make exploratory text sound like approved artifact content, and do not turn this into chat or a fix plan.
 - Purpose: explain why this selected content appears here, what job it serves in the slide purpose, narrative role, deck goal, audience, or narrative brief, and why it matters.
 - Source: if the selection contains a factual claim, number, comparison, conclusion, or recommendation, judge source credibility. Use not_needed for structural, transitional, or purely explanatory content that does not need evidence. Include source trace, warnings, gaps, and caveats here.
 
 Boundaries:
 - Do not hunt for problems. If it works, say it works.
-- Do not recommend edits or fixes; this inspector view only explains purpose and source credibility.
+- Do not recommend edits or fixes; this inspector view only explains narrative context, bounded exploratory reading context, purpose, and source credibility.
 - Do not turn every caveat into a problem.
 - If confidence is low, use unclear or unknown instead of pretending certainty.
 
@@ -30,3 +38,8 @@ Projection JSON:
 ${JSON.stringify(input.projection, null, 2)}
 \`\`\``
 }
+
+function normalizeInspectLanguage(language: string | undefined): string {
+  const value = typeof language === "string" ? language.trim() : ""
+  return value || "Auto"
+}

package/lib/inspect/requests.ts

@@ -1,5 +1,5 @@
 import type { InspectionPromptProjection } from "../inspection-context/project"
-import type { InspectionResult } from "../inspection-context/result"
+import { buildDeterministicInspectionResult, type InspectionResult } from "../inspection-context/result"
 
 export type InspectRequestStatus = "pending" | "completed" | "failed" | "expired"
 
@@ -53,11 +53,30 @@ export function completeInspectRequest(requestId: string, result: InspectionResu
   if (!request) throw new Error(`Unknown inspection request: ${requestId}`)
   if (request.status !== "pending") throw new Error(`Inspection request is not pending: ${request.status}`)
   request.status = "completed"
-  request.result = { ...result, requestId }
+  request.result = normalizeInspectionResult(request.projection, result, requestId)
   request.updatedAt = Date.now()
   return request
 }
 
+function normalizeInspectionResult(
+  projection: InspectionPromptProjection,
+  result: InspectionResult,
+  requestId: string,
+): InspectionResult {
+  const deterministic = buildDeterministicInspectionResult(projection, { requestId })
+  return {
+    ...result,
+    requestId,
+    cards: {
+      reading: result.cards.reading ?? deterministic.cards.reading,
+      exploratory: result.cards.exploratory ?? deterministic.cards.exploratory,
+      purpose: result.cards.purpose,
+      source: result.cards.source,
+    },
+    stale: result.stale ?? deterministic.stale,
+  }
+}
+
 export function failInspectRequest(requestId: string, error: string): PendingInspectRequest | undefined {
   const request = getInspectRequest(requestId)
   if (!request || request.status !== "pending") return request

package/lib/inspection-context/compile.ts

@@ -1,6 +1,8 @@
 import type { DeckSpec, DecksState, EvidenceRef, NarrativeBrief, NarrativeRole, SlideSpec, SourceMaterial } from "../decks-state"
+import { getArtifactClaimRefs, type ArtifactClaimRef, type ClaimSlideRef } from "../narrative-state/queries"
+import type { NarrativeClaim, NarrativeEvidenceBinding, NarrativeStateV1 } from "../narrative-state/types"
 
-export type InspectionClaimOrigin = "title" | "headline" | "body" | "bullet" | "purpose"
+export type InspectionClaimOrigin = "narrative" | "title" | "headline" | "body" | "bullet" | "purpose"
 export type InspectionGapType = "missing_evidence" | "weak_evidence"
 export type InspectionEvidenceSupport = "supported" | "weak" | "unknown"
 
@@ -13,11 +15,19 @@ export interface InspectionContext {
   outputPath: string
   narrativeBrief?: NarrativeBrief
   sourceMaterials: InspectionSourceMaterial[]
+  narrative?: InspectionNarrativeStateContext
   slides: InspectionSlideContext[]
   gaps: InspectionGap[]
   appendixCandidates: InspectionAppendixCandidate[]
   objectionContext: InspectionNarrativeContext[]
   riskContext: InspectionNarrativeContext[]
+  artifactCoverage: InspectionArtifactCoverage[]
+}
+
+export interface InspectionNarrativeStateContext {
+  id: string
+  status: string
+  claimCount: number
 }
 
 export interface InspectionSourceMaterial extends SourceMaterial {
@@ -46,6 +56,7 @@ export interface InspectionSlideText {
 
 export interface InspectionClaimCandidate {
   id: string
+  canonicalClaimId?: string
   slideIndex: number
   slideTitle: string
   origin: InspectionClaimOrigin
@@ -54,9 +65,18 @@ export interface InspectionClaimCandidate {
   evidenceSupport: InspectionEvidenceSupport
   evidence: InspectionEvidenceTrace[]
   gaps: InspectionGap[]
+  evidenceBindingIds: string[]
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats: string[]
 }
 
 export interface InspectionEvidenceTrace extends EvidenceRef {
+  evidenceBindingId?: string
+  claimId?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength?: NarrativeEvidenceBinding["strength"]
   slideIndex: number
   slideTitle: string
   hasDetail: boolean
@@ -80,19 +100,44 @@ export interface InspectionAppendixCandidate {
 
 export interface InspectionNarrativeContext {
   text: string
-  source: "narrativeBrief" | "slide"
+  source: "narrative" | "narrativeBrief" | "slide"
   slideIndex?: number
   slideTitle?: string
 }
 
+export interface InspectionArtifactCoverage {
+  artifactId: string
+  type: ArtifactClaimRef["type"]
+  outputPath?: string
+  coverageStatus: ArtifactClaimRef["coverageStatus"]
+  claimIds: string[]
+  affectedClaimIds: string[]
+  missingClaimIds: string[]
+  stale: boolean
+  staleReason?: string
+  staleReasons: string[]
+  note?: string
+  slideRefs: InspectionArtifactSlideRef[]
+}
+
+export interface InspectionArtifactSlideRef {
+  claimId: string
+  slideIndex: number
+  slideTitle: string
+  role: ClaimSlideRef["role"]
+  match: ClaimSlideRef["match"]
+  location: string
+}
+
 export function compileInspectionContext(state: DecksState, slug?: string): InspectionContext {
   const deck = activeDeck(state, slug)
+  const narrative = state.narrative
   const evidence = collectEvidence(deck)
   const sourceMaterials = compileSourceMaterials(state.workspace.sourceMaterials ?? [], evidence)
   const slides = deck.slides
     .slice()
     .sort((a, b) => a.index - b.index)
-    .map((slide) => compileSlide(slide))
+    .map((slide) => compileSlide(slide, narrative))
   const gaps = slides.flatMap((slide) => slide.claims.flatMap((claim) => claim.gaps))
 
   return {
@@ -103,24 +148,56 @@ export function compileInspectionContext(state: DecksState, slug?: string): Insp
     language: deck.language,
     outputPath: deck.outputPath,
     narrativeBrief: deck.narrativeBrief,
+    narrative: narrative ? { id: narrative.id, status: narrative.status, claimCount: narrative.claims.length } : undefined,
     sourceMaterials,
     slides,
     gaps,
     appendixCandidates: compileAppendixCandidates(slides),
-    objectionContext: compileNarrativeList(deck, "objections"),
-    riskContext: compileNarrativeList(deck, "risks"),
+    objectionContext: compileNarrativeList(deck, "objections", narrative),
+    riskContext: compileNarrativeList(deck, "risks", narrative),
+    artifactCoverage: compileArtifactCoverage(state),
   }
 }
 
+function compileArtifactCoverage(state: DecksState): InspectionArtifactCoverage[] {
+  return getArtifactClaimRefs(state).map((artifact) => ({
+    artifactId: artifact.artifactId,
+    type: artifact.type,
+    outputPath: artifact.outputPath,
+    coverageStatus: artifact.coverageStatus,
+    claimIds: artifact.claimIds,
+    affectedClaimIds: artifact.affectedClaimIds,
+    missingClaimIds: artifact.missingClaimIds,
+    stale: artifact.stale,
+    staleReason: artifact.staleReason,
+    staleReasons: artifact.staleReasons,
+    note: artifact.note,
+    slideRefs: artifact.slideRefs.map((ref) => ({
+      claimId: ref.claimId,
+      slideIndex: ref.slideIndex,
+      slideTitle: ref.slideTitle,
+      role: ref.role,
+      match: ref.match,
+      location: ref.location,
+    })),
+  }))
+}
+
 function activeDeck(state: DecksState, slug?: string): DeckSpec {
   const key = slug || state.activeDeck || (Object.keys(state.decks).length === 1 ? Object.keys(state.decks)[0] : undefined)
   if (!key || !state.decks[key]) throw new Error("No active deck is available for inspection context compilation.")
   return state.decks[key]
 }
 
-function compileSlide(slide: SlideSpec): InspectionSlideContext {
+function compileSlide(slide: SlideSpec, narrative: NarrativeStateV1 | undefined): InspectionSlideContext {
   const evidence = slide.evidence.map((item) => compileEvidence(slide, item))
-  const claims = claimCandidates(slide).map((claim, position) => compileClaim(slide, claim, position, evidence))
+  const canonicalClaims = narrative ? canonicalClaimCandidates(slide, narrative, evidence) : []
+  const canonicalText = new Set(canonicalClaims.map((claim) => normalizeText(claim.text)))
+  const heuristicClaims = claimCandidates(slide)
+    .filter((claim) => !canonicalText.has(normalizeText(claim.text)))
+    .map((claim, position) => compileClaim(slide, claim, position, evidence))
+  const claims = [...canonicalClaims, ...heuristicClaims]
+  const claimCaveats = canonicalClaims.flatMap((claim) => claim.caveats)
   return {
     index: slide.index,
     title: slide.title,
@@ -136,7 +213,61 @@ function compileSlide(slide: SlideSpec): InspectionSlideContext {
     },
     claims,
     evidence,
-    caveats: evidence.map((item) => item.caveat).filter((item): item is string => Boolean(item?.trim())),
+    caveats: dedupeText([
+      ...evidence.map((item) => item.caveat).filter((item): item is string => Boolean(item?.trim())),
+      ...claimCaveats,
+    ]),
+  }
+}
+
+function canonicalClaimCandidates(slide: SlideSpec, narrative: NarrativeStateV1, slideEvidence: InspectionEvidenceTrace[]): InspectionClaimCandidate[] {
+  const claimRefs = slide.claimRefs ?? []
+  const metadataClaimIds = new Set([
+    ...claimRefs.map((ref) => ref.claimId),
+    ...(slide.claimIds ?? []),
+  ].filter(Boolean))
+  const evidenceBindingIds = new Set(slide.evidenceBindingIds ?? [])
+  for (const binding of narrative.evidenceBindings) {
+    if (evidenceBindingIds.has(binding.id)) metadataClaimIds.add(binding.claimId)
+  }
+
+  return narrative.claims
+    .filter((claim) => metadataClaimIds.has(claim.id))
+    .map((claim) => compileCanonicalClaim(slide, claim, narrative.evidenceBindings, slideEvidence, evidenceBindingIds))
+}
+
+function compileCanonicalClaim(
+  slide: SlideSpec,
+  claim: NarrativeClaim,
+  bindings: NarrativeEvidenceBinding[],
+  slideEvidence: InspectionEvidenceTrace[],
+  slideEvidenceBindingIds: Set<string>,
+): InspectionClaimCandidate {
+  const allClaimBindings = bindings.filter((binding) => binding.claimId === claim.id)
+  const selectedBindings = allClaimBindings.filter((binding) => slideEvidenceBindingIds.size === 0 || slideEvidenceBindingIds.has(binding.id))
+  const evidenceBindings = selectedBindings.length > 0 ? selectedBindings : allClaimBindings
+  const evidence = evidenceBindings.length > 0
+    ? evidenceBindings.map((binding) => compileEvidenceBinding(slide, binding))
+    : slideEvidence
+  const gaps = canonicalClaimGaps(slide, claim, evidence)
+  return {
+    id: claim.id,
+    canonicalClaimId: claim.id,
+    slideIndex: slide.index,
+    slideTitle: slide.title,
+    origin: "narrative",
+    text: claim.text,
+    evidenceSensitive: claim.evidenceRequired || isEvidenceSensitiveClaim(claim.text),
+    evidenceSupport: narrativeEvidenceSupport(claim, evidence),
+    evidence,
+    gaps,
+    evidenceBindingIds: evidenceBindings.map((binding) => binding.id),
+    supportedScope: claim.supportedScope,
+    unsupportedScope: claim.unsupportedScope,
+    caveats: dedupeText([
+      ...(claim.caveats ?? []),
+      ...evidenceBindings.map((binding) => binding.caveat).filter((item): item is string => Boolean(item?.trim())),
+    ]),
   }
 }
 
@@ -159,9 +290,36 @@ function compileClaim(
     evidenceSupport: evidenceSupport(evidence),
     evidence,
     gaps,
+    evidenceBindingIds: [],
+    caveats: [],
   }
 }
 
+function canonicalClaimGaps(slide: SlideSpec, claim: NarrativeClaim, evidence: InspectionEvidenceTrace[]): InspectionGap[] {
+  if (!claim.evidenceRequired) return []
+  if (claim.evidenceStatus === "missing" || evidence.length === 0) {
+    return [{
+      type: "missing_evidence",
+      slideIndex: slide.index,
+      slideTitle: slide.title,
+      claimId: claim.id,
+      claimText: claim.text,
+      message: "Canonical narrative claim requires evidence but has no bound evidence trace.",
+    }]
+  }
+  if (claim.evidenceStatus === "weak" || evidence.some((item) => !item.hasDetail)) {
+    return [{
+      type: "weak_evidence",
+      slideIndex: slide.index,
+      slideTitle: slide.title,
+      claimId: claim.id,
+      claimText: claim.text,
+      message: "Canonical narrative claim has weak or source-only evidence trace.",
+    }]
+  }
+  return []
+}
+
 function claimGaps(slide: SlideSpec, claimId: string, claimText: string, evidence: InspectionEvidenceTrace[]): InspectionGap[] {
   if (evidence.length === 0) {
     return [{
@@ -192,6 +350,12 @@ function evidenceSupport(evidence: InspectionEvidenceTrace[]): InspectionEvidenc
   return "supported"
 }
 
+function narrativeEvidenceSupport(claim: NarrativeClaim, evidence: InspectionEvidenceTrace[]): InspectionEvidenceSupport {
+  if (claim.evidenceStatus === "supported" || claim.evidenceStatus === "not_required") return "supported"
+  if (claim.evidenceStatus === "partial" || claim.evidenceStatus === "weak") return "weak"
+  return evidenceSupport(evidence)
+}
+
 function claimCandidates(slide: SlideSpec): Array<{ origin: InspectionClaimOrigin; text: string }> {
   const claims: Array<{ origin: InspectionClaimOrigin; text: string }> = []
   pushClaim(claims, "title", slide.title)
@@ -218,6 +382,29 @@ function compileEvidence(slide: SlideSpec, evidence: EvidenceRef): InspectionEvi
   }
 }
 
+function compileEvidenceBinding(slide: SlideSpec, binding: NarrativeEvidenceBinding): InspectionEvidenceTrace {
+  const evidence: EvidenceRef = {
+    source: binding.source,
+    sourcePath: binding.sourcePath,
+    findingsFile: binding.findingsFile,
+    quote: binding.quote,
+    location: binding.location,
+    url: binding.url,
+    caveat: binding.caveat,
+  }
+  return {
+    ...evidence,
+    evidenceBindingId: binding.id,
+    claimId: binding.claimId,
+    supportScope: binding.supportScope,
+    unsupportedScope: binding.unsupportedScope,
+    strength: binding.strength,
+    slideIndex: slide.index,
+    slideTitle: slide.title,
+    hasDetail: hasEvidenceDetail(evidence),
+  }
+}
+
 function collectEvidence(deck: DeckSpec): InspectionEvidenceTrace[] {
   return deck.slides.flatMap((slide) => slide.evidence.map((item) => compileEvidence(slide, item)))
 }
@@ -253,7 +440,10 @@ function appendixReason(slide: InspectionSlideContext): string {
   return "Slide has recorded evidence that may be useful for source excerpts or backup detail."
 }
 
-function compileNarrativeList(deck: DeckSpec, key: "objections" | "risks"): InspectionNarrativeContext[] {
+function compileNarrativeList(deck: DeckSpec, key: "objections" | "risks", narrative: NarrativeStateV1 | undefined): InspectionNarrativeContext[] {
+  const fromNarrative = key === "objections"
+    ? (narrative?.objections ?? []).map((item) => ({ text: item.text, source: "narrative" as const }))
+    : (narrative?.risks ?? []).map((item) => ({ text: item.text, source: "narrative" as const }))
   const fromBrief = (deck.narrativeBrief?.[key] ?? []).map((text) => ({ text, source: "narrativeBrief" as const }))
   const role = key === "risks" ? "risk" : undefined
   const fromSlides = deck.slides
@@ -264,7 +454,19 @@ function compileNarrativeList(deck: DeckSpec, key: "objections" | "risks"): Insp
       slideIndex: slide.index,
       slideTitle: slide.title,
     })))
-  return [...fromBrief, ...fromSlides]
+  return dedupeNarrativeContext([...fromNarrative, ...fromBrief, ...fromSlides])
+}
+
+function dedupeNarrativeContext(values: InspectionNarrativeContext[]): InspectionNarrativeContext[] {
+  const seen = new Set<string>()
+  const result: InspectionNarrativeContext[] = []
+  for (const value of values) {
+    const key = `${normalizeText(value.text)}:${value.slideIndex ?? "global"}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(value)
+  }
+  return result
 }
 
 function slideTextList(slide: SlideSpec): string[] {
@@ -303,6 +505,24 @@ function cleanOptionalText(value: string | undefined): string | undefined {
   return text || undefined
 }
 
+function dedupeText(values: string[]): string[] {
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const value of values) {
+    const cleaned = cleanOptionalText(value)
+    if (!cleaned) continue
+    const key = normalizeText(cleaned)
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(cleaned)
+  }
+  return result
+}
+
+function normalizeText(value: string | undefined): string {
+  return value?.replace(/\s+/g, " ").trim().toLowerCase() ?? ""
+}
+
 const EVIDENCE_SENSITIVE_TERMS = [
   /\bmarket size\b/,
   /\bcagr\b/,

package/lib/inspection-context/match.ts

@@ -45,6 +45,7 @@ export interface InspectionElementSnapshot {
 export interface InspectionElementMatch {
   slide?: InspectionSlideContext
   claim?: InspectionClaimCandidate
+  candidateClaims?: InspectionClaimCandidate[]
   evidence: InspectionEvidenceTrace[]
   gaps: InspectionGap[]
   caveats: string[]
@@ -55,8 +56,12 @@ export interface InspectionElementMatch {
 
 export function matchInspectionElement(context: InspectionContext, snapshot: InspectionElementSnapshot): InspectionElementMatch {
   const selectedText = normalizeText(snapshot.text)
+  const surroundingText = normalizeText(snapshot.nearbyText || snapshot.outerHTMLExcerpt)
   const candidateSlides = candidateSlidesForSnapshot(context, snapshot)
 
+  const anchoredClaim = findAnchoredClaimMatch(candidateSlides, snapshot)
+  if (anchoredClaim) return claimMatch(context, anchoredClaim.slide, anchoredClaim.claim, "high", "Matched explicit claim anchor from selection snapshot.")
+
   if (selectedText) {
     const exactClaim = findClaimMatch(candidateSlides, selectedText, "exact")
     if (exactClaim) return claimMatch(context, exactClaim.slide, exactClaim.claim, "high", "Exact normalized text match.")
@@ -77,8 +82,27 @@ export function matchInspectionElement(context: InspectionContext, snapshot: Ins
     }
   }
 
+  if (surroundingText && surroundingText !== selectedText) {
+    const contextualClaim = findClaimMatch(candidateSlides, surroundingText, "contains")
+    if (contextualClaim) return claimMatch(context, contextualClaim.slide, contextualClaim.claim, "medium", "Matched claim using surrounding slide context.")
+  }
+
   const slide = candidateSlides[0]
-  if (slide) return slideMatch(context, slide, snapshot.slideIndex ? "medium" : "low", snapshot.slideIndex ? "Matched by slideIndex only." : "No claim text matched; returning first candidate slide.")
+  if (slide) {
+    const canonicalClaims = slide.claims.filter((claim) => claim.canonicalClaimId || claim.origin === "narrative")
+    if (canonicalClaims.length === 1) {
+      return claimMatch(context, slide, canonicalClaims[0], "medium", "Selected element matched the slide; the slide has one canonical narrative claim candidate.", canonicalClaims)
+    }
+    return slideMatch(
+      context,
+      slide,
+      snapshot.slideIndex ? "medium" : "low",
+      canonicalClaims.length > 1
+        ? "Matched slide only; multiple canonical claim candidates are available, so no claim id was chosen by semantic guess."
+        : snapshot.slideIndex ? "Matched by slideIndex only." : "No claim text matched; returning first candidate slide.",
+      canonicalClaims,
+    )
+  }
 
   return {
     evidence: [],
@@ -114,6 +138,37 @@ function findClaimMatch(
   return undefined
 }
 
+function findAnchoredClaimMatch(
+  slides: InspectionSlideContext[],
+  snapshot: InspectionElementSnapshot,
+): { slide: InspectionSlideContext; claim: InspectionClaimCandidate } | undefined {
+  const claimIds = explicitClaimIds(snapshot)
+  if (claimIds.length === 0) return undefined
+  for (const slide of slides) {
+    for (const claim of slide.claims) {
+      const ids = [claim.id, claim.canonicalClaimId].filter((item): item is string => Boolean(item))
+      if (ids.some((id) => claimIds.includes(id))) return { slide, claim }
+    }
+  }
+  return undefined
+}
+
+function explicitClaimIds(snapshot: InspectionElementSnapshot): string[] {
+  const values = [
+    snapshot.selector,
+    snapshot.domPath,
+    snapshot.outerHTMLExcerpt,
+    ...(snapshot.elements ?? []).flatMap((item) => [item.selector, item.domPath, item.outerHTMLExcerpt]),
+  ]
+  const ids: string[] = []
+  for (const value of values) {
+    if (!value) continue
+    for (const match of value.matchAll(/data-claim-id\s*=\s*["']([^"']+)["']/gi)) ids.push(match[1])
+    for (const match of value.matchAll(/data-claim-id=([^\]\s>"']+)/gi)) ids.push(match[1])
+  }
+  return dedupe(ids.map((item) => item.trim()).filter(Boolean))
+}
+
 function conservativeContains(claimText: string, selectedText: string): boolean {
   if (selectedText.length < 12 && claimText.length < 12) return false
   return claimText.includes(selectedText) || selectedText.includes(claimText)
@@ -125,10 +180,12 @@ function claimMatch(
   claim: InspectionClaimCandidate,
   confidence: InspectionMatchConfidence,
   reason: string,
+  candidateClaims: InspectionClaimCandidate[] = [],
 ): InspectionElementMatch {
   return {
     slide,
     claim,
+    candidateClaims: candidateClaims.length ? candidateClaims : [claim],
     evidence: claim.evidence,
     gaps: claim.gaps,
     caveats: slide.caveats,
@@ -143,9 +200,11 @@ function slideMatch(
   slide: InspectionSlideContext,
   confidence: InspectionMatchConfidence,
   reason: string,
+  candidateClaims: InspectionClaimCandidate[] = [],
 ): InspectionElementMatch {
   return {
     slide,
+    candidateClaims,
     evidence: slide.evidence,
     gaps: slide.claims.flatMap((claim) => claim.gaps),
     caveats: slide.caveats,
@@ -167,3 +226,14 @@ function normalizeText(text: string | undefined): string {
     .trim()
     .toLowerCase()
 }
+
+function dedupe(values: string[]): string[] {
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const value of values) {
+    if (seen.has(value)) continue
+    seen.add(value)
+    result.push(value)
+  }
+  return result
+}