@cyber-dash-tech/revela 0.10.0 → 0.11.0

package/lib/decks-state.ts

@@ -1,8 +1,24 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs"
+import { existsSync, readdirSync, readFileSync, statSync } from "fs"
 import { createHash } from "crypto"
-import { basename, dirname, join, resolve } from "path"
-
-export const DECKS_STATE_FILE = "DECKS.json"
+import { basename, join, resolve } from "path"
+import {
+  hasWorkspaceState,
+  readOrCreateWorkspaceState,
+  readWorkspaceState,
+  workspaceStatePath,
+  writeWorkspaceState,
+} from "./workspace-state/repository"
+import { ensureActiveHtmlDeckRenderTarget } from "./workspace-state/render-targets"
+import {
+  activeReviewTargetId,
+  appendReviewSnapshot,
+  createReviewSnapshot,
+  isReviewSnapshotCurrent,
+  latestReviewSnapshotForTarget,
+} from "./workspace-state/review-snapshots"
+import { WORKSPACE_STATE_FILE, type RenderTarget, type ReviewSnapshot, type WorkspaceAction } from "./workspace-state/types"
+
+export const DECKS_STATE_FILE = WORKSPACE_STATE_FILE
 
 export type DeckProductionStatus = "planning" | "blocked" | "ready" | "written"
 export type SlideProductionStatus = "planned" | "ready" | "written" | "qa_passed" | "qa_failed"
@@ -23,6 +39,9 @@ export interface DecksState {
     openQuestions: string[]
   }
   decks: Record<string, DeckSpec>
+  actions: WorkspaceAction[]
+  renderTargets: RenderTarget[]
+  reviews: ReviewSnapshot[]
 }
 
 export interface SourceMaterial {
@@ -249,11 +268,11 @@ export interface ReviewDeckStateOptions {
 }
 
 export function decksStatePath(workspaceRoot: string): string {
-  return join(workspaceRoot, DECKS_STATE_FILE)
+  return workspaceStatePath(workspaceRoot, DECKS_STATE_FILE)
 }
 
 export function hasDecksState(workspaceRoot: string): boolean {
-  return existsSync(decksStatePath(workspaceRoot))
+  return hasWorkspaceState(workspaceRoot, DECKS_STATE_FILE)
 }
 
 export function createEmptyDecksState(): DecksState {
@@ -266,6 +285,9 @@ export function createEmptyDecksState(): DecksState {
       openQuestions: [],
     },
     decks: {},
+    actions: [],
+    renderTargets: [],
+    reviews: [],
   }
 }
 
@@ -289,6 +311,7 @@ export function normalizeWorkspaceDeckState(state: DecksState, workspaceRoot: st
   delete normalized.decks[existingKey]
   normalized.decks[slug] = deck
   normalized.activeDeck = slug
+  ensureActiveHtmlDeckRenderTarget(normalized)
   return normalized
 }
 
@@ -326,21 +349,15 @@ export function createDeckSpec(input: Partial<DeckSpec> & { slug: string }): Dec
 }
 
 export function readDecksState(workspaceRoot: string): DecksState {
-  const parsed = JSON.parse(readFileSync(decksStatePath(workspaceRoot), "utf-8")) as DecksState
-  return normalizeDecksState(parsed)
+  return readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
 }
 
 export function writeDecksState(workspaceRoot: string, state: DecksState): void {
-  const filePath = decksStatePath(workspaceRoot)
-  mkdirSync(dirname(filePath), { recursive: true })
-  writeFileSync(filePath, JSON.stringify(normalizeDecksState(state), null, 2) + "\n", "utf-8")
+  writeWorkspaceState(workspaceRoot, state, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
 }
 
 export function readOrCreateDecksState(workspaceRoot: string): DecksState {
-  if (hasDecksState(workspaceRoot)) return readDecksState(workspaceRoot)
-  const state = createEmptyDecksState()
-  writeDecksState(workspaceRoot, state)
-  return state
+  return readOrCreateWorkspaceState(workspaceRoot, createEmptyDecksState, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
 }
 
 export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug: string }): DecksState {
@@ -354,6 +371,7 @@ export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug:
   const next = createDeckSpec({ ...existing, ...input, slug })
   normalized.decks[slug] = next
   normalized.activeDeck = slug
+  ensureActiveHtmlDeckRenderTarget(normalized)
   return normalized
 }
 
