@cyber-dash-tech/revela 0.16.3 → 0.17.0

package/lib/narrative-vault/auto-compile.ts

@@ -0,0 +1,134 @@
+import { DECKS_STATE_FILE } from "../decks-state"
+import { compileCacheMirrorNarrativeVault } from "./compile-mirror"
+import { narrativeVaultCachePath } from "./paths"
+import type { VaultDiagnosticDisplay } from "./diagnostic-report"
+import { runNarrativeMarkdownQa, type MarkdownQaReport } from "./markdown-qa"
+
+export interface AutoCompileNarrativeVaultResult {
+  ok: boolean
+  mirrored: "updated" | "skipped_no_decks" | "preserved_failed_compile" | "failed"
+  cachePath: string
+  touched: string[]
+  markdownQa?: MarkdownQaReport
+  error?: string
+  markdown: string
+}
+
+export function autoCompileNarrativeVault(workspaceRoot: string, touched: string[]): AutoCompileNarrativeVaultResult {
+  const uniqueTouched = [...new Set(touched)].sort()
+  const cachePath = relativeCachePath(workspaceRoot)
+
+  try {
+    const markdownQa = runNarrativeMarkdownQa(workspaceRoot, uniqueTouched)
+    const compiled = compileCacheMirrorNarrativeVault(workspaceRoot)
+    const mirrored = compiled.mirrorStatus
+    const ok = compiled.result.ok && markdownQa.ok
+
+    return {
+      ok,
+      mirrored,
+      cachePath,
+      touched: uniqueTouched,
+      markdownQa,
+      markdown: formatAutoCompileReport({
+        ok,
+        mirrored,
+        cachePath,
+        touched: uniqueTouched,
+        markdownQa,
+        blockers: compiled.diagnosticReport.blockers,
+        warnings: compiled.diagnosticReport.warnings,
+      }),
+    }
+  } catch (e) {
+    const error = e instanceof Error ? e.message : String(e)
+    return {
+      ok: false,
+      mirrored: "failed",
+      cachePath,
+      touched: uniqueTouched,
+      error,
+      markdown: formatAutoCompileReport({ ok: false, mirrored: "failed", cachePath, touched: uniqueTouched, error }),
+    }
+  }
+}
+
+export function formatAutoCompileReport(input: {
+  ok: boolean
+  mirrored: AutoCompileNarrativeVaultResult["mirrored"]
+  cachePath: string
+  touched: string[]
+  markdownQa?: MarkdownQaReport
+  blockers?: VaultDiagnosticDisplay[]
+  warnings?: VaultDiagnosticDisplay[]
+  error?: string
+}): string {
+  const lines = ["**[revela narrative vault]** Auto-compile completed.", ""]
+  lines.push(`Status: ${input.ok ? "ok" : "blocked"}`)
+  lines.push(`State: ${mirrorLabel(input.mirrored)}`)
+  lines.push(`Cache: \`${input.cachePath}\``)
+  lines.push(`Touched Markdown: ${formatTouched(input.touched)}`)
+
+  if (input.error) lines.push("", `Hook error: ${input.error}`)
+  appendMarkdownQa(lines, input.markdownQa)
+  appendDiagnostics(lines, "Blockers", input.blockers ?? [])
+  appendDiagnostics(lines, "Warnings", input.warnings ?? [])
+  return lines.join("\n")
+}
+
+function appendMarkdownQa(lines: string[], report?: MarkdownQaReport): void {
+  if (!report) return
+  const total = report.repairCards.length
+  lines.push(`Markdown QA: ${report.ok ? "clean" : "blocked"}${total > 0 ? ` (${report.blockers.length} blocker(s), ${report.warnings.length} warning(s))` : ""}`)
+  appendRepairCards(lines, "Markdown QA blockers", report.blockers)
+  appendRepairCards(lines, "Markdown QA warnings", report.warnings)
+}
+
+function appendRepairCards(lines: string[], label: string, cards: MarkdownQaReport["repairCards"]): void {
+  const shown = cards.slice(0, 8)
+  if (shown.length === 0) return
+  lines.push("", `${label}:`)
+  for (const card of shown) {
+    const location = [card.file, card.nodeId].filter(Boolean).join(" / ")
+    lines.push(`- \`${card.issueCode}\`${location ? ` (${location})` : ""}: ${card.message} Smallest repair: ${card.smallestRepair}`)
+  }
+  if (cards.length > shown.length) lines.push(`- ... ${cards.length - shown.length} more`)
+}
+
+function appendDiagnostics(lines: string[], label: string, diagnostics: VaultDiagnosticDisplay[]): void {
+  const shown = diagnostics.slice(0, 8)
+  if (shown.length === 0) return
+  lines.push("", `${label}:`)
+  for (const diagnostic of shown) lines.push(`- ${formatDiagnostic(diagnostic)}`)
+  if (diagnostics.length > shown.length) lines.push(`- ... ${diagnostics.length - shown.length} more`)
+}
+
+function formatDiagnostic(diagnostic: VaultDiagnosticDisplay): string {
+  const location = [diagnostic.file, diagnostic.nodeId].filter(Boolean).join(" / ")
+  return `\`${diagnostic.code}\`${location ? ` (${location})` : ""}: ${diagnostic.message}`
+}
+
+function formatTouched(touched: string[]): string {
+  const shown = touched.slice(0, 10).map((target) => `\`${target}\``)
+  if (touched.length > 10) shown.push(`... ${touched.length - 10} more`)
+  return shown.length > 0 ? shown.join(", ") : "none"
+}
+
+function mirrorLabel(mirrored: AutoCompileNarrativeVaultResult["mirrored"]): string {
+  switch (mirrored) {
+    case "updated":
+      return `${DECKS_STATE_FILE} render state saved; runtime narrative hydrated from vault`
+    case "skipped_no_decks":
+      return `${DECKS_STATE_FILE} not found; no state created`
+    case "preserved_failed_compile":
+      return `${DECKS_STATE_FILE} render state preserved; last-good narrative cache kept because compile is blocked`
+    case "failed":
+      return "not updated because auto-compile failed"
+  }
+}
+
+function relativeCachePath(workspaceRoot: string): string {
+  const cachePath = narrativeVaultCachePath(workspaceRoot).replace(/\\/g, "/")
+  const root = workspaceRoot.replace(/\\/g, "/").replace(/\/$/, "")
+  return cachePath.startsWith(root + "/") ? cachePath.slice(root.length + 1) : cachePath
+}

