@cyber-dash-tech/revela 0.10.0 → 0.12.0

package/lib/workspace-state/render-targets.ts

@@ -0,0 +1,182 @@
+import { createHash } from "crypto"
+import { basename, dirname, extname, join } from "path"
+import type { DeckSpec, DecksState } from "../decks-state"
+import type { RenderTarget } from "./types"
+
+export type RenderTargetType = RenderTarget["type"]
+
+export function activeHtmlDeckRenderTarget(state: DecksState): RenderTarget | undefined {
+  const deck = activeDeck(state)
+  if (!deck) return undefined
+  const expectedPath = normalizeWorkspacePath(deck.outputPath)
+  return (state.renderTargets ?? []).find((target) =>
+    target.type === "html_deck" && normalizeWorkspacePath(target.outputPath ?? "") === expectedPath
+  )
+}
+
+export function ensureActiveHtmlDeckRenderTarget(state: DecksState): RenderTarget | undefined {
+  const deck = activeDeck(state)
+  if (!deck?.outputPath) return undefined
+  state.renderTargets ??= []
+
+  const target = createHtmlDeckRenderTarget(deck)
+  const index = state.renderTargets.findIndex((item) => item.id === target.id)
+  if (index >= 0) {
+    state.renderTargets[index] = mergeRenderTarget(state.renderTargets[index], target)
+  } else {
+    state.renderTargets.push(target)
+  }
+
+  state.renderTargets = sortRenderTargets(state.renderTargets)
+  return state.renderTargets.find((item) => item.id === target.id)
+}
+
+export function resolveActiveHtmlDeckPath(state: DecksState): string | undefined {
+  const target = activeHtmlDeckRenderTarget(state) ?? ensureActiveHtmlDeckRenderTarget(state)
+  if (target?.outputPath) return normalizeWorkspacePath(target.outputPath)
+  return activeDeck(state)?.outputPath ? normalizeWorkspacePath(activeDeck(state)?.outputPath ?? "") : undefined
+}
+
+export function upsertRenderTarget(state: DecksState, target: RenderTarget): DecksState {
+  state.renderTargets ??= []
+  const cleaned = cleanRenderTarget(target)
+  const index = state.renderTargets.findIndex((item) => item.id === cleaned.id)
+  if (index >= 0) state.renderTargets[index] = mergeRenderTarget(state.renderTargets[index], cleaned)
+  else state.renderTargets.push(cleaned)
+  state.renderTargets = sortRenderTargets(state.renderTargets)
+  return state
+}
+
+export function deriveExportRenderTarget(htmlTarget: RenderTarget, type: "pdf" | "pptx", outputPath: string): RenderTarget {
+  const normalizedOutput = normalizeWorkspacePath(outputPath)
+  return cleanRenderTarget({
+    id: renderTargetId(type, normalizedOutput),
+    type,
+    outputPath: normalizedOutput,
+    sourceNodeIds: htmlTarget.outputPath ? [artifactNodeIdForRenderTarget(htmlTarget)] : htmlTarget.sourceNodeIds,
+    contractStatus: "unknown",
+    data: {
+      sourceTargetId: htmlTarget.id,
+      sourceOutputPath: htmlTarget.outputPath,
+    },
+  })
+}
+
+export function recordArtifactRenderTarget(
+  state: DecksState,
+  input: { sourceHtmlPath: string; type: "pdf" | "pptx"; outputPath: string; artifactVersion?: string },
+): RenderTarget {
+  const normalizedSource = normalizeWorkspacePath(input.sourceHtmlPath)
+  const activeTarget = ensureActiveHtmlDeckRenderTarget(state)
+  const htmlTarget = htmlDeckRenderTargetForPath(state, normalizedSource) ?? (
+    activeTarget && normalizeWorkspacePath(activeTarget.outputPath ?? "") === normalizedSource ? activeTarget : undefined
+  )
+  const sourceTarget = htmlTarget ?? {
+    id: renderTargetId("html_deck", normalizedSource),
+    type: "html_deck" as const,
+    outputPath: normalizedSource,
+    sourceNodeIds: [],
+    contractStatus: "unknown" as const,
+  }
+  const target = {
+    ...deriveExportRenderTarget(sourceTarget, input.type, input.outputPath),
+    ...(input.artifactVersion ? { artifactVersion: input.artifactVersion } : {}),
+  }
+  upsertRenderTarget(state, target)
+  return target
+}
+
+export function htmlDeckRenderTargetForPath(state: DecksState, htmlPath: string): RenderTarget | undefined {
+  const normalized = normalizeWorkspacePath(htmlPath)
+  return (state.renderTargets ?? []).find((target) =>
+    target.type === "html_deck" && normalizeWorkspacePath(target.outputPath ?? "") === normalized
+  )
+}
+
+export function renderTargetId(type: RenderTargetType, outputPath: string): string {
+  return `target:${type}:${stablePathOrHash(outputPath)}`
+}
+
+export function artifactNodeIdForRenderTarget(target: RenderTarget): string {
+  return `artifact:${stablePathOrHash(target.outputPath || target.id)}`
+}
+
+export function normalizeWorkspacePath(value: string): string {
+  return String(value ?? "").trim().replace(/\\/g, "/").replace(/^\.\//, "")
+}
+
+export function replaceExtension(filePath: string, extension: ".pdf" | ".pptx"): string {
+  const normalized = normalizeWorkspacePath(filePath)
+  const dir = dirname(normalized)
+  const name = basename(normalized, extname(normalized))
+  return normalizeWorkspacePath(join(dir, `${name}${extension}`))
+}
+
+function createHtmlDeckRenderTarget(deck: DeckSpec): RenderTarget {
+  const outputPath = normalizeWorkspacePath(deck.outputPath)
+  const slideNodeIds = deck.slides.map((slide) => `slide:${slide.index}`)
+  return cleanRenderTarget({
+    id: renderTargetId("html_deck", outputPath),
+    type: "html_deck",
+    outputPath,
+    sourceNodeIds: [...new Set(slideNodeIds)].sort(),
+    contractStatus: "unknown",
+    data: {
+      slug: deck.slug,
+      compatibilityOutputPath: outputPath,
+    },
+  })
+}
+
+function activeDeck(state: DecksState): DeckSpec | undefined {
+  const key = state.activeDeck || singleDeckKey(state.decks)
+  return key ? state.decks[key] : undefined
+}
+
+function singleDeckKey(decks: Record<string, DeckSpec>): string | undefined {
+  const keys = Object.keys(decks)
+  return keys.length === 1 ? keys[0] : undefined
+}
+
+function cleanRenderTarget(target: RenderTarget): RenderTarget {
+  const data = compactData(target.data ?? {})
+  return {
+    id: target.id || renderTargetId(target.type, target.outputPath || "unknown"),
+    type: target.type,
+    ...(target.outputPath ? { outputPath: normalizeWorkspacePath(target.outputPath) } : {}),
+    sourceNodeIds: [...new Set(target.sourceNodeIds ?? [])].sort(),
+    ...(target.artifactVersion ? { artifactVersion: target.artifactVersion } : {}),
+    ...(target.contractStatus ? { contractStatus: target.contractStatus } : {}),
+    ...(Object.keys(data).length > 0 ? { data } : {}),
+  }
+}
+
+function mergeRenderTarget(existing: RenderTarget, next: RenderTarget): RenderTarget {
+  return cleanRenderTarget({
+    ...existing,
+    ...next,
+    sourceNodeIds: next.sourceNodeIds.length > 0 ? next.sourceNodeIds : existing.sourceNodeIds,
+    data: { ...(existing.data ?? {}), ...(next.data ?? {}) },
+  })
+}
+
+function sortRenderTargets(targets: RenderTarget[]): RenderTarget[] {
+  return targets.map(cleanRenderTarget).sort((a, b) => a.id.localeCompare(b.id))
+}
+
+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 stablePathOrHash(value: string): string {
+  const normalized = normalizeWorkspacePath(value)
+  if (/^[a-z0-9._/-]+$/i.test(normalized) && normalized.length <= 80) return normalized
+  return createHash("sha1").update(normalized).digest("hex").slice(0, 12)
+}

package/lib/workspace-state/rendered-artifacts.ts

@@ -0,0 +1,43 @@
+import { relative, resolve, sep } from "path"
+import { hasDecksState, readDecksState, writeDecksState } from "../decks-state"
+import { recordWorkspaceAction } from "./actions"
+import { recordArtifactRenderTarget } from "./render-targets"
+
+export function recordRenderedArtifact(
+  workspaceRoot: string,
+  input: {
+    sourceHtmlPath: string
+    outputPath: string
+    type: "pdf" | "pptx"
+    actor: string
+    artifactVersion?: string
+  },
+): void {
+  const root = resolve(workspaceRoot)
+  if (!hasDecksState(root)) return
+
+  const state = readDecksState(root)
+  const sourceHtmlPath = workspaceRelative(root, resolve(root, input.sourceHtmlPath))
+  const outputPath = workspaceRelative(root, resolve(root, input.outputPath))
+  const target = recordArtifactRenderTarget(state, {
+    sourceHtmlPath,
+    type: input.type,
+    outputPath,
+    artifactVersion: input.artifactVersion,
+  })
+
+  recordWorkspaceAction(state, {
+    type: "artifact.rendered",
+    actor: input.actor,
+    inputs: { sourceHtmlPath, type: input.type },
+    outputs: { outputPath, targetId: target.id },
+    status: "success",
+    summary: `Rendered ${input.type.toUpperCase()} artifact from ${sourceHtmlPath}.`,
+    nodeIds: [target.id],
+  })
+  writeDecksState(root, state)
+}
+
+export function workspaceRelative(root: string, target: string): string {
+  return relative(root, target).split(sep).join("/")
+}

package/lib/workspace-state/repository.ts

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"
+import { dirname, join } from "path"
+import { WORKSPACE_STATE_FILE, type WorkspaceStateRepositoryOptions } from "./types"
+
+export function workspaceStatePath(workspaceRoot: string, fileName = WORKSPACE_STATE_FILE): string {
+  return join(workspaceRoot, fileName)
+}
+
+export function hasWorkspaceState(workspaceRoot: string, fileName = WORKSPACE_STATE_FILE): boolean {
+  return existsSync(workspaceStatePath(workspaceRoot, fileName))
+}
+
+export function readWorkspaceState<TState>(workspaceRoot: string, options: WorkspaceStateRepositoryOptions<TState> = {}): TState {
+  const parsed = JSON.parse(readFileSync(workspaceStatePath(workspaceRoot, options.fileName), "utf-8")) as TState
+  return options.normalize ? options.normalize(parsed) : parsed
+}
+
+export function writeWorkspaceState<TState>(workspaceRoot: string, state: TState, options: WorkspaceStateRepositoryOptions<TState> = {}): void {
+  const filePath = workspaceStatePath(workspaceRoot, options.fileName)
+  const next = options.normalize ? options.normalize(state) : state
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, JSON.stringify(next, null, 2) + "\n", "utf-8")
+}
+
+export function readOrCreateWorkspaceState<TState>(
+  workspaceRoot: string,
+  createState: () => TState,
+  options: WorkspaceStateRepositoryOptions<TState> = {},
+): TState {
+  if (hasWorkspaceState(workspaceRoot, options.fileName)) return readWorkspaceState(workspaceRoot, options)
+
+  const state = createState()
+  writeWorkspaceState(workspaceRoot, state, options)
+  return state
+}
+
+export function loadCanonicalState<TState>(workspaceRoot: string, options: WorkspaceStateRepositoryOptions<TState> = {}): TState {
+  return readWorkspaceState(workspaceRoot, options)
+}
+
+export function saveCanonicalState<TState>(workspaceRoot: string, state: TState, options: WorkspaceStateRepositoryOptions<TState> = {}): void {
+  writeWorkspaceState(workspaceRoot, state, options)
+}

