@cyber-dash-tech/revela 0.12.0 → 0.13.0

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
+}

package/lib/narrative-state/executive-brief.ts

@@ -0,0 +1,246 @@
+import type { DecksState } from "../decks-state"
+import { recordWorkspaceAction } from "../workspace-state/actions"
+import {
+  artifactNodeIdForRenderTarget,
+  normalizeWorkspacePath,
+  renderTargetId,
+  upsertRenderTarget,
+} from "../workspace-state/render-targets"
+import type { RenderTarget } from "../workspace-state/types"
+import { computeNarrativeHash } from "./hash"
+import { normalizeNarrativeState } from "./normalize"
+import { reviewNarrativeState } from "./readiness"
+import type { NarrativeApproval, NarrativeClaim, NarrativeEvidenceBinding, NarrativeStateV1 } from "./types"
+
+export const DEFAULT_EXECUTIVE_BRIEF_PATH = "briefs/executive-brief.md"
+
+export interface CompileExecutiveBriefOptions {
+  outputPath?: string
+  now?: string
+}
+
+export type CompileExecutiveBriefResult =
+  | {
+    ok: true
+    state: DecksState
+    outputPath: string
+    content: string
+    target: RenderTarget
+    narrativeHash: string
+  }
+  | {
+    ok: false
+    state: DecksState
+    reason: string
+    narrativeHash?: string
+  }
+
+export function compileExecutiveBrief(state: DecksState, options: CompileExecutiveBriefOptions = {}): CompileExecutiveBriefResult {
+  const now = options.now ?? new Date().toISOString()
+  const reviewed = reviewNarrativeState(state, { now })
+  const narrative = reviewed.state.narrative ?? normalizeNarrativeState(reviewed.state)
+  const narrativeHash = reviewed.result.narrativeHash || computeNarrativeHash(narrative)
+  const allowedApproval = currentNarrativeApprovalOrOverride(narrative, narrativeHash)
+
+  if (!allowedApproval) {
+    return {
+      ok: false,
+      state: reviewed.state,
+      reason: "Executive brief rendering requires current narrative approval or an explicit render override.",
+      narrativeHash,
+    }
+  }
+
+  const outputPath = normalizeWorkspacePath(options.outputPath || DEFAULT_EXECUTIVE_BRIEF_PATH)
+  const content = renderExecutiveBriefMarkdown(narrative, narrativeHash, now, allowedApproval)
+  const claimIds = narrative.claims.map((claim) => claim.id).sort()
+  const evidenceBindingIds = narrative.evidenceBindings.map((binding) => binding.id).sort()
+  const target: RenderTarget = {
+    id: renderTargetId("executive_brief", outputPath),
+    type: "executive_brief",
+    outputPath,
+    sourceNodeIds: [narrative.id, ...claimIds, ...evidenceBindingIds],
+    artifactVersion: narrativeHash,
+    contractStatus: "valid",
+    data: {
+      narrativeHash,
+      generatedAt: now,
+      format: "markdown",
+      claimIds,
+      evidenceBindingIds,
+      approvalId: allowedApproval.id,
+      approvalScope: allowedApproval.scope,
+    },
+  }
+
+  const next: DecksState = { ...reviewed.state, narrative }
+  upsertRenderTarget(next, target)
+  recordWorkspaceAction(next, {
+    type: "artifact.rendered",
+    actor: "revela-brief",
+    inputs: {
+      type: "executive_brief",
+      narrativeId: narrative.id,
+      narrativeHash,
+      approvalId: allowedApproval.id,
+    },
+    outputs: {
+      outputPath,
+      targetId: target.id,
+      claimCount: claimIds.length,
+      evidenceBindingCount: evidenceBindingIds.length,
+    },
+    status: "success",
+    summary: "Rendered executive brief from approved narrative state.",
+    nodeIds: [target.id, artifactNodeIdForRenderTarget(target), narrative.id, ...claimIds],
+    timestamp: now,
+  })
+
+  return { ok: true, state: next, outputPath, content, target, narrativeHash }
+}
+
+function currentNarrativeApprovalOrOverride(narrative: NarrativeStateV1, narrativeHash: string): NarrativeApproval | undefined {
+  const approvals = [...(narrative.approvals ?? [])]
+  for (let index = approvals.length - 1; index >= 0; index -= 1) {
+    const approval = approvals[index]
+    if (approval.narrativeHash !== narrativeHash) continue
+    if (approval.scope === "narrative" && approval.approvedBy === "user") return approval
+    if (approval.scope === "render_override" || approval.approvedBy === "override") return approval
+  }
+  return undefined
+}
+
+function renderExecutiveBriefMarkdown(narrative: NarrativeStateV1, narrativeHash: string, generatedAt: string, approval: NarrativeApproval): string {
+  const evidenceByClaim = groupEvidenceByClaim(narrative.evidenceBindings)
+  const centralClaims = narrative.claims.filter((claim) => claim.importance === "central")
+  const supportingClaims = narrative.claims.filter((claim) => claim.importance !== "central")
+  const lines: string[] = []
+
+  lines.push("# Executive Brief")
+  lines.push("")
+  lines.push(`Generated: ${generatedAt}`)
+  lines.push(`Narrative ID: ${narrative.id}`)
+  lines.push(`Narrative hash: ${narrativeHash}`)
+  lines.push(`Approval: ${approval.id} (${approval.scope}, ${approval.approvedBy})`)
+  lines.push("")
+  lines.push("## Decision Context")
+  lines.push(`- Audience: ${fallback(narrative.audience.primary)}`)
+  lines.push(`- Belief before: ${fallback(narrative.audience.beliefBefore)}`)
+  lines.push(`- Belief after: ${fallback(narrative.audience.beliefAfter)}`)
+  lines.push(`- Decision/action: ${fallback(narrative.decision.action)}`)
+  if (narrative.decision.owner) lines.push(`- Owner: ${narrative.decision.owner}`)
+  if (narrative.decision.deadline) lines.push(`- Deadline: ${narrative.decision.deadline}`)
+  if (narrative.decision.consequenceOfNoDecision) lines.push(`- Consequence of no decision: ${narrative.decision.consequenceOfNoDecision}`)
+  lines.push("")
+  lines.push("## Thesis")
+  lines.push(narrative.thesis?.statement ? `${narrative.thesis.statement} (${narrative.thesis.confidence} confidence)` : "Not recorded.")
+  if (narrative.thesis?.caveat) lines.push(`Caveat: ${narrative.thesis.caveat}`)
+  lines.push("")
+
+  appendClaims(lines, "Central Claims", centralClaims, evidenceByClaim)
+  appendClaims(lines, "Supporting Claims", supportingClaims, evidenceByClaim)
+  appendObjections(lines, narrative)
+  appendRisks(lines, narrative)
+  appendResearchGaps(lines, narrative)
+  lines.push("## Provenance")
+  lines.push(`- Render target: executive_brief`)
+  lines.push(`- Source narrative: ${narrative.id}`)
+  lines.push(`- Narrative hash: ${narrativeHash}`)
+  lines.push(`- Approval id: ${approval.id}`)
+  lines.push("- This brief is compiled from canonical narrative state, not from a deck summary.")
+  lines.push("")
+
+  return lines.join("\n")
+}
+
+function appendClaims(lines: string[], title: string, claims: NarrativeClaim[], evidenceByClaim: Map<string, NarrativeEvidenceBinding[]>): void {
+  lines.push(`## ${title}`)
+  if (claims.length === 0) {
+    lines.push("Not recorded.")
+    lines.push("")
+    return
+  }
+
+  for (const claim of claims) {
+    lines.push(`### ${claim.text}`)
+    lines.push(`- Claim ID: ${claim.id}`)
+    lines.push(`- Kind: ${claim.kind}`)
+    lines.push(`- Evidence status: ${claim.evidenceStatus}`)
+    if (claim.supportedScope) lines.push(`- Supported scope: ${claim.supportedScope}`)
+    if (claim.unsupportedScope) lines.push(`- Unsupported scope: ${claim.unsupportedScope}`)
+    for (const caveat of claim.caveats ?? []) lines.push(`- Caveat: ${caveat}`)
+    const bindings = evidenceByClaim.get(claim.id) ?? []
+    if (bindings.length === 0) lines.push("- Evidence: none bound")
+    else {
+      lines.push("- Evidence:")
+      for (const binding of bindings) appendEvidence(lines, binding)
+    }
+    lines.push("")
+  }
+}
+
+function appendEvidence(lines: string[], binding: NarrativeEvidenceBinding): void {
+  lines.push(`  - ${binding.id} (${binding.strength})`)
+  lines.push(`    - Source: ${binding.source}`)
+  if (binding.findingsFile) lines.push(`    - Findings file: ${binding.findingsFile}`)
+  if (binding.sourcePath) lines.push(`    - Source path: ${binding.sourcePath}`)
+  if (binding.location) lines.push(`    - Location: ${binding.location}`)
+  if (binding.url) lines.push(`    - URL: ${binding.url}`)
+  if (binding.quote) lines.push(`    - Quote: ${binding.quote}`)
+  if (binding.supportScope) lines.push(`    - Support scope: ${binding.supportScope}`)
+  if (binding.unsupportedScope) lines.push(`    - Unsupported scope: ${binding.unsupportedScope}`)
+  if (binding.caveat) lines.push(`    - Caveat: ${binding.caveat}`)
+}
+
+function appendObjections(lines: string[], narrative: NarrativeStateV1): void {
+  lines.push("## Objections")
+  if (narrative.objections.length === 0) lines.push("Not recorded.")
+  for (const objection of narrative.objections) {
+    lines.push(`- ${objection.text}`)
+    lines.push(`  - Objection ID: ${objection.id}`)
+    if (objection.claimId) lines.push(`  - Challenges claim: ${objection.claimId}`)
+    lines.push(`  - Priority: ${objection.priority}`)
+    if (objection.response) lines.push(`  - Response: ${objection.response}`)
+  }
+  lines.push("")
+}
+
+function appendRisks(lines: string[], narrative: NarrativeStateV1): void {
+  lines.push("## Risks")
+  if (narrative.risks.length === 0) lines.push("Not recorded.")
+  for (const risk of narrative.risks) {
+    lines.push(`- ${risk.text}`)
+    lines.push(`  - Risk ID: ${risk.id}`)
+    if (risk.claimId) lines.push(`  - Constrains claim: ${risk.claimId}`)
+    lines.push(`  - Severity: ${risk.severity}`)
+    if (risk.mitigation) lines.push(`  - Mitigation: ${risk.mitigation}`)
+  }
+  lines.push("")
+}
+
+function appendResearchGaps(lines: string[], narrative: NarrativeStateV1): void {
+  lines.push("## Research Gaps")
+  const gaps = narrative.researchGaps ?? []
+  if (gaps.length === 0) lines.push("Not recorded.")
+  for (const gap of gaps) {
+    lines.push(`- ${gap.question}`)
+    lines.push(`  - Gap ID: ${gap.id}`)
+    lines.push(`  - Status: ${gap.status}`)
+    lines.push(`  - Priority: ${gap.priority}`)
+    if (gap.targetId) lines.push(`  - Target: ${gap.targetType}:${gap.targetId}`)
+    if (gap.findingsFile) lines.push(`  - Findings file: ${gap.findingsFile}`)
+    if (gap.evidenceBindingIds?.length) lines.push(`  - Evidence bindings: ${gap.evidenceBindingIds.join(", ")}`)
+    if (gap.notes) lines.push(`  - Notes: ${gap.notes}`)
+  }
+  lines.push("")
+}
+
+function groupEvidenceByClaim(bindings: NarrativeEvidenceBinding[]): Map<string, NarrativeEvidenceBinding[]> {
+  const grouped = new Map<string, NarrativeEvidenceBinding[]>()
+  for (const binding of bindings) grouped.set(binding.claimId, [...(grouped.get(binding.claimId) ?? []), binding])
+  return grouped
+}
+
+function fallback(value: string | undefined): string {
+  return value?.trim() || "Not recorded"
+}