package/lib/narrative-vault/bootstrap.ts

@@ -0,0 +1,63 @@
+import { mkdirSync, writeFileSync } from "fs"
+import { dirname, join } from "path"
+import { narrativeVaultPath } from "./paths"
+import type { AudienceIntent, DecisionIntent, NarrativeStateV1, NarrativeThesis } from "../narrative-state/types"
+
+export interface InitNarrativeVaultInput {
+  id?: string
+  status?: NarrativeStateV1["status"]
+  audience?: Partial<AudienceIntent>
+  decision?: Partial<DecisionIntent>
+  thesis?: Partial<NarrativeThesis>
+}
+
+export interface InitNarrativeVaultResult {
+  ok: boolean
+  files: string[]
+  created: boolean
+  path: string
+}
+
+const VAULT_NODE_DIRS = ["claims", "evidence", "objections", "risks", "research-gaps"]
+
+export function initNarrativeVault(workspaceRoot: string, input: InitNarrativeVaultInput = {}): InitNarrativeVaultResult {
+  const root = narrativeVaultPath(workspaceRoot)
+  const files: string[] = []
+  mkdirSync(root, { recursive: true })
+  for (const dir of VAULT_NODE_DIRS) mkdirSync(join(root, dir), { recursive: true })
+
+  write(root, files, "index.md", frontmatter({ type: "index", id: input.id ?? "narrative:workspace", status: input.status ?? "draft" }))
+  write(root, files, "audience.md", `${frontmatter({ type: "audience", ...input.audience })}${input.audience?.primary ?? ""}\n`)
+  write(root, files, "decision.md", `${frontmatter({ type: "decision", ...input.decision })}${input.decision?.action ?? ""}\n`)
+  write(root, files, "thesis.md", `${frontmatter({ type: "thesis", id: input.thesis?.id ?? "thesis:main", confidence: input.thesis?.confidence ?? "medium", caveat: input.thesis?.caveat })}${input.thesis?.statement ?? ""}\n`)
+
+  return { ok: true, files, created: true, path: "revela-narrative" }
+}
+
+function write(root: string, files: string[], relativePath: string, content: string): void {
+  const filePath = join(root, relativePath)
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, content.endsWith("\n") ? content : `${content}\n`, "utf-8")
+  files.push(relativePath.split(/[/\\]+/).join("/"))
+}
+
+function frontmatter(values: Record<string, unknown>): string {
+  const lines = ["---"]
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined || value === "" || (Array.isArray(value) && value.length === 0)) continue
+    if (Array.isArray(value)) {
+      lines.push(`${key}:`)
+      for (const item of value) lines.push(`  - ${quote(String(item))}`)
+    } else if (typeof value === "boolean") {
+      lines.push(`${key}: ${value ? "true" : "false"}`)
+    } else {
+      lines.push(`${key}: ${quote(String(value))}`)
+    }
+  }
+  lines.push("---", "")
+  return lines.join("\n")
+}
+
+function quote(value: string): string {
+  return JSON.stringify(value)
+}