@@ -370,6 +388,7 @@ export function upsertSlides(state: DecksState, slug: string, slides: SlideSpec[
   deck.slides = [...byIndex.values()].sort((a, b) => a.index - b.index)
   normalized.decks[key] = deck
   normalized.activeDeck = key
+  ensureActiveHtmlDeckRenderTarget(normalized)
   return normalized
 }
 
@@ -459,26 +478,29 @@ export function reviewDeckState(state: DecksState, slug?: string, options: Revie
   const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
   const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   const evidenceCandidates = issues.flatMap((issue) => issue.evidenceCandidates ?? [])
+  const reviewedAt = new Date().toISOString()
   deck.writeReadiness = {
     status: blockers.length === 0 ? "ready" : "blocked",
     blockers,
-    lastReviewedAt: new Date().toISOString(),
+    lastReviewedAt: reviewedAt,
   }
   deck.status = blockers.length === 0 ? "ready" : "blocked"
   normalized.decks[deck.slug] = deck
   normalized.activeDeck = deck.slug
+  const result: DeckStateReadinessResult = {
+    ready: blockers.length === 0,
+    slug: deck.slug,
+    status: deck.writeReadiness.status,
+    blocker: blockers.join("; "),
+    blockers,
+    warnings,
+    issues,
+    evidenceCandidates,
+  }
+  appendReviewSnapshot(normalized, createReviewSnapshot(normalized, { slug: deck.slug, result, reviewedAt }))
   return {
     state: normalized,
-    result: {
-      ready: blockers.length === 0,
-      slug: deck.slug,
-      status: deck.writeReadiness.status,
-      blocker: blockers.join("; "),
-      blockers,
-      warnings,
-      issues,
-      evidenceCandidates,
-    },
+    result,
   }
 }
 
@@ -542,6 +564,38 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela review.",
     })
   }
+  if (normalized.reviews.length > 0) {
+    const targetId = activeReviewTargetId(normalized)
+    const snapshot = latestReviewSnapshotForTarget(normalized, targetId)
+    if (!snapshot) {
+      const message = "No review snapshot exists for the active HTML render target"
+      blockers.unshift(message)
+      issues.unshift({
+        type: "missing_slide_spec",
+        severity: "blocker",
+        message,
+        suggestedAction: "Run /revela review so readiness is recorded against the current active render target.",
+      })
+    } else if (!isReviewSnapshotCurrent(normalized, snapshot, deck.slug)) {
+      const message = "Latest review snapshot is stale for the current deck, sources, evidence, narrative state, or render target"
+      blockers.unshift(message)
+      issues.unshift({
+        type: "missing_slide_spec",
+        severity: "blocker",
+        message,
+        suggestedAction: "Run /revela review again after the latest state changes before writing deck HTML.",
+      })
+    } else if (snapshot.status !== "ready") {
+      const message = `Latest review snapshot is ${snapshot.status}, not ready`
+      blockers.unshift(message)
+      issues.unshift({
+        type: "missing_slide_spec",
+        severity: "blocker",
+        message,
+        suggestedAction: "Resolve review blockers and rerun /revela review before writing deck HTML.",
+      })
+    }
+  }
 
   return {
     ready: blockers.length === 0,
@@ -579,11 +633,12 @@ export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 140
     activeDeck: activeKey,
     workspace: compactWorkspaceForPrompt(state.workspace),
     deck: active ? compactDeckForPrompt(active) : undefined,
+    renderTargets: state.renderTargets,
+    reviews: compactReviewsForPrompt(state.reviews),
   }
   let text = JSON.stringify(compact, null, 2)
   if (text.length > maxChars) text = text.slice(0, maxChars).trimEnd() + "\n[DECKS.json state truncated for prompt size.]"
