@cyber-dash-tech/revela 0.10.0 → 0.12.0

package/lib/decks-state.ts

@@ -1,8 +1,26 @@
-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"
+import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "./narrative-state/normalize"
+import type { NarrativeStateV1 } from "./narrative-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"
@@ -12,6 +30,7 @@ export type NarrativeRole = "context" | "tension" | "evidence" | "recommendation
 export interface DecksState {
   version: 1
   activeDeck?: string
+  narrative?: NarrativeStateV1
   workspace: {
     brief?: string
     sourceMaterials: SourceMaterial[]
@@ -23,6 +42,9 @@ export interface DecksState {
     openQuestions: string[]
   }
   decks: Record<string, DeckSpec>
+  actions: WorkspaceAction[]
+  renderTargets: RenderTarget[]
+  reviews: ReviewSnapshot[]
 }
 
 export interface SourceMaterial {
@@ -249,11 +271,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 +288,9 @@ export function createEmptyDecksState(): DecksState {
       openQuestions: [],
     },
     decks: {},
+    actions: [],
+    renderTargets: [],
+    reviews: [],
   }
 }
 
@@ -289,6 +314,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 +352,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: normalizeDecksStateWithNarrative })
 }
 
 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: normalizeDecksStateWithNarrative })
 }
 
 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: normalizeDecksStateWithNarrative })
 }
 
 export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug: string }): DecksState {
@@ -354,6 +374,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 +391,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 +481,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 +567,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 +636,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 +674,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 {
@@ -648,6 +720,7 @@ function normalizeDecksState(input: DecksState): DecksState {
   const state: DecksState = {
     version: 1,
     activeDeck: input.activeDeck ? normalizeSlug(input.activeDeck) : undefined,
+    narrative: normalizeCanonicalNarrativeState(input.narrative, input.activeDeck || "workspace"),
     workspace: {
       brief: input.workspace?.brief,
       sourceMaterials: input.workspace?.sourceMaterials ?? [],
@@ -659,6 +732,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 +745,13 @@ function normalizeDecksState(input: DecksState): DecksState {
     const keys = Object.keys(state.decks)
     if (keys.length === 1) state.activeDeck = keys[0]
   }
+  ensureActiveHtmlDeckRenderTarget(state)
+  return state
+}
+
+function normalizeDecksStateWithNarrative(input: DecksState): DecksState {
+  const state = normalizeDecksState(input)
+  if (!state.narrative && currentDeckKey(state)) state.narrative = normalizeNarrativeState(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/narrative-state/hash.ts

@@ -0,0 +1,52 @@
+import { createHash } from "crypto"
+import type { NarrativeStateV1 } from "./types"
+
+export function stableNarrativeId(seed: string): string {
+  return `narrative:${stableHash(seed || "workspace")}`
+}
+
+export function stableClaimId(text: string): string {
+  return `claim:${stableHash(text)}`
+}
+
+export function stableEvidenceId(claimId: string, seed: string): string {
+  return `evidence:${claimId}:${stableHash(seed)}`
+}
+
+export function stableObjectionId(text: string): string {
+  return `objection:${stableHash(text)}`
+}
+
+export function stableRiskId(text: string): string {
+  return `risk:${stableHash(text)}`
+}
+
+export function computeNarrativeHash(narrative: NarrativeStateV1): string {
+  return stableHash(stableStringify({
+    version: narrative.version,
+    id: narrative.id,
+    audience: narrative.audience,
+    decision: narrative.decision,
+    thesis: narrative.thesis,
+    claims: narrative.claims,
+    evidenceBindings: narrative.evidenceBindings,
+    objections: narrative.objections,
+    risks: narrative.risks,
+  }))
+}
+
+export function stableHash(input: unknown): string {
+  const text = typeof input === "string" ? input : stableStringify(input)
+  return createHash("sha1").update(text).digest("hex").slice(0, 12)
+}
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, item]) => item !== undefined)
+      .sort(([a], [b]) => a.localeCompare(b))
+    return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`
+  }
+  return JSON.stringify(value)
+}