package/lib/narrative-vault/cache.ts

@@ -0,0 +1,14 @@
+import { mkdirSync, writeFileSync } from "fs"
+import { join } from "path"
+import { narrativeVaultCachePath } from "./paths"
+import type { NarrativeVaultCompileResult } from "./types"
+
+export function writeNarrativeVaultCache(workspaceRoot: string, result: NarrativeVaultCompileResult): void {
+  const cacheDir = narrativeVaultCachePath(workspaceRoot)
+  mkdirSync(cacheDir, { recursive: true })
+  if (result.ok && result.narrative) {
+    writeFileSync(join(cacheDir, "compiled-narrative.json"), JSON.stringify(result.narrative, null, 2) + "\n", "utf-8")
+    writeFileSync(join(cacheDir, "graph.json"), JSON.stringify(result.graph, null, 2) + "\n", "utf-8")
+  }
+  writeFileSync(join(cacheDir, "diagnostics.json"), JSON.stringify(result.diagnostics, null, 2) + "\n", "utf-8")
+}

package/lib/narrative-vault/compile-mirror.ts

@@ -0,0 +1,45 @@
+import { existsSync } from "fs"
+import { join } from "path"
+import { DECKS_STATE_FILE, readDecksState, writeDecksState, type DecksState } from "../decks-state"
+import type { NarrativeApproval } from "../narrative-state/types"
+import { writeNarrativeVaultCache } from "./cache"
+import { compileNarrativeVault } from "./compile"
+import { formatVaultDiagnosticReport, type VaultDiagnosticReport } from "./diagnostic-report"
+import type { NarrativeVaultCompileResult } from "./types"
+
+export type NarrativeVaultMirrorStatus = "updated" | "skipped_no_decks" | "preserved_failed_compile"
+
+export interface CompileCacheMirrorNarrativeVaultOptions {
+  state?: DecksState
+  fallbackApprovals?: NarrativeApproval[]
+}
+
+export interface CompileCacheMirrorNarrativeVaultResult {
+  result: NarrativeVaultCompileResult
+  diagnosticReport: VaultDiagnosticReport
+  mirrorStatus: NarrativeVaultMirrorStatus
+  state?: DecksState
+}
+
+export function compileCacheMirrorNarrativeVault(
+  workspaceRoot: string,
+  options: CompileCacheMirrorNarrativeVaultOptions = {},
+): CompileCacheMirrorNarrativeVaultResult {
+  const decksPath = join(workspaceRoot, DECKS_STATE_FILE)
+  const hasDecks = Boolean(options.state) || existsSync(decksPath)
+  const state = options.state ?? (hasDecks ? readDecksState(workspaceRoot) : undefined)
+  const fallbackApprovals = options.fallbackApprovals ?? state?.narrativeApprovals ?? state?.narrative?.approvals ?? []
+  const result = compileNarrativeVault(workspaceRoot, { fallbackApprovals })
+  const diagnosticReport = formatVaultDiagnosticReport(result.diagnostics)
+
+  writeNarrativeVaultCache(workspaceRoot, result)
+
+  if (!hasDecks || !state) return { result, diagnosticReport, mirrorStatus: "skipped_no_decks" }
+  if (result.ok && result.narrative) {
+    state.narrative = result.narrative
+    writeDecksState(workspaceRoot, state)
+    return { result, diagnosticReport, mirrorStatus: "updated", state }
+  }
+
+  return { result, diagnosticReport, mirrorStatus: "preserved_failed_compile", state }
+}

package/lib/narrative-vault/compile.ts