package/lib/workspace-state/research-attachments.ts

@@ -0,0 +1,130 @@
+import { existsSync } from "fs"
+import { basename, resolve, sep } from "path"
+import {
+  readDecksState,
+  writeDecksState,
+  type DecksState,
+  type ResearchAxis,
+} from "../decks-state"
+import { recordWorkspaceAction } from "./actions"
+
+export interface AttachResearchFindingsInput {
+  findingsFile: string
+  researchAxis?: string
+  status?: "done" | "read"
+}
+
+export interface AttachResearchFindingsResult {
+  attached: boolean
+  skipped: boolean
+  reason?: string
+  slug?: string
+  axis?: string
+  findingsFile?: string
+  status?: ResearchAxis["status"]
+}
+
+export function attachResearchFindings(workspaceRoot: string, input: AttachResearchFindingsInput): AttachResearchFindingsResult {
+  const state = readDecksState(workspaceRoot)
+  const result = attachResearchFindingsToState(state, workspaceRoot, input)
+  writeDecksState(workspaceRoot, state)
+  return result
+}
+
+export function attachResearchFindingsToState(state: DecksState, workspaceRoot: string, input: AttachResearchFindingsInput): AttachResearchFindingsResult {
+  const normalizedFile = normalizeResearchFindingsPath(input.findingsFile)
+  if (!normalizedFile) {
+    return recordSkipped(state, input, "findingsFile must be a workspace-relative researches/*.md path")
+  }
+
+  const absoluteFile = safeWorkspacePath(workspaceRoot, normalizedFile)
+  if (!absoluteFile || !existsSync(absoluteFile)) {
+    return recordSkipped(state, { ...input, findingsFile: normalizedFile }, "findingsFile does not exist inside the workspace")
+  }
+
+  const slug = state.activeDeck ?? singleDeckKey(state)
+  const deck = slug ? state.decks[slug] : undefined
+  if (!slug || !deck) return recordSkipped(state, { ...input, findingsFile: normalizedFile }, "no active deck is available")
+
+  const matches = matchingAxes(deck.researchPlan ?? [], input.researchAxis, normalizedFile)
+  if (matches.length === 0) return recordSkipped(state, { ...input, findingsFile: normalizedFile }, "no matching researchPlan axis found")
+  if (matches.length > 1) return recordSkipped(state, { ...input, findingsFile: normalizedFile }, "researchPlan axis match is ambiguous")
+
+  const index = matches[0]!
+  const existing = deck.researchPlan[index]!
+  const nextStatus = input.status ?? existing.status
+  deck.researchPlan[index] = {
+    ...existing,
+    status: nextStatus,
+    findingsFile: normalizedFile,
+  }
+
+  recordWorkspaceAction(state, {
+    type: "research.findings_attached",
+    actor: "revela-decks",
+    inputs: { activeDeck: slug, axis: existing.axis, findingsFile: normalizedFile, requestedStatus: input.status },
+    outputs: { slug, axis: existing.axis, findingsFile: normalizedFile, status: nextStatus },
+    summary: `Attached research findings ${normalizedFile} to axis ${existing.axis}.`,
+    nodeIds: [`finding:${normalizedFile}`],
+  })
+
+  return {
+    attached: true,
+    skipped: false,
+    slug,
+    axis: existing.axis,
+    findingsFile: normalizedFile,
+    status: nextStatus,
+  }
+}
+
+function matchingAxes(researchPlan: ResearchAxis[], researchAxis: string | undefined, findingsFile: string): number[] {
+  if (researchAxis?.trim()) {
+    const requested = normalizeKey(researchAxis)
+    return researchPlan.flatMap((axis, index) => normalizeKey(axis.axis) === requested ? [index] : [])
+  }
+
+  const fileKey = normalizeKey(basename(findingsFile, ".md"))
+  return researchPlan.flatMap((axis, index) => normalizeKey(axis.axis) === fileKey ? [index] : [])
+}
+
+function recordSkipped(state: DecksState, input: AttachResearchFindingsInput, reason: string): AttachResearchFindingsResult {
+  const normalizedFile = normalizeResearchFindingsPath(input.findingsFile) ?? input.findingsFile
+  recordWorkspaceAction(state, {
+    type: "research.findings_attached",
+    actor: "revela-decks",
+    inputs: { axis: input.researchAxis, findingsFile: normalizedFile, requestedStatus: input.status },
+    outputs: { reason },
+    status: "skipped",
+    summary: `Skipped research findings attachment: ${reason}.`,
+    nodeIds: normalizedFile ? [`finding:${normalizedFile}`] : [],
+  })
+  return { attached: false, skipped: true, reason }
+}
+
+function normalizeResearchFindingsPath(filePath: string | undefined): string | undefined {
+  const normalized = normalizePath(filePath ?? "").replace(/^\.\//, "")
+  if (!normalized || normalized.startsWith("../") || normalized.startsWith("/")) return undefined
+  if (!normalized.startsWith("researches/") || !normalized.endsWith(".md")) return undefined
+  return normalized
+}
+
+function safeWorkspacePath(workspaceRoot: string, relativePath: string): string | undefined {
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, relativePath)
+  if (target !== root && !target.startsWith(root + sep)) return undefined
+  return target
+}
+
+function singleDeckKey(state: DecksState): string | undefined {
+  const keys = Object.keys(state.decks)
+  return keys.length === 1 ? keys[0] : undefined
+}
+
+function normalizeKey(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, "-").replace(/^-+|-+$/g, "")
+}
+
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, "/")
+}