package/lib/narrative-state/hash.ts

@@ -9,6 +9,10 @@ export function stableClaimId(text: string): string {
   return `claim:${stableHash(text)}`
 }
 
+export function stableClaimRelationId(fromClaimId: string, toClaimId: string, relation: string): string {
+  return `claim-relation:${stableHash(`${fromClaimId}:${toClaimId}:${relation}`)}`
+}
+
 export function stableEvidenceId(claimId: string, seed: string): string {
   return `evidence:${claimId}:${stableHash(seed)}`
 }
@@ -21,6 +25,10 @@ export function stableRiskId(text: string): string {
   return `risk:${stableHash(text)}`
 }
 
+export function stableResearchGapId(seed: string): string {
+  return `research-gap:${stableHash(seed)}`
+}
+
 export function computeNarrativeHash(narrative: NarrativeStateV1): string {
   return stableHash(stableStringify({
     version: narrative.version,
@@ -29,6 +37,7 @@ export function computeNarrativeHash(narrative: NarrativeStateV1): string {
     decision: narrative.decision,
     thesis: narrative.thesis,
     claims: narrative.claims,
+    claimRelations: narrative.claimRelations ?? [],
     evidenceBindings: narrative.evidenceBindings,
     objections: narrative.objections,
     risks: narrative.risks,