-  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the current deck must have writeReadiness.status=ready and a complete slide spec, and its outputPath must match the target file.`
-  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, evidence, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the current deck must have writeReadiness.status=ready and a complete slide spec, and its outputPath must match the target file.`
+  return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection. When review snapshots exist, deck HTML writes require a current non-stale ready review snapshot for the active HTML render target.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the current deck must have writeReadiness.status=ready and a complete slide spec, and its outputPath must match the target file.`
 }
 
 function compactWorkspaceForPrompt(workspace: DecksState["workspace"]): DecksState["workspace"] {
@@ -616,6 +671,20 @@ function compactDeckForPrompt(deck: DeckSpec): DeckSpec {
   }
 }
 
+function compactReviewsForPrompt(reviews: ReviewSnapshot[]): ReviewSnapshot[] {
+  return reviews.slice(-5).map((review) => ({
+    id: review.id,
+    targetId: review.targetId,
+    inputHash: review.inputHash,
+    status: review.status,
+    blockers: review.blockers.slice(0, 5),
+    warnings: review.warnings.slice(0, 5),
+    issues: review.issues.slice(0, 10),
+    evidenceCandidates: review.evidenceCandidates?.slice(0, 10),
+    reviewedAt: review.reviewedAt,
+  }))
+}
+
 function compactNarrativeBriefForPrompt(brief: NarrativeBrief | undefined): NarrativeBrief | undefined {
   if (!brief) return undefined
   return {
@@ -659,6 +728,9 @@ function normalizeDecksState(input: DecksState): DecksState {
       openQuestions: input.workspace?.openQuestions ?? [],
     },
     decks: {},
+    actions: input.actions ?? [],
+    renderTargets: input.renderTargets ?? [],
+    reviews: input.reviews ?? [],
   }
   for (const [slug, deck] of Object.entries(input.decks ?? {})) {
     const normalizedSlug = normalizeSlug(deck.slug || slug)
@@ -669,6 +741,7 @@ function normalizeDecksState(input: DecksState): DecksState {
     const keys = Object.keys(state.decks)
     if (keys.length === 1) state.activeDeck = keys[0]
   }
+  ensureActiveHtmlDeckRenderTarget(state)
   return state
 }
 

package/lib/document-materials/extract.ts

@@ -10,6 +10,7 @@ import { extractPptx } from "../read-hooks/extractors/pptx"
 import { extractXlsx } from "../read-hooks/extractors/xlsx"
 import { hasDecksState, readDecksState, writeDecksState } from "../decks-state"
 import { computeSourceFingerprint, sourceMaterialMetadata, upsertSourceMaterial } from "../source-materials"
+import { recordWorkspaceAction } from "../workspace-state/actions"
 
 export type DocumentMaterial = {
   path: string
@@ -180,6 +181,25 @@ function updateDecksSourceMaterialIndex(
       : undefined,
     lastExtracted: extracted ? (result.cache_status === "hit" ? existing?.lastExtracted ?? now : now) : undefined,
   }, extracted ? "extracted" : "discovered")
+  recordWorkspaceAction(state, {
+    type: "source.extracted",
+    actor: "revela-extract-document-materials",
+    inputs: { file: base.path, type: base.type, fingerprint: base.fingerprint },
+    outputs: {
+      status: result.status,
+      cacheStatus: result.cache_status,
+      source: result.source,
+      manifestPath: result.manifest_path,
+      textPath: result.text_path,
+      cacheDir: result.cache_dir,
+      reason: result.reason,
+      imageCount: result.images?.length ?? 0,
+      tableCount: result.tables?.length ?? 0,
+    },
+    status: result.status === "failed" ? "failed" : result.status === "skipped" ? "skipped" : "success",
+    summary: extracted ? `Extracted reusable materials from ${base.path}.` : `Registered ${base.path} without reusable extraction output.`,
+    nodeIds: [`source:${base.path}`],
+  })
   writeDecksState(workspaceDir, state)
 }
 

package/lib/edit/resolve-deck.ts

@@ -1,12 +1,13 @@
 import { existsSync, readdirSync } from "fs"
 import { relative, resolve, sep } from "path"
-import { DECKS_STATE_FILE, isDeckHtmlPath, workspaceDeckSlug } from "../decks-state"
+import { DECKS_STATE_FILE, hasDecksState, isDeckHtmlPath, readDecksState, workspaceDeckSlug } from "../decks-state"
+import { resolveActiveHtmlDeckPath } from "../workspace-state/render-targets"
 
 export interface EditableDeck {
   slug: string
   file: string
   absoluteFile: string
-  source: "decks-state" | "fallback" | "file-path"
+  source: "render-target" | "decks-state" | "fallback" | "file-path"
 }
 
 export function resolveEditableDeck(workspaceRoot: string, input = ""): EditableDeck {
@@ -14,6 +15,16 @@ export function resolveEditableDeck(workspaceRoot: string, input = ""): Editable
     throw new Error("/revela edit no longer accepts a target. It opens the only HTML deck in decks/.")
   }
 
+  if (hasDecksState(workspaceRoot)) {
+    const state = readDecksState(workspaceRoot)
+    const deckPath = resolveActiveHtmlDeckPath(state)
+    const source = state.renderTargets.some((target) => target.type === "html_deck" && target.outputPath === deckPath) ? "render-target" : "decks-state"
+    if (deckPath && isDeckHtmlPath(deckPath)) {
+      const absoluteFile = resolve(workspaceRoot, deckPath)
+      if (existsSync(absoluteFile)) return resolveDeckFile(workspaceRoot, workspaceDeckSlug(workspaceRoot), deckPath, source)
+    }
+  }
+
   const htmlFiles = listDeckHtmlFiles(workspaceRoot)
   if (htmlFiles.length === 0) {
     throw new Error("No deck HTML found in decks/. Generate a deck first.")

package/lib/inspect/open.ts

@@ -2,6 +2,7 @@ import { existsSync } from "fs"
 import { ACTIVE_PROMPT_FILE } from "../config"
 import { ctx } from "../ctx"
 import { seedBuiltinDesigns } from "../design/designs"
+import { assertDeckHtmlContractValid } from "../deck-html/contract"
 import { seedBuiltinDomains } from "../domain/domains"
 import { ensureEditableDeckState } from "../edit/deck-state"
 import { openUrl } from "../edit/open"
@@ -30,6 +31,7 @@ export interface OpenInspectDeckOptions {
 export function openInspectDeck(target: string, options: OpenInspectDeckOptions): OpenInspectDeckResult {
   const deck = resolveEditableDeck(options.workspaceRoot, target)
   const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
+  assertDeckHtmlContractValid(options.workspaceRoot, deck.absoluteFile)
 
   ctx.enabled = true
   if (!existsSync(ACTIVE_PROMPT_FILE)) {
@@ -52,7 +54,7 @@ export function openInspectDeck(target: string, options: OpenInspectDeckOptions)
   return {
     deck,
     url,
-    source: deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path",
+    source: deck.source === "render-target" ? "render target" : deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path",
     stateNote: preflight.changed ? "Deck state was prepared in DECKS.json for inspection." : "Deck state already points to this inspection target.",
     preflightChanged: preflight.changed,
     reusedSession: session.reused,

package/lib/qa/export-gate.ts

@@ -1,6 +1,13 @@
 import { formatReport, runQA } from "./index"
+import { assertDeckHtmlContractValid } from "../deck-html/contract"
+
+export interface ExportQAGateOptions {
+  workspaceRoot?: string
+}
+
+export async function assertExportQAPassed(filePath: string, options: ExportQAGateOptions = {}): Promise<void> {
+  if (options.workspaceRoot) assertDeckHtmlContractValid(options.workspaceRoot, filePath)
 
-export async function assertExportQAPassed(filePath: string): Promise<void> {
   const report = await runQA(filePath)
   if (report.totalIssues === 0) return
 

package/lib/refine/open.ts

@@ -2,6 +2,7 @@ import { existsSync } from "fs"
 import { ACTIVE_PROMPT_FILE } from "../config"
 import { ctx } from "../ctx"
 import { seedBuiltinDesigns } from "../design/designs"
+import { assertDeckHtmlContractValid } from "../deck-html/contract"
 import { seedBuiltinDomains } from "../domain/domains"
 import { ensureEditableDeckState } from "../edit/deck-state"
 import { openUrl } from "../edit/open"
@@ -33,6 +34,7 @@ export interface OpenRefineDeckOptions {
 export function openRefineDeck(target: string, options: OpenRefineDeckOptions): OpenRefineDeckResult {
   const deck = resolveEditableDeck(options.workspaceRoot, target)
   const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
+  assertDeckHtmlContractValid(options.workspaceRoot, deck.absoluteFile)
   const mode = options.mode ?? "edit"
 
   ctx.enabled = true
@@ -57,7 +59,7 @@ export function openRefineDeck(target: string, options: OpenRefineDeckOptions):
   return {
     deck,
     url,
-    source: deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path",
+    source: deck.source === "render-target" ? "render target" : deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path",
     stateNote: preflight.changed ? "Deck state was prepared in DECKS.json for refinement." : "Deck state already points to this refinement target.",
     preflightChanged: preflight.changed,
     reusedSession: session.reused,

package/lib/workspace-state/actions.ts

@@ -0,0 +1,71 @@
+import { createHash } from "crypto"
+import type { DecksState } from "../decks-state"
+import type { WorkspaceAction, WorkspaceActionType } from "./types"
+
+export const MAX_WORKSPACE_ACTIONS = 500
+
+export interface WorkspaceActionInput {
+  type: WorkspaceActionType
+  actor?: string
+  inputs?: Record<string, unknown>
+  outputs?: Record<string, unknown>
+  status?: WorkspaceAction["status"]
+  summary?: string
+  nodeIds?: string[]
+  timestamp?: string
+}
+
+export function recordWorkspaceAction(state: DecksState, input: WorkspaceActionInput): DecksState {
+  const actions = state.actions ?? []
+  const timestamp = input.timestamp ?? new Date().toISOString()
+  const action: WorkspaceAction = {
+    id: workspaceActionId(input.type, timestamp, actions.length, input),
+    type: input.type,
+    timestamp,
+    status: input.status ?? "success",
+    ...(input.actor ? { actor: input.actor } : {}),
+    ...(input.inputs ? { inputs: compactActionPayload(input.inputs) } : {}),
+    ...(input.outputs ? { outputs: compactActionPayload(input.outputs) } : {}),
+    ...(input.summary ? { summary: input.summary } : {}),
+    ...(input.nodeIds && input.nodeIds.length > 0 ? { nodeIds: [...new Set(input.nodeIds)].sort() } : {}),
+  }
+
+  state.actions = [...actions, action].slice(-MAX_WORKSPACE_ACTIONS)
+  return state
+}
+
+export function compactActionPayload(input: Record<string, unknown>): Record<string, unknown> {
+  const output: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(input)) {
+    const compacted = compactActionValue(value)
+    if (compacted !== undefined) output[key] = compacted
+  }
+  return output
+}
+
+export function workspaceActionId(type: WorkspaceActionType, timestamp: string, sequence: number, input: Omit<WorkspaceActionInput, "timestamp">): string {
+  return `action:${timestamp}:${type}:${stableHash(JSON.stringify({ sequence, input: compactActionPayload(input as Record<string, unknown>) }))}`
+}
+
+function compactActionValue(value: unknown): unknown {
+  if (value === undefined || value === null) return undefined
+  if (typeof value === "string") {
+    const trimmed = value.trim()
+    if (!trimmed) return undefined
+    return trimmed.length > 500 ? `${trimmed.slice(0, 500).trimEnd()}... [truncated]` : trimmed
+  }
+  if (typeof value === "number" || typeof value === "boolean") return value
+  if (Array.isArray(value)) {
+    const items = value.map(compactActionValue).filter((item) => item !== undefined)
+    return items.length > 0 ? items.slice(0, 50) : undefined
+  }
+  if (typeof value === "object") {
+    const compacted = compactActionPayload(value as Record<string, unknown>)
+    return Object.keys(compacted).length > 0 ? compacted : undefined
+  }
+  return undefined
+}
+
+function stableHash(value: string): string {
+  return createHash("sha1").update(value).digest("hex").slice(0, 10)
+}

package/lib/workspace-state/compat.ts

@@ -0,0 +1,10 @@
+import type { DecksState } from "../decks-state"
+import type { DecksStateV1Projection, WorkspaceState } from "./types"
+
+export function isDecksStateV1(state: WorkspaceState): state is DecksState {
+  return state.version === 1
+}
+
+export function asDecksStateV1Projection(state: DecksState): DecksStateV1Projection {
+  return state
+}