@cyber-dash-tech/revela 0.13.0 → 0.14.0

package/lib/inspection-context/project.ts

@@ -1,5 +1,5 @@
 import type { NarrativeBrief, NarrativeRole } from "../decks-state"
-import type { InspectionContext, InspectionEvidenceTrace, InspectionGap } from "./compile"
+import type { InspectionClaimCandidate, InspectionContext, InspectionEvidenceTrace, InspectionGap } from "./compile"
 import type { InspectionElementMatch, InspectionElementSnapshot, InspectionMatchConfidence } from "./match"
 
 export interface InspectionPromptProjection {
@@ -13,6 +13,7 @@ export interface InspectionPromptProjection {
     caveats: InspectionCaveatsProjection
     objective: InspectionObjectiveProjection
     appendix: InspectionAppendixProjection
+    artifacts: InspectionArtifactCoverageProjection
   }
 }
 
@@ -28,11 +29,15 @@ export interface InspectionProjectionElement {
   scope?: "element" | "selection" | "slide"
   slideIndex?: number
   text?: string
+  nearbyText?: string
+  outerHTMLExcerpt?: string
   elements?: Array<{
     text?: string
     tagName?: string
     classList: string[]
     role?: string
+    nearbyText?: string
+    outerHTMLExcerpt?: string
   }>
   tagName?: string
   classList: string[]
@@ -60,6 +65,20 @@ export interface InspectionProjectionMatch {
     unsupportedScope?: string
     caveats: string[]
   }
+  candidateClaims?: InspectionProjectionClaimCandidate[]
+}
+
+export interface InspectionProjectionClaimCandidate {
+  id: string
+  canonicalClaimId?: string
+  origin: string
+  text: string
+  evidenceSensitive: boolean
+  evidenceSupport: string
+  evidenceBindingIds: string[]
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats: string[]
 }
 
 export interface InspectionSourceProjection {
@@ -100,6 +119,32 @@ export interface InspectionAppendixProjection {
   relatedObjections: string[]
 }
 
+export interface InspectionArtifactCoverageProjection {
+  selectedClaimId?: string
+  artifacts: InspectionArtifactCoverageProjectionItem[]
+}
+
+export interface InspectionArtifactCoverageProjectionItem {
+  artifactId: string
+  type: string
+  outputPath?: string
+  coverageStatus: "current" | "stale" | "partial" | "missing"
+  containsClaim: boolean
+  stale: boolean
+  staleReason?: string
+  staleReasons: string[]
+  affectedClaimIds: string[]
+  missingClaimIds: string[]
+  note?: string
+  locations: Array<{
+    slideIndex: number
+    slideTitle: string
+    role: string
+    match: string
+    location: string
+  }>
+}
+
 export interface InspectionEvidenceProjectionTrace {
   source: string
   evidenceBindingId?: string
@@ -132,6 +177,7 @@ export function projectInspectionMatch(
 ): InspectionPromptProjection {
   const slide = match.slide
   const claim = match.claim
+  const candidateClaims = dedupeClaims(match.candidateClaims ?? [])
   const traces = match.evidence.map(projectEvidenceTrace)
   const gaps = match.gaps.map(projectGap)
   const narrativeBrief = context.narrativeBrief
@@ -149,11 +195,15 @@ export function projectInspectionMatch(
       slideIndex: snapshot.slideIndex,
       scope: snapshot.scope,
       text: truncateOptional(snapshot.selectedText || snapshot.text, 700),
+      nearbyText: truncateOptional(snapshot.nearbyText, 900),
+      outerHTMLExcerpt: truncateOptional(snapshot.outerHTMLExcerpt, 900),
       elements: snapshot.elements?.slice(0, 12).map((item) => ({
         text: truncateOptional(item.text, 320),
         tagName: truncateOptional(item.tagName, 40),
         classList: (item.classList ?? []).slice(0, 8).map((className) => truncate(className, 80)),
         role: truncateOptional(item.role, 80),
+        nearbyText: truncateOptional(item.nearbyText, 420),
+        outerHTMLExcerpt: truncateOptional(item.outerHTMLExcerpt, 420),
       })),
       tagName: truncateOptional(snapshot.tagName, 40),
       classList: (snapshot.classList ?? []).slice(0, 12).map((item) => truncate(item, 80)),
@@ -171,19 +221,9 @@ export function projectInspectionMatch(
           }
         : undefined,
       claim: claim
-        ? {
-            id: claim.id,
-            canonicalClaimId: claim.canonicalClaimId,
-            origin: claim.origin,
-            text: truncate(claim.text, 500),
-            evidenceSensitive: claim.evidenceSensitive,
-            evidenceSupport: claim.evidenceSupport,
-            evidenceBindingIds: claim.evidenceBindingIds,
-            supportedScope: truncateOptional(claim.supportedScope, 280),
-            unsupportedScope: truncateOptional(claim.unsupportedScope, 280),
-            caveats: claim.caveats.map((item) => truncate(item, 280)).slice(0, 8),
-          }
+        ? projectClaimCandidate(claim)
         : undefined,
+      candidateClaims: candidateClaims.map(projectClaimCandidate).slice(0, 8),
     },
     cards: {
       source: {
@@ -219,10 +259,73 @@ export function projectInspectionMatch(
         relatedRisks: relatedNarrativeText(context.riskContext, slide?.index),
         relatedObjections: relatedNarrativeText(context.objectionContext, slide?.index),
       },
+      artifacts: projectArtifactCoverage(context, claim?.canonicalClaimId ?? claim?.id),
     },
   }
 }
 
+function projectClaimCandidate(claim: InspectionClaimCandidate): InspectionProjectionClaimCandidate {
+  return {
+    id: claim.id,
+    canonicalClaimId: claim.canonicalClaimId,
+    origin: claim.origin,
+    text: truncate(claim.text, 500),
+    evidenceSensitive: claim.evidenceSensitive,
+    evidenceSupport: claim.evidenceSupport,
+    evidenceBindingIds: claim.evidenceBindingIds,
+    supportedScope: truncateOptional(claim.supportedScope, 280),
+    unsupportedScope: truncateOptional(claim.unsupportedScope, 280),
+    caveats: claim.caveats.map((item) => truncate(item, 280)).slice(0, 8),
+  }
+}
+
+function dedupeClaims(claims: InspectionClaimCandidate[]): InspectionClaimCandidate[] {
+  const seen = new Set<string>()
+  const result: InspectionClaimCandidate[] = []
+  for (const claim of claims) {
+    const key = claim.canonicalClaimId || claim.id
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(claim)
+  }
+  return result
+}
+
+function projectArtifactCoverage(context: InspectionContext, selectedClaimId: string | undefined): InspectionArtifactCoverageProjection {
+  return {
+    selectedClaimId,
+    artifacts: context.artifactCoverage.map((artifact) => {
+      const locations = selectedClaimId
+        ? artifact.slideRefs
+          .filter((ref) => ref.claimId === selectedClaimId)
+          .slice(0, 8)
+          .map((ref) => ({
+            slideIndex: ref.slideIndex,
+            slideTitle: truncate(ref.slideTitle, 180),
+            role: ref.role,
+            match: ref.match,
+            location: truncate(ref.location, 120),
+          }))
+        : []
+      const containsClaim = Boolean(selectedClaimId && (artifact.claimIds.includes(selectedClaimId) || locations.length > 0))
+      return {
+        artifactId: truncate(artifact.artifactId, 180),
+        type: artifact.type,
+        outputPath: truncateOptional(artifact.outputPath, 220),
+        coverageStatus: artifact.coverageStatus,
+        containsClaim,
+        stale: artifact.stale,
+        staleReason: truncateOptional(artifact.staleReason, 240),
+        staleReasons: artifact.staleReasons.map((item) => truncate(item, 240)).slice(0, 5),
+        affectedClaimIds: artifact.affectedClaimIds.map((item) => truncate(item, 160)).slice(0, 8),
+        missingClaimIds: artifact.missingClaimIds.map((item) => truncate(item, 160)).slice(0, 8),
+        note: truncateOptional(artifact.note, 240),
+        locations,
+      }
+    }).slice(0, 8),
+  }
+}
+
 function projectEvidenceTrace(trace: InspectionEvidenceTrace): InspectionEvidenceProjectionTrace {
   return {
     source: truncate(trace.source, 180),

package/lib/inspection-context/result.ts

@@ -4,6 +4,8 @@ import type { InspectionPromptProjection } from "./project"
 export type InspectionResultStatus = "success" | "no_match"
 export type InspectionPurposeStatus = "clear" | "weak" | "misplaced" | "unknown"
 export type InspectionSourceStatus = "supported" | "weak" | "unsupported" | "not_needed" | "unknown"
+export type NarrativeReadingStatus = "matched" | "no_match"
+export type ExploratoryReadingStatus = "available" | "limited" | "unavailable"
 
 export interface InspectionResult {
   version: 1
@@ -16,6 +18,8 @@ export interface InspectionResult {
   }
   matchConfidence: InspectionMatchConfidence
   cards: {
+    reading?: NarrativeReadingCard
+    exploratory?: ExploratoryReadingCard
     purpose: PurposeCard
     source: SourceCard
   }
@@ -53,6 +57,47 @@ export interface SourceCard {
   rationale: string
 }
 
+export interface NarrativeReadingCard {
+  status: NarrativeReadingStatus
+  claimId?: string
+  canonicalClaimId?: string
+  claimText?: string
+  evidenceStatus?: string
+  evidenceBindingIds: string[]
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats: string[]
+  relatedObjections: string[]
+  relatedRisks: string[]
+  artifactCoverage: NarrativeReadingArtifactCoverage[]
+  rationale: string
+}
+
+export interface NarrativeReadingArtifactCoverage {
+  artifactId: string
+  type: string
+  outputPath?: string
+  coverageStatus: "current" | "stale" | "partial" | "missing"
+  containsClaim: boolean
+  stale: boolean
+  staleReason?: string
+  locations: string[]
+  note?: string
+}
+
+export interface ExploratoryReadingCard {
+  status: ExploratoryReadingStatus
+  official: false
+  audience?: string
+  claimFocus?: string
+  objectionPrompts: string[]
+  audienceReframe: string
+  appendixLeads: string[]
+  meetingPrep: string[]
+  boundaries: string[]
+  rationale: string
+}
+
 export function buildDeterministicInspectionResult(
   projection: InspectionPromptProjection,
   options: { requestId?: string; staleReason?: string } = {},
@@ -72,6 +117,8 @@ export function buildDeterministicInspectionResult(
     slide: slide ? { index: slide.index, title: slide.title } : undefined,
     matchConfidence: projection.match.confidence,
     cards: {
+      reading: narrativeReadingCard(projection, noMatch),
+      exploratory: exploratoryReadingCard(projection, noMatch),
       purpose: {
         status: purposeStatus(projection, noMatch),
         role: projection.cards.objective.narrativeRole,
@@ -101,6 +148,126 @@ export function buildDeterministicInspectionResult(
   }
 }
 
+function exploratoryReadingCard(projection: InspectionPromptProjection, noMatch: boolean): ExploratoryReadingCard {
+  const claimText = projection.match.claim?.text ?? projection.cards.evidence.matchedClaim
+  const caveats = projection.cards.caveats.caveats
+  const unsupportedScope = projection.match.claim?.unsupportedScope ?? firstPresent(projection.cards.evidence.traces.map((item) => item.unsupportedScope))
+  const objectionPrompts = exploratoryObjections(projection, unsupportedScope)
+  const appendixLeads = exploratoryAppendixLeads(projection)
+  const meetingPrep = exploratoryMeetingPrep(projection, unsupportedScope)
+  return {
+    status: noMatch ? "unavailable" : claimText ? "available" : "limited",
+    official: false,
+    audience: projection.cards.objective.audience,
+    claimFocus: claimText,
+    objectionPrompts,
+    audienceReframe: exploratoryAudienceFrame(projection, claimText),
+    appendixLeads,
+    meetingPrep,
+    boundaries: exploratoryBoundaries(projection, noMatch),
+    rationale: exploratoryRationale(projection, noMatch, objectionPrompts.length + appendixLeads.length + meetingPrep.length),
+  }
+}
+
+function exploratoryObjections(projection: InspectionPromptProjection, unsupportedScope: string | undefined): string[] {
+  const items = projection.cards.appendix.relatedObjections.map((item) => `Prepare for this objection using recorded support only: ${item}`)
+  if (unsupportedScope) items.push(`Expect questions about unsupported scope: ${unsupportedScope}`)
+  for (const gap of projection.cards.evidence.gaps) items.push(`Treat this as an evidence gap, not as support: ${gap.message}`)
+  return dedupe(items).slice(0, 4)
+}
+
+function exploratoryAudienceFrame(projection: InspectionPromptProjection, claimText: string | undefined): string {
+  const audience = projection.cards.objective.audience
+  const beliefAfter = projection.cards.objective.audienceBeliefAfter
+  const decision = projection.cards.objective.decisionOrAction
+  if (!claimText) return "No specific claim is matched, so audience reframing is limited to the selected slide context."
+  if (audience && beliefAfter) return `For ${audience}, frame this claim as support for the desired belief: ${beliefAfter}`
+  if (audience && decision) return `For ${audience}, connect this claim to the recorded decision or action: ${decision}`
+  if (audience) return `For ${audience}, keep the wording inside the recorded claim boundary: ${claimText}`
+  return "Audience-specific reframing is limited because no audience is recorded in the projection."
+}
+
+function exploratoryAppendixLeads(projection: InspectionPromptProjection): string[] {
+  const sourceLeads = projection.cards.evidence.traces.map((trace) => {
+    const where = trace.location || trace.page || trace.url || trace.sourcePath || trace.findingsFile
+    return where ? `${trace.source}: ${where}` : trace.source
+  })
+  const appendixCandidates = projection.cards.appendix.candidates.map((candidate) => `Slide ${candidate.slideIndex}: ${candidate.slideTitle} (${candidate.reason})`)
+  return dedupe([...sourceLeads, ...appendixCandidates]).slice(0, 5)
+}
+
+function exploratoryMeetingPrep(projection: InspectionPromptProjection, unsupportedScope: string | undefined): string[] {
+  const items: string[] = []
+  for (const risk of projection.cards.appendix.relatedRisks) items.push(`Risk to be ready for: ${risk}`)
+  for (const caveat of projection.cards.caveats.caveats) items.push(`Caveat to say plainly: ${caveat}`)
+  if (unsupportedScope) items.push(`Do not overstate beyond: ${unsupportedScope}`)
+  for (const warning of projection.cards.source.weakSourceGaps) items.push(`Source trace is weak: ${warning.message}`)
+  for (const gap of projection.cards.source.missingSourceGaps) items.push(`Missing support: ${gap.message}`)
+  return dedupe(items).slice(0, 5)
+}
+
+function exploratoryBoundaries(projection: InspectionPromptProjection, noMatch: boolean): string[] {
+  const boundaries = [
+    "Exploratory reading is non-official and does not change canonical narrative state or artifact content.",
+    "Use only recorded claims, evidence, caveats, risks, objections, and artifact coverage from this inspection projection.",
+  ]
+  if (noMatch) boundaries.push("No matched slide or claim is available, so exploratory reading cannot infer support.")
+  if (projection.cards.evidence.gaps.length > 0) boundaries.push("Evidence gaps must remain visible and cannot be filled by generated reading text.")
+  return boundaries
+}
+
+function exploratoryRationale(projection: InspectionPromptProjection, noMatch: boolean, signalCount: number): string {
+  if (noMatch) return "Exploratory reading is unavailable because the selection did not match a slide or claim."
+  if (signalCount > 0) return "This bounded reading layer derives objection, audience, appendix, and meeting-prep cues from recorded inspection context only."
+  if (projection.match.claim) return "A matched claim exists, but little supporting exploratory context is recorded beyond the claim itself."
+  return "Exploratory reading is limited because the selection maps to slide context but not to a specific claim."
+}
+
+function narrativeReadingCard(projection: InspectionPromptProjection, noMatch: boolean): NarrativeReadingCard {
+  const claim = projection.match.claim
+  const evidenceBindingIds = dedupe([
+    ...(claim?.evidenceBindingIds ?? []),
+    ...projection.cards.evidence.traces.map((item) => item.evidenceBindingId).filter((item): item is string => Boolean(item)),
+  ])
+  return {
+    status: noMatch ? "no_match" : "matched",
+    claimId: claim?.id,
+    canonicalClaimId: claim?.canonicalClaimId,
+    claimText: claim?.text ?? projection.cards.evidence.matchedClaim,
+    evidenceStatus: claim?.evidenceSupport ?? projection.cards.evidence.evidenceSupport,
+    evidenceBindingIds,
+    supportedScope: claim?.supportedScope ?? firstPresent(projection.cards.evidence.traces.map((item) => item.supportScope)),
+    unsupportedScope: claim?.unsupportedScope ?? firstPresent(projection.cards.evidence.traces.map((item) => item.unsupportedScope)),
+    caveats: projection.cards.caveats.caveats,
+    relatedObjections: projection.cards.appendix.relatedObjections,
+    relatedRisks: projection.cards.appendix.relatedRisks,
+    artifactCoverage: artifactCoverage(projection),
+    rationale: narrativeReadingRationale(projection, noMatch),
+  }
+}
+
+function artifactCoverage(projection: InspectionPromptProjection): NarrativeReadingArtifactCoverage[] {
+  return projection.cards.artifacts.artifacts.map((artifact) => ({
+    artifactId: artifact.artifactId,
+    type: artifact.type,
+    outputPath: artifact.outputPath,
+    coverageStatus: artifact.coverageStatus,
+    containsClaim: artifact.containsClaim,
+    stale: artifact.stale,
+    staleReason: artifact.staleReason,
+    locations: artifact.locations.map((location) => `Slide ${location.slideIndex}: ${location.slideTitle} (${location.role}, ${location.match}:${location.location})`),
+    note: artifact.note ?? artifact.staleReasons[0],
+  }))
+}
+
+function narrativeReadingRationale(projection: InspectionPromptProjection, noMatch: boolean): string {
+  if (noMatch) return "No matched slide or claim is available for narrative reading."
+  const claim = projection.match.claim
+  if (claim?.canonicalClaimId) return "The selection resolves to a canonical narrative claim, so Refine can show claim, evidence-boundary, caveat, objection, and risk context before any generated judgment."
+  if (claim) return "The selection resolves to a slide claim candidate. Canonical narrative linkage is not recorded for this element, so reading context falls back to slide claim and source trace."
+  return "The selection resolves to a slide but not a specific claim; narrative reading is limited to slide purpose, role, and surrounding evidence context."
+}
+
 function purposeStatus(projection: InspectionPromptProjection, noMatch: boolean): InspectionPurposeStatus {
   if (noMatch) return "unknown"
   if (projection.cards.objective.narrativeRole || projection.cards.objective.slidePurpose) return "clear"
@@ -158,3 +325,19 @@ function sourceCaveats(projection: InspectionPromptProjection): string[] {
     ...projection.cards.appendix.relatedObjections,
   ].slice(0, 10)
 }
+
+function firstPresent(values: Array<string | undefined>): string | undefined {
+  return values.find((value) => Boolean(value?.trim()))
+}
+
+function dedupe(values: string[]): string[] {
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const value of values) {
+    const key = value.trim()
+    if (!key || seen.has(key)) continue
+    seen.add(key)
+    result.push(key)
+  }
+  return result
+}

package/lib/narrative-state/queries.ts

@@ -352,6 +352,7 @@ function pushSlideRef(refs: ClaimSlideRef[], seen: Set<string>, claim: Narrative
 function claimSlideRefsForTarget(target: RenderTarget, currentHtmlRefs: ClaimSlideRef[], htmlCoverageByPath: Map<string, ClaimSlideRef[]>): ClaimSlideRef[] {
   const stored = parseStoredClaimSlideRefs(target)
   if (stored.length > 0) return stored
+  if (target.type === "brief" || target.type === "executive_brief") return []
   if (target.type === "html_deck") return currentHtmlRefs
   const sourceOutputPath = typeof target.data?.sourceOutputPath === "string" ? target.data.sourceOutputPath : undefined
   if (sourceOutputPath) return htmlCoverageByPath.get(sourceOutputPath) ?? currentHtmlRefs