@cyber-dash-tech/revela 0.10.0 → 0.11.0

package/lib/workspace-state/evidence-status.ts

@@ -0,0 +1,267 @@
+import {
+  applyEvidenceCandidates,
+  hasDecksState,
+  readDecksState,
+  reviewDeckState,
+  writeDecksState,
+  type AppliedEvidenceCandidate,
+  type DecksState,
+  type EvidenceBindingCandidate,
+  type EvidenceCandidateSearchDiagnostic,
+  type EvidenceRef,
+  type ReadinessIssue,
+  type SkippedEvidenceCandidate,
+} from "../decks-state"
+import { compileInspectionContext, type InspectionEvidenceTrace, type InspectionGap } from "../inspection-context/compile"
+import { matchInspectionElement, type InspectionElementMatch, type InspectionElementSnapshot, type InspectionMatchConfidence } from "../inspection-context/match"
+import { recordWorkspaceAction } from "./actions"
+import type { WorkspaceAction } from "./types"
+
+export interface EvidenceStatusForSelection {
+  version: 1
+  selection: EvidenceStatusSelection
+  match: EvidenceStatusMatch
+  boundEvidence: EvidenceStatusEvidence[]
+  gaps: EvidenceStatusGap[]
+  candidateEvidence: EvidenceStatusCandidate[]
+  searchDiagnostics: EvidenceCandidateSearchDiagnostic[]
+  actionTrace: EvidenceStatusActionTrace[]
+}
+
+export interface EvidenceStatusSelection {
+  slideIndex?: number
+  selectedText?: string
+  scope?: InspectionElementSnapshot["scope"]
+}
+
+export interface EvidenceStatusMatch {
+  confidence: InspectionMatchConfidence
+  reason: string
+  slideIndex?: number
+  slideTitle?: string
+  claimId?: string
+  claimText?: string
+  claimEvidenceSensitive?: boolean
+  claimEvidenceSupport?: string
+}
+
+export interface EvidenceStatusEvidence extends EvidenceRef {
+  slideIndex: number
+  slideTitle: string
+  hasDetail: boolean
+}
+
+export interface EvidenceStatusGap {
+  type: InspectionGap["type"]
+  slideIndex: number
+  slideTitle: string
+  claimText: string
+  message: string
+}
+
+export interface EvidenceStatusCandidate extends EvidenceBindingCandidate {
+  relevant: boolean
+}
+
+export interface EvidenceStatusActionTrace {
+  id: string
+  type: WorkspaceAction["type"]
+  timestamp: string
+  actor?: string
+  status: WorkspaceAction["status"]
+  summary?: string
+  inputs?: Record<string, unknown>
+  outputs?: Record<string, unknown>
+  nodeIds?: string[]
+}
+
+export interface ApplyEvidenceBindingsResult {
+  applied: AppliedEvidenceCandidate[]
+  skipped: SkippedEvidenceCandidate[]
+  nextReviewNeeded: boolean
+}
+
+export function getEvidenceStatusForSelection(workspaceRoot: string, snapshot: InspectionElementSnapshot, options: { slug?: string } = {}): EvidenceStatusForSelection {
+  if (!hasDecksState(workspaceRoot)) throw new Error("DECKS.json is required before checking evidence status. Run /revela init first.")
+  const state = readDecksState(workspaceRoot)
+  return getEvidenceStatusInState(state, snapshot, { ...options, workspaceRoot })
+}
+
+export function getEvidenceStatusInState(
+  state: DecksState,
+  snapshot: InspectionElementSnapshot,
+  options: { workspaceRoot?: string; slug?: string } = {},
+): EvidenceStatusForSelection {
+  const normalizedSnapshot = normalizeEvidenceSnapshot(snapshot)
+  const context = compileInspectionContext(state, options.slug)
+  const match = matchInspectionElement(context, normalizedSnapshot)
+  const reviewed = reviewDeckState(state, context.slug, { workspaceRoot: options.workspaceRoot })
+  const candidates = relevantCandidates(reviewed.result.evidenceCandidates ?? [], match)
+  const diagnostics = relevantSearchDiagnostics(reviewed.result.issues, match)
+
+  return {
+    version: 1,
+    selection: {
+      slideIndex: normalizedSnapshot.slideIndex,
+      selectedText: normalizedSnapshot.selectedText || normalizedSnapshot.text,
+      scope: normalizedSnapshot.scope,
+    },
+    match: projectMatch(match),
+    boundEvidence: match.evidence.map(projectEvidence),
+    gaps: evidenceStatusGaps(match, reviewed.result.issues),
+    candidateEvidence: candidates,
+    searchDiagnostics: diagnostics,
+    actionTrace: actionTraceForMatch(state.actions ?? [], match),
+  }
+}
+
+export function applyEvidenceBindings(workspaceRoot: string, candidateIds: string[]): ApplyEvidenceBindingsResult {
+  if (!hasDecksState(workspaceRoot)) throw new Error("DECKS.json is required before applying evidence bindings. Run /revela init first.")
+  const ids = [...new Set(candidateIds.map((id) => id.trim()).filter(Boolean))]
+  if (ids.length === 0) throw new Error("candidateIds are required for evidence binding application.")
+
+  const state = readDecksState(workspaceRoot)
+  const applied = applyEvidenceCandidates(state, ids, { workspaceRoot })
+  recordEvidenceBindingAction(applied.state, ids, applied.result)
+  writeDecksState(workspaceRoot, applied.state)
+  return applied.result
+}
+
+export function recordEvidenceBindingAction(state: DecksState, candidateIds: string[], result: ApplyEvidenceBindingsResult): DecksState {
+  return recordWorkspaceAction(state, {
+    type: "evidence.binding_applied",
+    actor: "revela-decks",
+    inputs: { candidateIds },
+    outputs: {
+      applied: result.applied.map((item) => ({ candidateId: item.candidateId, slideIndex: item.slideIndex, evidence: item.evidence })),
+      skipped: result.skipped,
+      nextReviewNeeded: result.nextReviewNeeded,
+    },
+    status: result.applied.length > 0 ? "success" : "skipped",
+    summary: `Applied ${result.applied.length} evidence candidate${result.applied.length === 1 ? "" : "s"}.`,
+    nodeIds: result.applied.map((item) => `slide:${item.slideIndex}`),
+  })
+}
+
+function normalizeEvidenceSnapshot(snapshot: InspectionElementSnapshot): InspectionElementSnapshot {
+  const selectedText = snapshot.selectedText || snapshot.text
+  return {
+    ...snapshot,
+    text: snapshot.text || selectedText,
+    selectedText,
+  }
+}
+
+function projectMatch(match: InspectionElementMatch): EvidenceStatusMatch {
+  return {
+    confidence: match.confidence,
+    reason: match.reason,
+    slideIndex: match.slide?.index,
+    slideTitle: match.slide?.title,
+    claimId: match.claim?.id,
+    claimText: match.claim?.text,
+    claimEvidenceSensitive: match.claim?.evidenceSensitive,
+    claimEvidenceSupport: match.claim?.evidenceSupport,
+  }
+}
+
+function projectEvidence(trace: InspectionEvidenceTrace): EvidenceStatusEvidence {
+  return {
+    ...trace,
+    slideIndex: trace.slideIndex,
+    slideTitle: trace.slideTitle,
+    hasDetail: trace.hasDetail,
+  }
+}
+
+function projectGap(gap: InspectionGap): EvidenceStatusGap {
+  return {
+    type: gap.type,
+    slideIndex: gap.slideIndex,
+    slideTitle: gap.slideTitle,
+    claimText: gap.claimText,
+    message: gap.message,
+  }
+}
+
+function evidenceStatusGaps(match: InspectionElementMatch, issues: ReadinessIssue[]): EvidenceStatusGap[] {
+  const gaps = match.gaps.map(projectGap)
+  const slideIndex = match.slide?.index
+  for (const issue of issues) {
+    if (issue.slideIndex !== slideIndex) continue
+    if (typeof issue.slideIndex !== "number") continue
+    if (issue.type !== "missing_evidence" && issue.type !== "weak_evidence") continue
+    if (gaps.some((gap) => gap.type === issue.type && gap.claimText === issue.claimText)) continue
+    gaps.push({
+      type: issue.type,
+      slideIndex: issue.slideIndex,
+      slideTitle: issue.slideTitle ?? match.slide?.title ?? "",
+      claimText: issue.claimText ?? match.claim?.text ?? "",
+      message: issue.message,
+    })
+  }
+  return gaps
+}
+
+function relevantCandidates(candidates: EvidenceBindingCandidate[], match: InspectionElementMatch): EvidenceStatusCandidate[] {
+  const slideIndex = match.slide?.index
+  return candidates
+    .filter((candidate) => candidate.slideIndex === slideIndex)
+    .map((candidate) => ({
+      ...candidate,
+      relevant: candidateRelevantToMatch(candidate, match),
+    }))
+}
+
+function candidateRelevantToMatch(candidate: EvidenceBindingCandidate, match: InspectionElementMatch): boolean {
+  const claimText = normalizeText(match.claim?.text)
+  if (!claimText || !candidate.claimText) return true
+  const candidateClaim = normalizeText(candidate.claimText)
+  if (candidateClaim === claimText || candidateClaim.includes(claimText) || claimText.includes(candidateClaim)) return true
+  const quote = normalizeText(candidate.quote)
+  if (quote.includes(claimText)) return true
+  return (candidate.supportScope ?? []).some((scope) => {
+    const normalizedScope = normalizeText(scope)
+    return normalizedScope === claimText || normalizedScope.includes(claimText) || claimText.includes(normalizedScope)
+  })
+}
+
+function relevantSearchDiagnostics(issues: ReadinessIssue[], match: InspectionElementMatch): EvidenceCandidateSearchDiagnostic[] {
+  const slideIndex = match.slide?.index
+  return issues
+    .filter((issue) => issue.slideIndex === slideIndex && issue.evidenceCandidateSearch)
+    .map((issue) => issue.evidenceCandidateSearch!)
+}
+
+function actionTraceForMatch(actions: WorkspaceAction[], match: InspectionElementMatch): EvidenceStatusActionTrace[] {
+  const slideNodeId = match.slide ? `slide:${match.slide.index}` : undefined
+  const evidenceKeys = new Set(match.evidence.flatMap((item) => [item.source, item.sourcePath, item.findingsFile].filter((value): value is string => Boolean(value))))
+  return actions
+    .filter((action) => actionRelevantToMatch(action, slideNodeId, evidenceKeys))
+    .slice(-12)
+    .map((action) => ({
+      id: action.id,
+      type: action.type,
+      timestamp: action.timestamp,
+      actor: action.actor,
+      status: action.status,
+      summary: action.summary,
+      inputs: action.inputs,
+      outputs: action.outputs,
+      nodeIds: action.nodeIds,
+    }))
+}
+
+function actionRelevantToMatch(action: WorkspaceAction, slideNodeId: string | undefined, evidenceKeys: Set<string>): boolean {
+  if (slideNodeId && action.nodeIds?.includes(slideNodeId)) return true
+  if (action.type === "evidence.binding_applied" || action.type === "evidence.candidate_generated") return true
+  const text = JSON.stringify({ inputs: action.inputs, outputs: action.outputs, nodeIds: action.nodeIds })
+  for (const key of evidenceKeys) {
+    if (key && text.includes(key)) return true
+  }
+  return false
+}
+
+function normalizeText(value: string | undefined): string {
+  return String(value ?? "").replace(/\s+/g, " ").trim().toLowerCase()
+}