package/lib/workspace-state/review-snapshots.ts

@@ -0,0 +1,127 @@
+import { createHash } from "crypto"
+import type { DeckSpec, DecksState, DeckStateReadinessResult } from "../decks-state"
+import { projectWorkspaceGraph } from "./graph"
+import { activeHtmlDeckRenderTarget, ensureActiveHtmlDeckRenderTarget } from "./render-targets"
+import type { ReviewSnapshot } from "./types"
+
+export const MAX_REVIEW_SNAPSHOTS = 50
+
+export interface ReviewSnapshotInput {
+  slug: string
+  result: DeckStateReadinessResult
+  reviewedAt?: string
+}
+
+export function currentReviewInputHash(state: DecksState, slug?: string): string {
+  return stableHash(stableStringify(reviewInputProjection(state, slug)))
+}
+
+export function activeReviewTargetId(state: DecksState): string | undefined {
+  return activeHtmlDeckRenderTarget(state)?.id ?? ensureActiveHtmlDeckRenderTarget(state)?.id
+}
+
+export function createReviewSnapshot(state: DecksState, input: ReviewSnapshotInput): ReviewSnapshot {
+  const reviewedAt = input.reviewedAt ?? new Date().toISOString()
+  const targetId = activeReviewTargetId(state)
+  const inputHash = currentReviewInputHash(state, input.slug)
+  return {
+    id: reviewSnapshotId(targetId, inputHash, reviewedAt),
+    ...(targetId ? { targetId } : {}),
+    inputHash,
+    status: input.result.status ?? (input.result.ready ? "ready" : "blocked"),
+    blockers: input.result.blockers,
+    warnings: input.result.warnings,
+    issues: input.result.issues,
+    ...(input.result.evidenceCandidates ? { evidenceCandidates: input.result.evidenceCandidates } : {}),
+    reviewedAt,
+  }
+}
+
+export function appendReviewSnapshot(state: DecksState, snapshot: ReviewSnapshot): DecksState {
+  const next = (state.reviews ?? []).filter((item) => item.id !== snapshot.id)
+  next.push(snapshot)
+  state.reviews = next
+    .sort((a, b) => a.reviewedAt.localeCompare(b.reviewedAt))
+    .slice(-MAX_REVIEW_SNAPSHOTS)
+  return state
+}
+
+export function latestReviewSnapshotForTarget(state: DecksState, targetId?: string): ReviewSnapshot | undefined {
+  const reviews = state.reviews ?? []
+  const candidates = targetId ? reviews.filter((item) => item.targetId === targetId) : reviews
+  return candidates.reduce<ReviewSnapshot | undefined>((latest, item) => {
+    if (!latest) return item
+    return item.reviewedAt.localeCompare(latest.reviewedAt) >= 0 ? item : latest
+  }, undefined)
+}
+
+export function isReviewSnapshotCurrent(state: DecksState, snapshot: ReviewSnapshot, slug?: string): boolean {
+  return snapshot.inputHash === currentReviewInputHash(state, slug)
+}
+
+function reviewInputProjection(state: DecksState, slug?: string): unknown {
+  const key = slug || state.activeDeck || singleDeckKey(state.decks)
+  const deck = key ? state.decks[key] : undefined
+  const stableState = cloneForGraphProjection(state, key)
+  return {
+    version: state.version,
+    activeDeck: key,
+    workspace: {
+      brief: state.workspace.brief,
+      sourceMaterials: state.workspace.sourceMaterials,
+      openQuestions: state.workspace.openQuestions,
+    },
+    deck: deck ? stableDeckProjection(deck) : undefined,
+    renderTarget: activeHtmlDeckRenderTarget(state) ?? ensureActiveHtmlDeckRenderTarget(state),
+    graph: deck ? projectWorkspaceGraph(stableState, { slug: key }) : undefined,
+  }
+}
+
+function stableDeckProjection(deck: DeckSpec): unknown {
+  return {
+    slug: deck.slug,
+    goal: deck.goal,
+    audience: deck.audience,
+    language: deck.language,
+    outputPath: deck.outputPath,
+    narrativeBrief: deck.narrativeBrief,
+    theme: deck.theme,
+    requiredInputs: deck.requiredInputs,
+    researchPlan: deck.researchPlan,
+    slides: deck.slides,
+    assets: deck.assets,
+  }
+}
+
+function cloneForGraphProjection(state: DecksState, slug?: string): DecksState {
+  const clone = structuredClone(state) as DecksState
+  const key = slug || clone.activeDeck || singleDeckKey(clone.decks)
+  const deck = key ? clone.decks[key] : undefined
+  if (deck) {
+    deck.status = "planning"
+    deck.writeReadiness = { status: "blocked", blockers: [] }
+  }
+  clone.actions = []
+  clone.reviews = []
+  return clone
+}
+
+function reviewSnapshotId(targetId: string | undefined, inputHash: string, reviewedAt: string): string {
+  return `review:${targetId ?? "workspace"}:${inputHash.slice(0, 12)}:${stableHash(reviewedAt).slice(0, 8)}`
+}
+
+function stableHash(value: string): string {
+  return createHash("sha1").update(value).digest("hex")
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`
+  const object = value as Record<string, unknown>
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`
+}
+
+function singleDeckKey(decks: Record<string, DeckSpec>): string | undefined {
+  const keys = Object.keys(decks)
+  return keys.length === 1 ? keys[0] : undefined
+}

