@cyber-dash-tech/revela 0.11.0 → 0.13.0

package/lib/inspection-context/compile.ts

@@ -1,6 +1,7 @@
 import type { DeckSpec, DecksState, EvidenceRef, NarrativeBrief, NarrativeRole, SlideSpec, SourceMaterial } from "../decks-state"
+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,6 +14,7 @@ export interface InspectionContext {
   outputPath: string
   narrativeBrief?: NarrativeBrief
   sourceMaterials: InspectionSourceMaterial[]
+  narrative?: InspectionNarrativeStateContext
   slides: InspectionSlideContext[]
   gaps: InspectionGap[]
   appendixCandidates: InspectionAppendixCandidate[]
@@ -20,6 +22,12 @@ export interface InspectionContext {
   riskContext: InspectionNarrativeContext[]
 }
 
+export interface InspectionNarrativeStateContext {
+  id: string
+  status: string
+  claimCount: number
+}
+
 export interface InspectionSourceMaterial extends SourceMaterial {
   linkedEvidenceCount: number
 }
@@ -46,6 +54,7 @@ export interface InspectionSlideText {
 
 export interface InspectionClaimCandidate {
   id: string
+  canonicalClaimId?: string
   slideIndex: number
   slideTitle: string
   origin: InspectionClaimOrigin
@@ -54,9 +63,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
@@ -87,12 +105,13 @@ export interface InspectionNarrativeContext {
 
 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,6 +122,7 @@ 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,
@@ -118,9 +138,15 @@ function activeDeck(state: DecksState, slug?: string): DeckSpec {
   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 +162,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,7 +239,34 @@ 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[] {
@@ -192,6 +299,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 +331,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)))
 }
@@ -303,6 +439,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/project.ts

@@ -50,10 +50,15 @@ export interface InspectionProjectionMatch {
   }
   claim?: {
     id: string
+    canonicalClaimId?: string
     origin: string
     text: string
     evidenceSensitive: boolean
     evidenceSupport: string
+    evidenceBindingIds: string[]
+    supportedScope?: string
+    unsupportedScope?: string
+    caveats: string[]
   }
 }
 
@@ -97,6 +102,8 @@ export interface InspectionAppendixProjection {
 
 export interface InspectionEvidenceProjectionTrace {
   source: string
+  evidenceBindingId?: string
+  claimId?: string
   sourcePath?: string
   findingsFile?: string
   location?: string
@@ -104,6 +111,9 @@ export interface InspectionEvidenceProjectionTrace {
   url?: string
   quote?: string
   caveat?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength?: string
   extractedTextPath?: string
   extractedManifestPath?: string
   hasDetail: boolean
@@ -163,10 +173,15 @@ export function projectInspectionMatch(
       claim: claim
         ? {
             id: claim.id,
+            canonicalClaimId: claim.canonicalClaimId,
             origin: claim.origin,
             text: truncate(claim.text, 500),
             evidenceSensitive: claim.evidenceSensitive,
             evidenceSupport: claim.evidenceSupport,
+            evidenceBindingIds: claim.evidenceBindingIds,
+            supportedScope: truncateOptional(claim.supportedScope, 280),
+            unsupportedScope: truncateOptional(claim.unsupportedScope, 280),
+            caveats: claim.caveats.map((item) => truncate(item, 280)).slice(0, 8),
           }
         : undefined,
     },
@@ -211,6 +226,8 @@ export function projectInspectionMatch(
 function projectEvidenceTrace(trace: InspectionEvidenceTrace): InspectionEvidenceProjectionTrace {
   return {
     source: truncate(trace.source, 180),
+    evidenceBindingId: truncateOptional(trace.evidenceBindingId, 160),
+    claimId: truncateOptional(trace.claimId, 160),
     sourcePath: truncateOptional(trace.sourcePath, 220),
     findingsFile: truncateOptional(trace.findingsFile, 220),
     location: truncateOptional(trace.location, 120),
@@ -218,6 +235,9 @@ function projectEvidenceTrace(trace: InspectionEvidenceTrace): InspectionEvidenc
     url: truncateOptional(trace.url, 240),
     quote: truncateOptional(trace.quote, 500),
     caveat: truncateOptional(trace.caveat, 280),
+    supportScope: truncateOptional(trace.supportScope, 280),
+    unsupportedScope: truncateOptional(trace.unsupportedScope, 280),
+    strength: trace.strength,
     extractedTextPath: truncateOptional(trace.extractedTextPath, 220),
     extractedManifestPath: truncateOptional(trace.extractedManifestPath, 220),
     hasDetail: trace.hasDetail,

package/lib/narrative-state/coverage.ts

@@ -0,0 +1,100 @@
+import { type DecksState, type SlideClaimRef, type SlideClaimRefRole } from "../decks-state"
+import { recordWorkspaceAction } from "../workspace-state/actions"
+import { ensureActiveHtmlDeckRenderTarget } from "../workspace-state/render-targets"
+import { computeNarrativeHash } from "./hash"
+import { normalizeNarrativeState } from "./normalize"
+import { getClaimSlideRefs, type ClaimSlideRef } from "./queries"
+
+export interface BackfillSlideClaimRefsResult {
+  updated: boolean
+  addedCount: number
+  slideCount: number
+  narrativeHash: string
+  refs: ClaimSlideRef[]
+}
+
+export function backfillSlideClaimRefsFromCoverage(state: DecksState): { state: DecksState; result: BackfillSlideClaimRefsResult } {
+  const narrative = normalizeNarrativeState(state)
+  const narrativeHash = computeNarrativeHash(narrative)
+  const deckKey = state.activeDeck || Object.keys(state.decks)[0]
+  const deck = deckKey ? state.decks[deckKey] : undefined
+  if (!deck) {
+    return { state: { ...state, narrative }, result: { updated: false, addedCount: 0, slideCount: 0, narrativeHash, refs: [] } }
+  }
+
+  const refs = getClaimSlideRefs({ ...state, narrative }, deck)
+  const refsBySlide = new Map<number, ClaimSlideRef[]>()
+  for (const ref of refs) refsBySlide.set(ref.slideIndex, [...(refsBySlide.get(ref.slideIndex) ?? []), ref])
+
+  let addedCount = 0
+  const slides = deck.slides.map((slide) => {
+    const existing = [...(slide.claimRefs ?? [])]
+    const seen = new Set(existing.map((ref) => `${ref.claimId}:${ref.role}`))
+    const additions: SlideClaimRef[] = []
+    for (const ref of refsBySlide.get(slide.index) ?? []) {
+      const role = backfilledRole(ref.role)
+      const key = `${ref.claimId}:${role}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      additions.push({ claimId: ref.claimId, role, note: backfillNote(ref) })
+    }
+    if (additions.length === 0) return slide
+    addedCount += additions.length
+    return { ...slide, claimRefs: [...existing, ...additions] }
+  })
+
+  const next: DecksState = {
+    ...state,
+    narrative,
+    decks: {
+      ...state.decks,
+      [deckKey]: {
+        ...deck,
+        slides,
+      },
+    },
+  }
+
+  const updatedRefs = getClaimSlideRefs(next, next.decks[deckKey])
+  const htmlTarget = ensureActiveHtmlDeckRenderTarget(next)
+  if (htmlTarget) {
+    htmlTarget.data = {
+      ...(htmlTarget.data ?? {}),
+      narrativeId: narrative.id,
+      narrativeHash,
+      claimSlideRefs: updatedRefs.map((ref) => ({
+        claimId: ref.claimId,
+        claimText: ref.claimText,
+        slideIndex: ref.slideIndex,
+        slideTitle: ref.slideTitle,
+        match: ref.match,
+        role: ref.role,
+        location: ref.location,
+      })),
+    }
+  }
+
+  if (addedCount > 0) {
+    recordWorkspaceAction(next, {
+      type: "artifact.coverage_backfilled",
+      actor: "revela-decks",
+      inputs: { activeDeck: deckKey, narrativeId: narrative.id },
+      outputs: { addedCount, slideCount: slides.length, narrativeHash },
+      status: "success",
+      summary: `Backfilled ${addedCount} slide claim reference${addedCount === 1 ? "" : "s"} from current artifact coverage.`,
+      nodeIds: [narrative.id, `artifact:${deck.outputPath ?? deckKey}`],
+    })
+  }
+
+  return { state: next, result: { updated: addedCount > 0, addedCount, slideCount: slides.length, narrativeHash, refs: updatedRefs } }
+}
+
+function backfilledRole(role: SlideClaimRefRole): SlideClaimRefRole {
+  return role
+}
+
+function backfillNote(ref: ClaimSlideRef): string {
+  if (ref.match === "metadata") return `Backfilled from ${ref.location}.`
+  if (ref.match === "content") return `Backfilled from content match at ${ref.location}.`
+  return "Backfilled from slide evidence trace."
+}

package/lib/narrative-state/display.ts

@@ -0,0 +1,219 @@
+import type { NarrativeMap, NarrativeMapClaimRelation } from "./map"
+
+export type NarrativeViewLanguage = string
+
+export interface NarrativeDisplayModel {
+  version: 1
+  language: NarrativeViewLanguage
+  pageTitle?: string
+  summaryLine?: string
+  labels?: Partial<NarrativeDisplayLabels>
+  claimCards?: NarrativeDisplayClaimCard[]
+  relations?: NarrativeDisplayRelation[]
+}
+
+export interface NarrativeDisplayLabels {
+  eyebrow: string
+  claimFlow: string
+  flowNote: string
+  selectedClaim: string
+  claim: string
+  claimId: string
+  status: string
+  supportedScope: string
+  unsupportedScope: string
+  incomingRelations: string
+  outgoingRelations: string
+  evidence: string
+  objections: string
+  risks: string
+  researchGaps: string
+  coveredSlides: string
+  noClaims: string
+  none: string
+}
+
+export interface NarrativeDisplayClaimCard {
+  claimId: string
+  displayTitle?: string
+  roleLabel?: string
+  narrativeJob?: string
+  evidenceSummary?: string
+  riskOrGapSummary?: string
+}
+
+export interface NarrativeDisplayRelation {
+  fromClaimId: string
+  toClaimId: string
+  relation: NarrativeMapClaimRelation["relation"]
+  displayLabel?: string
+  displayRationale?: string
+}
+
+export interface ValidatedNarrativeDisplayModel {
+  version: 1
+  language: NarrativeViewLanguage
+  pageTitle?: string
+  summaryLine?: string
+  labels: NarrativeDisplayLabels
+  claimCards: Map<string, NarrativeDisplayClaimCard>
+  relations: Map<string, NarrativeDisplayRelation>
+}
+
+export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage): NarrativeDisplayLabels {
+  if (isChineseLanguage(language)) {
+    return {
+      eyebrow: "只读主张流",
+      claimFlow: "主张推进",
+      flowNote: "点击主张查看证据、关系、风险、缺口和已覆盖页面。",
+      selectedClaim: "当前主张",
+      claim: "主张",
+      claimId: "主张 ID",
+      status: "状态",
+      supportedScope: "已支持范围",
+      unsupportedScope: "未支持范围",
+      incomingRelations: "前置关系",
+      outgoingRelations: "后续关系",
+      evidence: "证据",
+      objections: "反对意见",
+      risks: "风险",
+      researchGaps: "研究缺口",
+      coveredSlides: "已覆盖页面",
+      noClaims: "没有记录主张",
+      none: "无",
+    }
+  }
+  if (isJapaneseLanguage(language)) {
+    return {
+      eyebrow: "読み取り専用クレームフロー",
+      claimFlow: "クレームフロー",
+      flowNote: "クレームをクリックすると、根拠、関係、リスク、ギャップ、該当スライドを確認できます。",
+      selectedClaim: "選択中のクレーム",
+      claim: "クレーム",
+      claimId: "クレーム ID",
+      status: "ステータス",
+      supportedScope: "裏付けられた範囲",
+      unsupportedScope: "未裏付けの範囲",
+      incomingRelations: "入力関係",
+      outgoingRelations: "出力関係",
+      evidence: "根拠",
+      objections: "反論",
+      risks: "リスク",
+      researchGaps: "調査ギャップ",
+      coveredSlides: "対応スライド",
+      noClaims: "クレームは記録されていません",
+      none: "なし",
+    }
+  }
+  return {
+    eyebrow: "Read-only claim flow board",
+    claimFlow: "Claim Flow",
+    flowNote: "Click a claim to inspect support, relation context, gaps, and covered slides.",
+    selectedClaim: "Selected claim",
+    claim: "Claim",
+    claimId: "Claim ID",
+    status: "Status",
+    supportedScope: "Supported scope",
+    unsupportedScope: "Unsupported scope",
+    incomingRelations: "Incoming relations",
+    outgoingRelations: "Outgoing relations",
+    evidence: "Evidence",
+    objections: "Objections",
+    risks: "Risks",
+    researchGaps: "Research gaps",
+    coveredSlides: "Covered slides",
+    noClaims: "No claims recorded",
+    none: "None",
+  }
+}
+
+export function validateNarrativeDisplayModel(map: NarrativeMap, input: NarrativeDisplayModel | undefined, language: NarrativeViewLanguage): ValidatedNarrativeDisplayModel {
+  const defaults = defaultNarrativeDisplayLabels(language)
+  if (!input) return emptyDisplayModel(language, defaults)
+  if (input.version !== 1) throw new Error("Narrative display model version must be 1.")
+  if (input.language !== language) throw new Error(`Narrative display model language must be ${language}.`)
+
+  const claimIds = new Set(map.claimFlow.map((claim) => claim.id))
+  const relationByKey = new Map(map.claimRelations.map((relation) => [relationKey(relation), relation]))
+  const claimCards = new Map<string, NarrativeDisplayClaimCard>()
+  for (const card of input.claimCards ?? []) {
+    if (!claimIds.has(card.claimId)) throw new Error(`Unknown display claimId: ${card.claimId}`)
+    claimCards.set(card.claimId, cleanClaimCard(card))
+  }
+
+  const relations = new Map<string, NarrativeDisplayRelation>()
+  for (const relation of input.relations ?? []) {
+    const key = relationKey(relation)
+    const canonical = relationByKey.get(key)
+    if (!canonical) throw new Error(`Display relation is not present in the narrative map: ${key}`)
+    relations.set(key, cleanRelation(relation, canonical))
+  }
+
+  return {
+    version: 1,
+    language,
+    pageTitle: clean(input.pageTitle),
+    summaryLine: clean(input.summaryLine),
+    labels: mergeLabels(defaults, input.labels),
+    claimCards,
+    relations,
+  }
+}
+
+export function emptyDisplayModel(language: NarrativeViewLanguage, labels = defaultNarrativeDisplayLabels(language)): ValidatedNarrativeDisplayModel {
+  return { version: 1, language, labels, claimCards: new Map(), relations: new Map() }
+}
+
+export function relationKey(relation: Pick<NarrativeDisplayRelation, "fromClaimId" | "toClaimId" | "relation">): string {
+  return `${relation.fromClaimId}\u0000${relation.toClaimId}\u0000${relation.relation}`
+}
+
+export function isChineseLanguage(language: string): boolean {
+  const normalized = language.trim().toLowerCase()
+  return normalized === "zh" || normalized === "zh-cn" || normalized === "cn" || normalized === "chinese" || normalized.includes("中文") || normalized.includes("简体")
+}
+
+export function isJapaneseLanguage(language: string): boolean {
+  const normalized = language.trim().toLowerCase()
+  return normalized === "ja" || normalized === "ja-jp" || normalized === "jp" || normalized === "japanese" || normalized.includes("日本")
+}
+
+function mergeLabels(defaults: NarrativeDisplayLabels, overrides: Partial<NarrativeDisplayLabels> | undefined): NarrativeDisplayLabels {
+  const merged: NarrativeDisplayLabels = { ...defaults }
+  if (!overrides) return merged
+  for (const key of Object.keys(defaults) as Array<keyof NarrativeDisplayLabels>) {
+    merged[key] = clean(overrides[key]) ?? defaults[key]
+  }
+  return merged
+}
+
+function cleanClaimCard(card: NarrativeDisplayClaimCard): NarrativeDisplayClaimCard {
+  return {
+    claimId: card.claimId,
+    displayTitle: clean(card.displayTitle),
+    roleLabel: clean(card.roleLabel),
+    narrativeJob: clean(card.narrativeJob),
+    evidenceSummary: clean(card.evidenceSummary),
+    riskOrGapSummary: clean(card.riskOrGapSummary),
+  }
+}
+
+function cleanRelation(relation: NarrativeDisplayRelation, canonical: NarrativeMapClaimRelation): NarrativeDisplayRelation {
+  const displayLabel = clean(relation.displayLabel)
+  const displayRationale = clean(relation.displayRationale)
+  if (displayLabel && canonical.inferred) throw new Error("Display label cannot replace inferred, non-canonical claim relation status.")
+  if (displayRationale && canonical.inferred) throw new Error("Display rationale cannot replace inferred, non-canonical claim relation rationale.")
+  if (displayRationale && !canonical.rationale?.trim()) throw new Error("Display rationale requires canonical claim relation rationale.")
+  return {
+    fromClaimId: relation.fromClaimId,
+    toClaimId: relation.toClaimId,
+    relation: relation.relation,
+    displayLabel,
+    displayRationale,
+  }
+}
+
+function clean(value: string | undefined): string | undefined {
+  const text = value?.trim()
+  return text || undefined
+}