package/lib/workspace-state/graph.ts

@@ -0,0 +1,426 @@
+import { createHash } from "crypto"
+import type { DeckSpec, DecksState, EvidenceRef, NarrativeBrief, ResearchAxis, SlideSpec, SourceMaterial } from "../decks-state"
+import { renderTargetId } from "./render-targets"
+import type { GraphEdge, GraphEdgeType, GraphNode, GraphNodeType, RenderTarget, WorkspaceGraph } from "./types"
+
+export interface ProjectWorkspaceGraphOptions {
+  slug?: string
+}
+
+interface GraphBuilder {
+  nodes: Map<string, GraphNode>
+  edges: Map<string, GraphEdge>
+}
+
+export function projectWorkspaceGraph(state: DecksState, options: ProjectWorkspaceGraphOptions = {}): WorkspaceGraph {
+  const deck = activeDeck(state, options.slug)
+  const builder: GraphBuilder = { nodes: new Map(), edges: new Map() }
+
+  for (const material of state.workspace.sourceMaterials ?? []) addSourceMaterial(builder, material)
+  for (const axis of deck.researchPlan ?? []) addResearchFinding(builder, axis)
+
+  const narrativeId = addNarrative(builder, deck)
+  for (const slide of deck.slides.slice().sort((a, b) => a.index - b.index)) addSlide(builder, slide)
+  for (const slide of deck.slides.slice().sort((a, b) => a.index - b.index)) addSlideClaimsAndEvidence(builder, slide)
+  const targets = renderTargetsForDeck(state, deck)
+  for (const target of targets) addArtifact(builder, deck, target, narrativeId, targets)
+
+  return normalizeGraph(builder)
+}
+
+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 workspace graph projection.")
+  return state.decks[key]
+}
+
+function addSourceMaterial(builder: GraphBuilder, material: SourceMaterial): void {
+  const sourceId = sourceNodeId(material.path || material.fingerprint || "unknown-source")
+  addNode(builder, {
+    id: sourceId,
+    type: "source",
+    label: material.path,
+    data: compactData({
+      path: material.path,
+      type: material.type,
+      size: material.size,
+      fingerprint: material.fingerprint,
+      status: material.status,
+      summary: material.summary,
+      bestUsedFor: material.bestUsedFor,
+    }),
+  })
+
+  const extraction = material.extraction
+  if (!extraction) return
+  const extractionKey = extraction.manifestPath || extraction.textPath || extraction.cacheDir
+  if (!extractionKey) return
+
+  const extractionId = extractionNodeId(extractionKey)
+  addNode(builder, {
+    id: extractionId,
+    type: "extraction",
+    label: extractionKey,
+    data: compactData(extraction),
+  })
+  addEdge(builder, "extracted_as", sourceId, extractionId)
+}
+
+function addResearchFinding(builder: GraphBuilder, axis: ResearchAxis): void {
+  if (!axis.findingsFile?.trim()) return
+  const id = findingNodeId(axis.findingsFile)
+  addNode(builder, {
+    id,
+    type: "finding",
+    label: axis.findingsFile,
+    data: compactData({
+      axis: axis.axis,
+      needed: axis.needed,
+      status: axis.status,
+      findingsFile: axis.findingsFile,
+      notes: axis.notes,
+      sourceKind: "researchPlan",
+    }),
+  })
+}
+
+function addNarrative(builder: GraphBuilder, deck: DeckSpec): string | undefined {
+  const brief = deck.narrativeBrief
+  if (!hasNarrativeBrief(brief)) return undefined
+
+  const narrativeId = `narrative:${stableHash(deck.slug)}`
+  addNode(builder, {
+    id: narrativeId,
+    type: "narrativeIntent",
+    label: deck.goal || deck.slug,
+    data: compactData({
+      goal: deck.goal,
+      audience: deck.audience,
+      language: deck.language,
+      audienceBeliefBefore: brief?.audienceBeliefBefore,
+      audienceBeliefAfter: brief?.audienceBeliefAfter,
+      decisionOrAction: brief?.decisionOrAction,
+      narrativeArc: brief?.narrativeArc,
+      keyClaims: brief?.keyClaims,
+    }),
+  })
+
+  for (const objection of brief?.objections ?? []) {
+    const objectionId = `objection:${stableHash(objection)}`
+    addNode(builder, { id: objectionId, type: "objection", label: objection, data: { text: objection } })
+    addEdge(builder, "contains", narrativeId, objectionId)
+    addEdge(builder, "challenges", objectionId, narrativeId)
+  }
+
+  for (const risk of brief?.risks ?? []) {
+    const riskId = `risk:${stableHash(risk)}`
+    addNode(builder, { id: riskId, type: "risk", label: risk, data: { text: risk } })
+    addEdge(builder, "contains", narrativeId, riskId)
+    addEdge(builder, "constrained_by", narrativeId, riskId)
+  }
+
+  return narrativeId
+}
+
+function addSlide(builder: GraphBuilder, slide: SlideSpec): void {
+  addNode(builder, {
+    id: slideNodeId(slide.index),
+    type: "slide",
+    label: slide.title,
+    data: compactData({
+      index: slide.index,
+      title: slide.title,
+      purpose: slide.purpose,
+      narrativeRole: slide.narrativeRole,
+      layout: slide.layout,
+      components: slide.components,
+      status: slide.status,
+    }),
+  })
+}
+
+function addSlideClaimsAndEvidence(builder: GraphBuilder, slide: SlideSpec): void {
+  const slideId = slideNodeId(slide.index)
+  const claims = claimCandidates(slide)
+  const claimIds = claims.map((claim) => addClaim(builder, slide, claim))
+
+  for (const claimId of claimIds) {
+    addEdge(builder, "contains", slideId, claimId)
+    addEdge(builder, "appears_in", claimId, slideId)
+  }
+
+  for (const evidence of slide.evidence ?? []) {
+    const supportId = addEvidenceSupportNode(builder, evidence)
+    for (const claimId of claimIds) {
+      addEdge(builder, "supports", supportId, claimId, compactData({
+        slideIndex: slide.index,
+        detailLevel: hasEvidenceDetail(evidence) ? "detailed" : "weak",
+        source: evidence.source,
+        quote: evidence.quote,
+        page: evidence.page,
+        url: evidence.url,
+        sourcePath: evidence.sourcePath,
+        location: evidence.location,
+        findingsFile: evidence.findingsFile,
+        caveat: evidence.caveat,
+        extractedTextPath: evidence.extractedTextPath,
+        extractedManifestPath: evidence.extractedManifestPath,
+      }))
+    }
+  }
+}
+
+function addClaim(builder: GraphBuilder, slide: SlideSpec, claim: { origin: string; text: string }): string {
+  const id = claimNodeId(slide.index, claim.text)
+  addNode(builder, {
+    id,
+    type: "claim",
+    label: claim.text,
+    data: compactData({
+      slideIndex: slide.index,
+      slideTitle: slide.title,
+      origin: claim.origin,
+      text: claim.text,
+    }),
+  })
+  return id
+}
+
+function addEvidenceSupportNode(builder: GraphBuilder, evidence: EvidenceRef): string {
+  if (evidence.findingsFile?.trim()) {
+    const id = findingNodeId(evidence.findingsFile)
+    addNode(builder, {
+      id,
+      type: "finding",
+      label: evidence.findingsFile,
+      data: compactData({ findingsFile: evidence.findingsFile, source: evidence.source, quote: evidence.quote, location: evidence.location, caveat: evidence.caveat }),
+    })
+    return id
+  }
+
+  const sourceKey = evidence.sourcePath || evidence.source || evidence.url || "unknown-evidence-source"
+  const id = sourceNodeId(sourceKey)
+  addNode(builder, {
+    id,
+    type: "source",
+    label: sourceKey,
+    data: compactData({ source: evidence.source, sourcePath: evidence.sourcePath, url: evidence.url }),
+  })
+
+  if (evidence.extractedTextPath || evidence.extractedManifestPath) {
+    const extractionKey = evidence.extractedTextPath || evidence.extractedManifestPath
+    const extractionId = extractionNodeId(extractionKey ?? sourceKey)
+    addNode(builder, {
+      id: extractionId,
+      type: "extraction",
+      label: extractionKey,
+      data: compactData({ textPath: evidence.extractedTextPath, manifestPath: evidence.extractedManifestPath }),
+    })
+    addEdge(builder, "extracted_as", id, extractionId)
+  }
+
+  return id
+}
+
+function addArtifact(builder: GraphBuilder, deck: DeckSpec, target: RenderTarget, narrativeId: string | undefined, targets: RenderTarget[]): void {
+  const artifactId = artifactNodeId(target.outputPath ?? deck.outputPath)
+  addNode(builder, {
+    id: artifactId,
+    type: "artifact",
+    label: target.outputPath ?? deck.outputPath,
+    data: compactData({
+      renderTargetId: target.id,
+      type: target.type,
+      outputPath: target.outputPath ?? deck.outputPath,
+      slug: deck.slug,
+      status: deck.status,
+      artifactVersion: target.artifactVersion,
+      contractStatus: target.contractStatus,
+    }),
+  })
+
+  if (narrativeId) addEdge(builder, "renders_from", artifactId, narrativeId)
+  const sourceNodeIds = target.sourceNodeIds.length > 0 ? target.sourceNodeIds : deck.slides.map((slide) => slideNodeId(slide.index))
+  for (const sourceNodeId of sourceNodeIds) addEdge(builder, "renders_from", artifactId, resolveRenderSourceNodeId(sourceNodeId, targets))
+}
+
+function renderTargetsForDeck(state: DecksState, deck: DeckSpec): RenderTarget[] {
+  const deckOutputPath = normalizePath(deck.outputPath)
+  const htmlTargetId = renderTargetId("html_deck", deckOutputPath)
+  const htmlArtifactId = artifactNodeId(deckOutputPath)
+  const targets = (state.renderTargets ?? []).filter((target) => {
+    if (target.id === htmlTargetId) return true
+    if (target.type === "html_deck") return normalizePath(target.outputPath ?? "") === deckOutputPath
+    const data = target.data ?? {}
+    return data.sourceTargetId === htmlTargetId ||
+      data.sourceOutputPath === deckOutputPath ||
+      target.sourceNodeIds.includes(htmlTargetId) ||
+      target.sourceNodeIds.includes(htmlArtifactId)
+  })
+  const htmlTarget = targets.find((target) => target.id === htmlTargetId) ?? fallbackHtmlDeckRenderTarget(deck)
+  if (!targets.some((target) => target.id === htmlTarget.id)) targets.push(htmlTarget)
+  return targets.sort((a, b) => a.id.localeCompare(b.id))
+}
+
+function resolveRenderSourceNodeId(sourceNodeId: string, targets: RenderTarget[]): string {
+  if (!sourceNodeId.startsWith("target:")) return sourceNodeId
+  const target = targets.find((item) => item.id === sourceNodeId)
+  return target ? artifactNodeId(target.outputPath ?? target.id) : sourceNodeId
+}
+
+function fallbackHtmlDeckRenderTarget(deck: DeckSpec): RenderTarget {
+  return {
+    id: renderTargetId("html_deck", deck.outputPath),
+    type: "html_deck",
+    outputPath: deck.outputPath,
+    sourceNodeIds: deck.slides.map((slide) => slideNodeId(slide.index)),
+    contractStatus: "unknown",
+    data: { slug: deck.slug, compatibilityOutputPath: deck.outputPath },
+  }
+}
+
+function claimCandidates(slide: SlideSpec): Array<{ origin: string; text: string }> {
+  const claims: Array<{ origin: string; text: string }> = []
+  pushClaim(claims, "title", slide.title)
+  pushClaim(claims, "purpose", slide.purpose)
+  pushClaim(claims, "headline", slide.content?.headline)
+  for (const item of slide.content?.body ?? []) pushClaim(claims, "body", item)
+  for (const item of slide.content?.bullets ?? []) pushClaim(claims, "bullet", item)
+  return claims
+}
+
+function pushClaim(claims: Array<{ origin: string; text: string }>, origin: string, text: string | undefined): void {
+  const value = cleanOptionalText(text)
+  if (!value) return
+  if (claims.some((claim) => claim.text === value)) return
+  claims.push({ origin, text: value })
+}
+
+function hasNarrativeBrief(brief: NarrativeBrief | undefined): boolean {
+  return Boolean(
+    brief?.audienceBeliefBefore?.trim() ||
+      brief?.audienceBeliefAfter?.trim() ||
+      brief?.decisionOrAction?.trim() ||
+      brief?.narrativeArc?.trim() ||
+      brief?.keyClaims.length ||
+      brief?.objections.length ||
+      brief?.risks.length,
+  )
+}
+
+function hasEvidenceDetail(evidence: EvidenceRef): boolean {
+  return Boolean(
+    evidence.quote?.trim() ||
+      evidence.page?.trim() ||
+      evidence.location?.trim() ||
+      evidence.url?.trim() ||
+      evidence.findingsFile?.trim() ||
+      evidence.sourcePath?.trim() ||
+      evidence.extractedTextPath?.trim(),
+  )
+}
+
+function addNode(builder: GraphBuilder, node: GraphNode): void {
+  const existing = builder.nodes.get(node.id)
+  if (!existing) {
+    builder.nodes.set(node.id, cleanNode(node))
+    return
+  }
+  builder.nodes.set(node.id, cleanNode({
+    ...existing,
+    label: existing.label || node.label,
+    data: compactData({ ...(existing.data ?? {}), ...(node.data ?? {}) }),
+  }))
+}
+
+function addEdge(builder: GraphBuilder, type: GraphEdgeType, from: string, to: string, data?: Record<string, unknown>): void {
+  const cleanedData = compactData(data ?? {})
+  const edge: GraphEdge = {
+    id: edgeId(type, from, to, cleanedData),
+    type,
+    from,
+    to,
+    ...(Object.keys(cleanedData).length > 0 ? { data: cleanedData } : {}),
+  }
+  builder.edges.set(edge.id, edge)
+}
+
+function normalizeGraph(builder: GraphBuilder): WorkspaceGraph {
+  const nodes = [...builder.nodes.values()].sort((a, b) => a.id.localeCompare(b.id))
+  return {
+    nodes: Object.fromEntries(nodes.map((node) => [node.id, node])),
+    edges: [...builder.edges.values()].sort((a, b) => a.id.localeCompare(b.id)),
+  }
+}
+
+function cleanNode(node: GraphNode): GraphNode {
+  const data = compactData(node.data ?? {})
+  return {
+    id: node.id,
+    type: node.type as GraphNodeType,
+    ...(node.label ? { label: node.label } : {}),
+    ...(Object.keys(data).length > 0 ? { data } : {}),
+  }
+}
+
+function compactData(input: Record<string, unknown>): Record<string, unknown> {
+  const output: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined || value === null) continue
+    if (typeof value === "string" && value.trim() === "") continue
+    if (Array.isArray(value) && value.length === 0) continue
+    output[key] = value
+  }
+  return output
+}
+
+function sourceNodeId(value: string): string {
+  return `source:${stablePathOrHash(value)}`
+}
+
+function extractionNodeId(value: string): string {
+  return `extraction:${stablePathOrHash(value)}`
+}
+
+function findingNodeId(value: string): string {
+  return `finding:${stablePathOrHash(value)}`
+}
+
+function claimNodeId(slideIndex: number, text: string): string {
+  return `claim:${slideIndex}:${stableHash(normalizeText(text))}`
+}
+
+function slideNodeId(index: number): string {
+  return `slide:${index}`
+}
+
+function artifactNodeId(outputPath: string): string {
+  return `artifact:${stablePathOrHash(outputPath)}`
+}
+
+function edgeId(type: GraphEdgeType, from: string, to: string, data: Record<string, unknown>): string {
+  return `edge:${type}:${stableHash(JSON.stringify({ from, to, data }))}`
+}
+
+function stablePathOrHash(value: string): string {
+  const normalized = normalizePath(value)
+  if (/^[a-z0-9._/-]+$/i.test(normalized) && normalized.length <= 80) return normalized
+  return stableHash(normalized)
+}
+
+function stableHash(value: string): string {
+  return createHash("sha1").update(value).digest("hex").slice(0, 12)
+}
+
+function normalizePath(value: string): string {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "")
+}
+
+function normalizeText(value: string): string {
+  return value.trim().replace(/\s+/g, " ").toLowerCase()
+}
+
+function cleanOptionalText(value: string | undefined): string | undefined {
+  const text = String(value ?? "").trim()
+  return text || undefined
+}