package/lib/workspace-state/types.ts

@@ -0,0 +1,122 @@
+import type { DecksState } from "../decks-state"
+
+export const WORKSPACE_STATE_FILE = "DECKS.json"
+
+export type WorkspaceStateVersion = 1 | 2
+
+export interface WorkspaceStateRepositoryOptions<TState> {
+  fileName?: string
+  normalize?: (state: TState) => TState
+}
+
+export interface WorkspaceStateV2 {
+  version: 2
+  workspace: WorkspaceMeta
+  graph: WorkspaceGraph
+  actions: WorkspaceAction[]
+  renderTargets: RenderTarget[]
+  reviews: ReviewSnapshot[]
+  compatibility?: DecksStateV1Projection
+}
+
+export interface WorkspaceMeta {
+  brief?: string
+  preferences?: {
+    user: string[]
+    workflow: string[]
+  }
+  openQuestions?: string[]
+}
+
+export interface WorkspaceGraph {
+  nodes: Record<string, GraphNode>
+  edges: GraphEdge[]
+}
+
+export interface GraphNode {
+  id: string
+  type: GraphNodeType
+  label?: string
+  data?: Record<string, unknown>
+}
+
+export type GraphNodeType =
+  | "source"
+  | "extraction"
+  | "finding"
+  | "claim"
+  | "narrativeIntent"
+  | "objection"
+  | "risk"
+  | "slide"
+  | "artifact"
+
+export interface GraphEdge {
+  id: string
+  type: GraphEdgeType
+  from: string
+  to: string
+  data?: Record<string, unknown>
+}
+
+export type GraphEdgeType =
+  | "contains"
+  | "extracted_as"
+  | "produced"
+  | "supports"
+  | "appears_in"
+  | "challenges"
+  | "constrained_by"
+  | "renders_from"
+  | "derived_from"
+
+export interface WorkspaceAction {
+  id: string
+  type: WorkspaceActionType
+  timestamp: string
+  actor?: string
+  inputs?: Record<string, unknown>
+  outputs?: Record<string, unknown>
+  status: "success" | "failed" | "skipped"
+  summary?: string
+  nodeIds?: string[]
+}
+
+export type WorkspaceActionType =
+  | "workspace.scanned"
+  | "source.discovered"
+  | "source.extracted"
+  | "research.findings_saved"
+  | "research.findings_attached"
+  | "narrative.upserted"
+  | "deck.plan_compiled"
+  | "evidence.candidate_generated"
+  | "evidence.binding_applied"
+  | "narrative.approved"
+  | "review.performed"
+  | "artifact.rendered"
+
+export interface RenderTarget {
+  id: string
+  type: "html_deck" | "pdf" | "pptx" | "brief" | "appendix" | "qa_view" | "interactive_page"
+  outputPath?: string
+  sourceNodeIds: string[]
+  artifactVersion?: string
+  contractStatus?: "unknown" | "valid" | "invalid" | "stale"
+  data?: Record<string, unknown>
+}
+
+export interface ReviewSnapshot {
+  id: string
+  targetId?: string
+  inputHash: string
+  status: "blocked" | "ready" | "written"
+  blockers: string[]
+  warnings: string[]
+  issues: unknown[]
+  evidenceCandidates?: unknown[]
+  reviewedAt: string
+}
+
+export type DecksStateV1Projection = DecksState
+export type WorkspaceState = DecksState | WorkspaceStateV2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",