@@ -0,0 +1,350 @@
+import { normalizeCanonicalNarrativeState } from "../narrative-state/normalize"
+import { computeNarrativeHash } from "../narrative-state/hash"
+import type {
+  AudienceIntent,
+  DecisionIntent,
+  NarrativeApproval,
+  NarrativeClaim,
+  NarrativeClaimKind,
+  NarrativeEvidenceBinding,
+  NarrativeObjection,
+  NarrativeResearchGap,
+  NarrativeResearchGapTargetType,
+  NarrativeRisk,
+  NarrativeStateV1,
+  NarrativeStatus,
+  NarrativeThesis,
+} from "../narrative-state/types"
+import { firstParagraphOrBody, parseMarkdownList } from "./markdown"
+import { readNarrativeVaultDocuments } from "./read"
+import type { NarrativeVaultCompileResult, NarrativeVaultGraph, VaultDiagnostic, VaultDocument, VaultNodeType, VaultRelation } from "./types"
+
+export interface CompileNarrativeVaultOptions {
+  fallbackApprovals?: NarrativeApproval[]
+  now?: string
+}
+
+export function compileNarrativeVault(workspaceRoot: string, options: CompileNarrativeVaultOptions = {}): NarrativeVaultCompileResult {
+  const read = readNarrativeVaultDocuments(workspaceRoot)
+  const diagnostics: VaultDiagnostic[] = [...read.diagnostics]
+  const docs = read.documents
+  if (docs.length === 0) {
+    return {
+      ok: false,
+      diagnostics: [{ severity: "error", code: "empty_vault", message: "revela-narrative/ exists but contains no Markdown narrative nodes." }],
+      graph: { nodes: [], relations: [] },
+    }
+  }
+  const nodeDocs = docs.filter((doc) => stringField(doc, "id"))
+  const duplicateIds = duplicateValues(nodeDocs.map((doc) => stringField(doc, "id")))
+  for (const id of duplicateIds) diagnostics.push({ severity: "error", code: "duplicate_id", message: `Duplicate narrative vault id: ${id}`, nodeId: id })
+
+  const byId = new Map<string, VaultDocument>()
+  for (const doc of nodeDocs) if (!byId.has(stringField(doc, "id"))) byId.set(stringField(doc, "id"), doc)
+  const claimIds = new Set(docs.filter((doc) => typeField(doc) === "claim").map((doc) => stringField(doc, "id")).filter(Boolean))
+
+  for (const doc of docs) {
+    if (!stringField(doc, "type")) diagnostics.push({ severity: "error", code: "missing_type", message: "Missing required frontmatter field: type", file: doc.relativePath })
+    else if (!isVaultNodeType(stringField(doc, "type"))) diagnostics.push({ severity: "error", code: "unknown_node_type", message: `Unknown narrative vault node type: ${stringField(doc, "type")}`, file: doc.relativePath, nodeId: stringField(doc, "id") })
+    if (requiresId(doc) && !stringField(doc, "id")) diagnostics.push({ severity: "error", code: "missing_id", message: "Missing required frontmatter field: id", file: doc.relativePath })
+  }
+
+  const relations = docs.flatMap((doc) => doc.relations)
+  const relationTargets = targetsFromRelations(relations, byId)
+  for (const relation of relations) {
+    const from = byId.get(relation.fromId)
+    const to = byId.get(relation.toId)
+    if (!from) {
+      diagnostics.push({ severity: "error", code: "broken_relation_source", message: `Relation starts from unknown node: ${relation.fromId}`, file: relation.file, nodeId: relation.fromId })
+      continue
+    }
+    if (!to) {
+      diagnostics.push({ severity: "error", code: "broken_link", message: `Relation points to unknown node: ${relation.toId}`, file: relation.file, nodeId: relation.fromId })
+      continue
+    }
+    const illegalReason = illegalRelationReason(typeField(from), typeField(to), relation.relation)
+    if (illegalReason) diagnostics.push({ severity: "error", code: "illegal_relation_target", message: illegalReason, file: relation.file, nodeId: relation.fromId })
+  }
+
+  for (const doc of docs.filter((item) => typeField(item) === "evidence")) {
+    const evidenceId = stringField(doc, "id")
+    const claimId = relationTargets.get(evidenceId)?.targetId || stringField(doc, "claimId") || ""
+    if (!claimId) {
+      diagnostics.push({ severity: "error", code: "evidence_claim_missing", message: `Evidence ${evidenceId || doc.relativePath} is missing a claim-support relation or compatibility claimId.`, file: doc.relativePath, nodeId: evidenceId })
+    } else if (!claimIds.has(claimId)) {
+      diagnostics.push({ severity: "error", code: "evidence_claim_missing", message: `Evidence ${evidenceId || doc.relativePath} references unknown claim ${claimId}.`, file: doc.relativePath, nodeId: evidenceId })
+    }
+  }
+
+  const narrative: Partial<NarrativeStateV1> = {
+    version: 1,
+    id: stringField(findType(docs, "index"), "id") || "narrative:workspace",
+    status: statusField(findType(docs, "index"), "status") ?? "draft",
+    audience: compileAudience(findType(docs, "audience")),
+    decision: compileDecision(findType(docs, "decision")),
+    thesis: compileThesis(findType(docs, "thesis")),
+    claims: docs.filter((doc) => typeField(doc) === "claim").map(compileClaim),
+    evidenceBindings: docs.filter((doc) => typeField(doc) === "evidence").map((doc) => compileEvidence(doc, relationTargets)),
+    objections: docs.filter((doc) => typeField(doc) === "objection").map((doc) => compileObjection(doc, relationTargets)),
+    risks: docs.filter((doc) => typeField(doc) === "risk").map((doc) => compileRisk(doc, relationTargets)),
+    researchGaps: docs.filter((doc) => typeField(doc) === "research-gap").map((doc) => compileResearchGap(doc, options.now, relationTargets)),
+    claimRelations: relations
+      .filter((relation) => byId.get(relation.fromId) && typeField(byId.get(relation.fromId)) === "claim" && byId.get(relation.toId) && typeField(byId.get(relation.toId)) === "claim")
+      .map((relation) => ({ id: relation.id ?? `${relation.fromId}:${relation.relation}:${relation.toId}`, fromClaimId: relation.fromId, toClaimId: relation.toId, relation: relation.relation, rationale: relation.rationale })),
+    approvals: options.fallbackApprovals ?? [],
+    updatedAt: options.now ?? new Date().toISOString(),
+  }
+
+  const normalized = normalizeCanonicalNarrativeState(narrative, "vault")
+  if (!normalized) diagnostics.push({ severity: "error", code: "compile_failed", message: "Narrative vault could not be normalized." })
+  if (normalized) addSemanticDiagnostics(normalized, diagnostics)
+  if (normalized && normalized.approvals.length > 0) {
+    const currentHash = computeNarrativeHash(normalized)
+    const latest = normalized.approvals[normalized.approvals.length - 1]
+    if (latest && latest.narrativeHash !== currentHash) diagnostics.push({ severity: "warning", code: "stale_approval_hash", message: "Latest narrative approval hash is stale.", nodeId: normalized.id })
+  }
+
+  const graph: NarrativeVaultGraph = {
+    nodes: nodeDocs.map((doc) => ({ id: stringField(doc, "id"), type: typeField(doc), file: doc.relativePath })),
+    relations,
+  }
+  return { ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error") && Boolean(normalized), narrative: normalized, diagnostics, graph }
+}
+
+function compileAudience(doc: VaultDocument | undefined): AudienceIntent {
+  return {
+    primary: stringField(doc, "primary") || firstParagraphOrBody(doc?.body ?? ""),
+    secondary: arrayField(doc, "secondary"),
+    beliefBefore: stringField(doc, "beliefBefore"),
+    beliefAfter: stringField(doc, "beliefAfter"),
+    decisionContext: stringField(doc, "decisionContext"),
+    successCriteria: arrayField(doc, "successCriteria"),
+  }
+}
+
+function compileDecision(doc: VaultDocument | undefined): DecisionIntent {
+  return {
+    action: stringField(doc, "action") || firstParagraphOrBody(doc?.body ?? ""),
+    owner: stringField(doc, "owner"),
+    deadline: stringField(doc, "deadline"),
+    decisionType: enumField(doc, "decisionType", ["approve", "invest", "prioritize", "align", "choose", "understand", "other"]),
+    consequenceOfNoDecision: stringField(doc, "consequenceOfNoDecision"),
+  }
+}
+
+function compileThesis(doc: VaultDocument | undefined): NarrativeThesis | undefined {
+  if (!doc) return undefined
+  return { id: stringField(doc, "id") || "thesis:main", statement: stringField(doc, "statement") || firstParagraphOrBody(doc.body), confidence: enumField(doc, "confidence", ["high", "medium", "low"]) ?? "medium", caveat: stringField(doc, "caveat") }
+}
+
+function compileClaim(doc: VaultDocument): NarrativeClaim {
+  return {
+    id: stringField(doc, "id"),
+    kind: enumField(doc, "kind", ["context", "problem", "opportunity", "evidence", "recommendation", "risk", "assumption", "ask"]) ?? "evidence",
+    text: stringField(doc, "text") || firstParagraphOrBody(doc.body),
+    importance: enumField(doc, "importance", ["central", "supporting", "background"]) ?? "supporting",
+    evidenceRequired: booleanField(doc, "evidenceRequired", true),
+    evidenceStatus: "missing",
+    supportedScope: stringField(doc, "supportedScope"),
+    unsupportedScope: stringField(doc, "unsupportedScope"),
+    caveats: [...arrayField(doc, "caveats"), ...parseMarkdownList(doc.sections.caveats ?? "")],
+  }
+}
+
+type RelationTarget = { targetId: string; targetType?: NarrativeResearchGapTargetType; evidenceBindingIds?: string[] }
+
+function compileEvidence(doc: VaultDocument, relationTargets = new Map<string, RelationTarget>()): NarrativeEvidenceBinding {
+  return {
+    id: stringField(doc, "id"),
+    claimId: relationTargets.get(stringField(doc, "id"))?.targetId || stringField(doc, "claimId") || "",
+    source: stringField(doc, "source") || stringField(doc, "sourcePath") || stringField(doc, "findingsFile") || stringField(doc, "url"),
+    sourcePath: stringField(doc, "sourcePath"),
+    findingsFile: stringField(doc, "findingsFile"),
+    quote: stringField(doc, "quote") || firstParagraphOrBody(doc.body),
+    location: stringField(doc, "location"),
+    url: stringField(doc, "url"),
+    caveat: stringField(doc, "caveat"),
+    supportScope: stringField(doc, "supportScope"),
+    unsupportedScope: stringField(doc, "unsupportedScope"),
+    strength: enumField(doc, "strength", ["strong", "partial", "weak"]) ?? "weak",
+  }
+}
+
+function compileObjection(doc: VaultDocument, relationTargets = new Map<string, RelationTarget>()): NarrativeObjection {
+  return { id: stringField(doc, "id"), text: stringField(doc, "text") || firstParagraphOrBody(doc.body), claimId: relationTargets.get(stringField(doc, "id"))?.targetId || stringField(doc, "claimId") || "", priority: enumField(doc, "priority", ["high", "medium", "low"]) ?? "medium", response: stringField(doc, "response") || firstParagraphOrBody(doc.sections.response ?? "") }
+}
+
+function compileRisk(doc: VaultDocument, relationTargets = new Map<string, RelationTarget>()): NarrativeRisk {
+  return { id: stringField(doc, "id"), text: stringField(doc, "text") || firstParagraphOrBody(doc.body), claimId: relationTargets.get(stringField(doc, "id"))?.targetId || stringField(doc, "claimId") || "", severity: enumField(doc, "severity", ["high", "medium", "low"]) ?? "medium", mitigation: stringField(doc, "mitigation") || firstParagraphOrBody(doc.sections.mitigation ?? "") }
+}
+
+function compileResearchGap(doc: VaultDocument, now = new Date().toISOString(), relationTargets = new Map<string, RelationTarget>()): NarrativeResearchGap {
+  const relationTarget = relationTargets.get(stringField(doc, "id"))
+  return {
+    id: stringField(doc, "id"),
+    targetType: relationTarget?.targetType ?? enumField(doc, "targetType", ["claim", "objection", "risk", "decision", "narrative"]) ?? "narrative",
+    targetId: relationTarget?.targetId || stringField(doc, "targetId") || "",
+    question: stringField(doc, "question") || firstParagraphOrBody(doc.body),
+    status: enumField(doc, "status", ["open", "in_progress", "findings_saved", "attached", "evidence_bound", "closed"]) ?? "open",
+    priority: enumField(doc, "priority", ["high", "medium", "low"]) ?? "medium",
+    findingsFile: stringField(doc, "findingsFile"),
+    evidenceBindingIds: unique([...(relationTarget?.evidenceBindingIds ?? []), ...arrayField(doc, "evidenceBindingIds")]),
+    notes: stringField(doc, "notes") || firstParagraphOrBody(doc.sections.notes ?? ""),
+    createdAt: stringField(doc, "createdAt") || now,
+    updatedAt: stringField(doc, "updatedAt") || now,
+    closedAt: stringField(doc, "closedAt"),
+  }
+}
+
+function addSemanticDiagnostics(narrative: NarrativeStateV1, diagnostics: VaultDiagnostic[]): void {
+  const claimIds = new Set(narrative.claims.map((claim) => claim.id))
+  const evidenceIds = new Set(narrative.evidenceBindings.map((binding) => binding.id))
+  for (const binding of narrative.evidenceBindings) {
+    if (!binding.source || !binding.quote || !binding.supportScope || !binding.unsupportedScope || !binding.caveat) diagnostics.push({ severity: "warning", code: "evidence_trace_incomplete", message: `Evidence node ${binding.id} is missing source trace, quote, scope, unsupported scope, or caveat.`, nodeId: binding.id })
+    if (!claimIds.has(binding.claimId)) diagnostics.push({ severity: "error", code: "evidence_claim_missing", message: `Evidence ${binding.id} references unknown claim ${binding.claimId}.`, nodeId: binding.id })
+  }
+  for (const claim of narrative.claims) {
+    if (claim.importance === "central" && !narrative.claimRelations?.some((relation) => relation.fromClaimId === claim.id || relation.toClaimId === claim.id) && narrative.claims.length > 1) diagnostics.push({ severity: "warning", code: "orphan_central_claim", message: `Central claim ${claim.id} has no claim relations.`, nodeId: claim.id })
+    if (claim.evidenceRequired && !narrative.evidenceBindings.some((binding) => binding.claimId === claim.id)) diagnostics.push({ severity: "warning", code: "claim_missing_evidence", message: `Evidence-required claim ${claim.id} has no evidence binding.`, nodeId: claim.id })
+  }
+  for (const gap of narrative.researchGaps ?? []) {
+    if (gap.status !== "closed") diagnostics.push({ severity: "warning", code: "research_gap_unresolved", message: `Research gap ${gap.id} is unresolved.`, nodeId: gap.id })
+    for (const id of gap.evidenceBindingIds ?? []) if (!evidenceIds.has(id)) diagnostics.push({ severity: "warning", code: "gap_evidence_missing", message: `Research gap ${gap.id} references unknown evidence ${id}.`, nodeId: gap.id })
+  }
+}
+
+function findType(docs: VaultDocument[], type: VaultNodeType): VaultDocument | undefined {
+  return docs.find((doc) => typeField(doc) === type)
+}
+
+function typeField(doc: VaultDocument | undefined): VaultNodeType {
+  const value = stringField(doc, "type")
+  if (isVaultNodeType(value)) return value
+  return "index"
+}
+
+function isVaultNodeType(value: string): value is VaultNodeType {
+  return value === "research-gap" || ["index", "audience", "decision", "thesis", "claim", "evidence", "objection", "risk"].includes(value)
+}
+
+function illegalRelationReason(fromType: VaultNodeType, toType: VaultNodeType, relation: string): string | undefined {
+  if (fromType !== "claim") {
+    const allowedNonClaim: Record<string, VaultNodeType[]> = {
+      evidence: relation === "supports" ? ["claim"] : [],
+      objection: relation === "answers" || relation === "contrasts_with" ? ["claim"] : [],
+      risk: relation === "constrains" ? ["claim"] : [],
+      "research-gap": relation === "depends_on" ? ["claim", "evidence", "objection", "risk"] : [],
+      index: [],
+      audience: [],
+      decision: [],
+      thesis: [],
+      claim: [],
+    }
+    if (allowedNonClaim[fromType]?.includes(toType)) return undefined
+    return `Relation ${relation} from ${fromType} cannot target ${toType}.`
+  }
+  const allowedTargets: Record<string, VaultNodeType[]> = {
+    leads_to: ["claim"],
+    supports: ["claim"],
+    contrasts_with: ["claim"],
+    depends_on: ["claim", "evidence"],
+    constrains: ["claim", "risk"],
+    answers: ["claim", "objection"],
+  }
+  if (!allowedTargets[relation]?.includes(toType)) return `Relation ${relation} from a claim cannot target ${toType}.`
+  return undefined
+}
+
+function targetsFromRelations(relations: VaultRelation[], byId: Map<string, VaultDocument>): Map<string, RelationTarget> {
+  const targets = new Map<string, RelationTarget>()
+  for (const relation of relations) {
+    const from = byId.get(relation.fromId)
+    const to = byId.get(relation.toId)
+    if (!from || !to) continue
+    const fromType = typeField(from)
+    const targetType = researchGapTargetType(typeField(to))
+    if (fromType === "evidence" && relation.relation === "supports" && targetType === "claim") targets.set(relation.fromId, { targetId: relation.toId, targetType })
+    if (fromType === "objection" && (relation.relation === "answers" || relation.relation === "contrasts_with") && targetType === "claim") targets.set(relation.fromId, { targetId: relation.toId, targetType })
+    if (fromType === "risk" && relation.relation === "constrains" && targetType === "claim") targets.set(relation.fromId, { targetId: relation.toId, targetType })
+  }
+  for (const relation of relations) {
+    const from = byId.get(relation.fromId)
+    const to = byId.get(relation.toId)
+    if (!from || !to || typeField(from) !== "research-gap" || relation.relation !== "depends_on") continue
+    const toType = typeField(to)
+    if (toType === "evidence") {
+      const evidenceTarget = targets.get(relation.toId)
+      mergeRelationTarget(targets, relation.fromId, {
+        targetId: evidenceTarget?.targetId || relation.toId,
+        targetType: evidenceTarget?.targetType ?? "narrative",
+        evidenceBindingIds: [relation.toId],
+      })
+      continue
+    }
+    const targetType = researchGapTargetType(toType)
+    if (targetType) mergeRelationTarget(targets, relation.fromId, { targetId: relation.toId, targetType })
+  }
+  return targets
+}
+
+function mergeRelationTarget(targets: Map<string, RelationTarget>, id: string, next: RelationTarget): void {
+  const existing = targets.get(id)
+  if (!existing) {
+    targets.set(id, next)
+    return
+  }
+  targets.set(id, {
+    targetId: existing.targetType === "claim" ? existing.targetId : next.targetId || existing.targetId,
+    targetType: existing.targetType === "claim" ? existing.targetType : next.targetType ?? existing.targetType,
+    evidenceBindingIds: unique([...(existing.evidenceBindingIds ?? []), ...(next.evidenceBindingIds ?? [])]),
+  })
+}
+
+function researchGapTargetType(type: VaultNodeType): NarrativeResearchGapTargetType | undefined {
+  if (type === "claim" || type === "objection" || type === "risk") return type
+  return undefined
+}
+
+function requiresId(doc: VaultDocument): boolean {
+  return typeField(doc) !== "audience" && typeField(doc) !== "decision"
+}
+
+function stringField(doc: VaultDocument | undefined, key: string): string {
+  const value = doc?.frontmatter[key]
+  return typeof value === "string" ? value.trim() : ""
+}
+
+function arrayField(doc: VaultDocument | undefined, key: string): string[] {
+  const value = doc?.frontmatter[key]
+  if (Array.isArray(value)) return value.map((item) => item.trim()).filter(Boolean)
+  if (typeof value === "string" && value.trim()) return value.split(",").map((item) => item.trim()).filter(Boolean)
+  return []
+}
+
+function booleanField(doc: VaultDocument | undefined, key: string, fallback: boolean): boolean {
+  const value = doc?.frontmatter[key]
+  return typeof value === "boolean" ? value : fallback
+}
+
+function enumField<T extends string>(doc: VaultDocument | undefined, key: string, allowed: readonly T[]): T | undefined {
+  const value = stringField(doc, key)
+  return allowed.includes(value as T) ? value as T : undefined
+}
+
+function statusField(doc: VaultDocument | undefined, key: string): NarrativeStatus | undefined {
+  return enumField(doc, key, ["draft", "needs_research", "needs_user_confirmation", "ready_for_approval", "approved"])
+}
+
+function duplicateValues(values: string[]): string[] {
+  const seen = new Set<string>()
+  const duplicates = new Set<string>()
+  for (const value of values) {
+    if (seen.has(value)) duplicates.add(value)
+    seen.add(value)
+  }
+  return [...duplicates]
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))]
+}

package/lib/narrative-vault/constants.ts

@@ -0,0 +1,6 @@
+export const NARRATIVE_VAULT_DIR = "revela-narrative"
+export const NARRATIVE_VAULT_CACHE_DIR = ".opencode/revela/narrative-cache"
+
+export const NARRATIVE_VAULT_NODE_DIRS = ["claims", "evidence", "objections", "risks", "research-gaps"] as const
+
+export const NARRATIVE_VAULT_RELATION_TYPES = ["leads_to", "supports", "depends_on", "contrasts_with", "constrains", "answers"] as const