dsh-logicprobe 0.9.0 → 1.1.0

package/src/uml.ts

@@ -31,7 +31,7 @@
  * @module logicprobe-uml
  */
 
-import { validateModel, modelHash } from './engine.js'
+import { REPORT_SCHEMAS, validateModel, modelHash, metadataKeysOf, narrativeComplete, narrativeCoverageOf, verdictOfFindings, DEFAULT_HASH_SPEC, type HashSpec, type NarrativeCoverage, type ReportSchema, type Verdict } from './engine.js'
 import type { GuardNode, GuardOp, LeafGuard, LogicModelV1, StateSpec, TransitionSpec, UpdateSpec, VariableSpec } from './engine.js'
 
 export type UmlNotation = 'mermaid' | 'plantuml'
@@ -72,9 +72,31 @@ export interface UmlParseResult {
    * symbol, which the review reports.
    */
   labels: Record<string, string>
+  /**
+   * Declarations found in the text that LogicModelV1 cannot represent. A non-empty
+   * list means the parsed model is NOT this diagram: the text belongs to another
+   * diagram family (component, package, class, deployment, …), so whatever came
+   * out is a by-product of reading keywords the parser does not own.
+   */
+  discardedConstructs: DiscardedConstruct[]
+  /**
+   * Arrows whose endpoints were declared by a discarded construct. They survive
+   * parsing as state transitions, which is exactly why they are counted out loud.
+   */
+  discardedEdges: number
   warnings: string[]
 }
 
+/** One declaration the parser could not represent, with the source line that carried it. */
+export interface DiscardedConstruct {
+  /** The construct keyword, lower-cased (`component`, `package`, `classDiagram`). */
+  construct: string
+  /** 1-based line number in the diagram source. */
+  line: number
+  /** The source line, trimmed. */
+  text: string
+}
+
 export interface UmlFinding {
   code: string
   severity: 'error' | 'warning' | 'info'
@@ -83,12 +105,16 @@ export interface UmlFinding {
   events?: string[]
   transitions?: Array<{ from: string; event: string; to: string }>
   detail?: string
+  /** Machine-readable context for the finding (ids, coverage, rule matches), same shape as the engine's findings. */
+  evidence?: Record<string, unknown>
 }
 
 export interface UmlRoundTripReport {
   notation: UmlNotation
   diagram: UmlDiagram
   ok: boolean
+  /** Which published hash specification the two hashes follow (see references/hash-spec.md). */
+  hashSpec: HashSpec
   modelHash: string
   parsedHash: string
   diffs: string[]
@@ -96,7 +122,13 @@ export interface UmlRoundTripReport {
 }
 
 export interface UmlReviewReport {
+  /** The review ran and produced this report. It does NOT mean the modelling passed — read `verdict`. */
   ok: boolean
+  ran: boolean
+  verdict: Verdict
+  verdictReason: string
+  /** The versioned report contract this result follows. */
+  schema: ReportSchema
   source: 'model' | 'diagram' | 'model+diagram'
   summary: {
     errors: number
@@ -117,11 +149,31 @@ export interface UmlReviewReport {
   model?: LogicModelV1
   /** Diagram rendered from the model, when only a model was given. */
   primary?: string
+  /** Paths of the `_`-prefixed metadata keys found in the supplied model, when it carried any. */
+  metadataKeys?: string[]
+  /** How much of the model the narrative documents; absent when there is no narrative. */
+  narrativeCoverage?: NarrativeCoverage
+  /** Hashes of what was reviewed, in one place. */
+  hashes: { hashSpec: HashSpec; modelHash?: string; parsedHash?: string }
+  /** Declarations the parser could not represent; a non-empty list fails the review. */
+  discardedConstructs?: DiscardedConstruct[]
+  /** Arrows whose endpoints came from a discarded construct. */
+  discardedEdges?: number
   warnings: string[]
   nextSteps: string[]
 }
 
-export class UmlError extends Error {}
+/**
+ * A UML front-end refusal. `code` lets the tool report *why* it refused instead of
+ * collapsing every refusal into a generic input error.
+ */
+export class UmlError extends Error {
+  readonly code: string
+  constructor(message: string, code = 'UML_INPUT') {
+    super(message)
+    this.code = code
+  }
+}
 
 // ---------------------------------------------------------------------------
 // Shared helpers
@@ -557,9 +609,34 @@ interface DiagramLine {
   diagram: 'state' | 'activity' | 'sequence'
 }
 
+/**
+ * Mermaid diagram-family headers that are neither a state machine nor a flow.
+ * Recognizing them matters twice: the text must not be reported as "cannot tell
+ * whether this is Mermaid or PlantUML", and it must not be parsed as a state
+ * diagram — every line of it would be ignored or misread, and the empty model that
+ * comes out would be presented as if it described the file.
+ */
+const MERMAID_OTHER_FAMILIES: readonly string[] = [
+  'classDiagram', 'erDiagram', 'gantt', 'pie', 'journey', 'mindmap', 'gitGraph',
+  'C4Context', 'C4Container', 'C4Component', 'C4Dynamic', 'C4Deployment',
+  'requirementDiagram', 'timeline', 'quadrantChart', 'sankey-beta', 'block-beta',
+  'packet-beta', 'architecture-beta', 'radar-beta', 'treemap-beta', 'xychart-beta',
+]
+
+/** The other-family header this text declares, if any. */
+function otherMermaidFamily(text: string): string | undefined {
+  for (const family of MERMAID_OTHER_FAMILIES) {
+    if (new RegExp('^\\s*' + family + '\\b', 'm').test(text)) return family
+  }
+  return undefined
+}
+
 function detectNotation(text: string): UmlNotation {
   if (/^\s*@start/m.test(text)) return 'plantuml'
   if (/^\s*(stateDiagram|stateDiagram-v2|flowchart|graph|sequenceDiagram)\b/m.test(text)) return 'mermaid'
+  // A known Mermaid family is still Mermaid: say so, and let detectDiagram refuse it
+  // by name instead of blaming the notation.
+  if (otherMermaidFamily(text) !== undefined) return 'mermaid'
   throw new UmlError('cannot tell whether this is Mermaid or PlantUML text: expected `stateDiagram-v2` / `flowchart` / `sequenceDiagram`, or `@startuml`')
 }
 
@@ -567,6 +644,10 @@ function detectDiagram(text: string): 'state' | 'activity' | 'sequence' {
   if (/^\s*stateDiagram/m.test(text)) return 'state'
   if (/^\s*(flowchart|graph)\b/m.test(text)) return 'activity'
   if (/^\s*sequenceDiagram\b/m.test(text)) return 'sequence'
+  const family = otherMermaidFamily(text)
+  if (family !== undefined) {
+    throw new UmlError('`' + family + '` is not a state or activity diagram: logicprobe models state machines and flows, so this diagram family cannot be parsed into a LogicModelV1. Discarded: ' + family + ' ×1. Render the machine with logicprobe_uml action=render and keep this diagram as its own view.', 'UML_NOT_A_STATE_DIAGRAM')
+  }
   if (/^\s*@startuml/m.test(text)) {
     // PlantUML declares the diagram kind by its body; the state keyword is the only
     // structural one logicprobe emits, everything else in that family is a state diagram too.
@@ -648,6 +729,10 @@ interface RawDiagram {
   terminals: string[]
   finalMarks: string[]
   warnings: string[]
+  /** Declarations that belong to another diagram family (component, package, class, …). */
+  discarded: DiscardedConstruct[]
+  /** Node names those declarations introduced; arrows touching them are counted as discarded edges. */
+  discardedNodes: Set<string>
 }
 
 function rawToModel(raw: RawDiagram, directives: Directives, warnings: string[]): LogicModelV1 {
@@ -762,37 +847,107 @@ function inferVariables(transitions: TransitionSpec[], declared: Map<string, 'in
   return [...kinds.entries()].map(([name, kind]) => ({ name, kind, init: kind === 'boolean' ? false : 0 }))
 }
 
+/**
+ * PlantUML keywords that declare a construct LogicModelV1 has no place for. Their
+ * presence marks the text as a component, package, class, deployment or database
+ * diagram — a different diagram family. A state parser still reads *something* out of
+ * such a file (the arrows look like transitions), which is why the discarded
+ * declarations are collected and reported instead of being ignored.
+ */
+const PLANTUML_OTHER_CONSTRUCT = /^(component|package|class|interface|enum|enumeration|object|actor|usecase|node|artifact|database|rectangle|folder|frame|cloud|storage|collections|queue|stack|agent|boundary|control|entity|deployment|protocol|struct|exception|metaclass|stereotype|circle|hexagon|label|port|portin|portout)\b/i
+
+/** The node identifier a declaration introduces, when it has one (`… as ID`, or a bare `component ID`). */
+function declaredIdentifier(text: string): string | undefined {
+  const alias = /\bas\s+([A-Za-z_][A-Za-z0-9_]*)\s*;?$/.exec(text)
+  if (alias !== null) return alias[1]
+  const bare = /^[A-Za-z]+\s+([A-Za-z_][A-Za-z0-9_]*)\s*;?$/.exec(text)
+  return bare === null ? undefined : bare[1]
+}
+
+/**
+ * Findings a parse result carries on its own. A diagram from another family parses
+ * into something; without this finding that something is presented as a model of the
+ * file, which is a false guarantee of exactly the kind this plugin exists to prevent.
+ */
+export function parseFindings(parsed: UmlParseResult): UmlFinding[] {
+  // A note block is reported in `discardedConstructs` for transparency, but it does not make
+  // the text "not a state diagram": the rest of the file still is one, so only the constructs
+  // that actually replace a state declaration count towards the refusal.
+  const unsupported = parsed.discardedConstructs.filter((entry) => entry.construct !== 'note')
+  if (unsupported.length === 0) return []
+  const counts = new Map<string, number>()
+  for (const entry of unsupported) counts.set(entry.construct, (counts.get(entry.construct) ?? 0) + 1)
+  const summary = [...counts.entries()]
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .map(([construct, count]) => construct + ' ×' + String(count))
+    .join(', ')
+  const shown = unsupported.slice(0, 12).map((entry) => 'line ' + String(entry.line) + ': ' + entry.text).join(' | ')
+  return [{
+    code: 'UML_NOT_A_STATE_DIAGRAM',
+    severity: 'error',
+    message: 'the text is not a state or activity diagram: ' + String(unsupported.length) + ' declaration(s) of unsupported construct(s) (' + summary + ') and ' + String(parsed.discardedEdges) + ' arrow(s) between them were read as states and transitions, so the parsed model is not this diagram.',
+    detail: shown + (unsupported.length > 12 ? ' | … ' + String(unsupported.length - 12) + ' more' : ''),
+  }]
+}
+
 function parseStateDiagram(text: string, notation: UmlNotation): UmlParseResult {
   const lines = text.split(/\r?\n/)
   const { directives, body } = readDirectives(lines, notation)
-  const raw: RawDiagram = { states: [], display: new Map(), edges: [], terminals: [], finalMarks: [], warnings: [] }
+  const raw: RawDiagram = { states: [], display: new Map(), edges: [], terminals: [], finalMarks: [], warnings: [], discarded: [], discardedNodes: new Set() }
+  let discardedEdges = 0
   const declared = new Set<string>()
   const declare = (name: string): void => { if (!declared.has(name)) { declared.add(name); raw.states.push(name) } }
   const skip = notation === 'mermaid'
     ? /^(stateDiagram|stateDiagram-v2|direction\b|classDef\b|class\b|style\b|linkStyle\b|click\b|hide\b|scale\b|title\b|accTitle\b|accDescr\b|%%\{)/
     : /^(@startuml|@enduml|scale\b|skinparam\b|title\b|hide\b|left to right direction|top to bottom direction|autonumber|!theme)/
-  for (const rawLine of body) {
+  let inNote = false
+  body.forEach((rawLine, index) => {
     const line = rawLine.trim()
-    if (line === '' || (line.startsWith('--') && !line.includes('-->'))) continue
-    if (skip.test(line)) continue
+    if (line === '' || (line.startsWith('--') && !line.includes('-->'))) return
+    if (skip.test(line)) return
+    const noteStart = /^note\b/i.test(line)
+    const noteEnd = /^end\s*note$/i.test(line)
+    if (notation === 'plantuml' && !inNote && !noteStart && !noteEnd) {
+      const other = PLANTUML_OTHER_CONSTRUCT.exec(line)
+      if (other !== null) {
+        raw.discarded.push({ construct: other[1].toLowerCase(), line: index + 1, text: line })
+        const id = declaredIdentifier(line)
+        if (id !== undefined) raw.discardedNodes.add(id)
+        return
+      }
+    }
+    if (noteEnd) { inNote = false; return }
+    // A multi-line note body is prose, not a statement: skip it silently rather than
+    // reporting one ignored line per line of text.
+    if (inNote) return
+    if (noteStart && !/:\s*.+$/.test(line)) {
+      // R7: a multi-line note block is prose the notation carries and LogicModelV1 does not.
+      // Its body is still skipped line by line, but the block itself is NOT silent: it is
+      // reported once, like any other unsupported construct, so "the diagram hash changed and
+      // the report said nothing" cannot happen. It stays out of `warnings` (no per-line noise)
+      // and `parseFindings` keeps it out of the "not a state diagram" verdict.
+      raw.discarded.push({ construct: 'note', line: index + 1, text: line })
+      inNote = true
+      return
+    }
     const note = /^note\s+(?:over|right of|left of)\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.+)$/i.exec(line)
     if (note !== null) {
       declare(note[1])
       const existing = raw.display.get(note[1])
       if (existing === undefined) raw.display.set(note[1], note[2].trim())
-      continue
+      return
     }
-    if (/^note\b/i.test(line) || /^end\s*note$/i.test(line)) continue
+    if (noteStart) return
     const stateDecl = /^state\s+"([^"]*)"\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(line)
-    if (stateDecl !== null) { declare(stateDecl[2]); raw.display.set(stateDecl[2], stateDecl[1]); continue }
+    if (stateDecl !== null) { declare(stateDecl[2]); raw.display.set(stateDecl[2], stateDecl[1]); return }
     const bareState = /^state\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{?$/.exec(line)
-    if (bareState !== null) { declare(bareState[1]); continue }
+    if (bareState !== null) { declare(bareState[1]); return }
     const concurrency = /^\}\s*$|^--\s*$/.test(line)
-    if (concurrency) { raw.warnings.push('UML_PARSE_CONCURRENCY_FLATTENED: a concurrency region or composite block was flattened; LogicModelV1 has no region construct (use logicprobe_compose_verify for parallel machines).'); continue }
+    if (concurrency) { raw.warnings.push('UML_PARSE_CONCURRENCY_FLATTENED: a concurrency region or composite block was flattened; LogicModelV1 has no region construct (use logicprobe_compose_verify for parallel machines).'); return }
     const composite = /^state\s+(.+)\s*\{$/.exec(line)
-    if (composite !== null) { raw.warnings.push('UML_PARSE_COMPOSITE_FLATTENED: composite state "' + composite[1].trim() + '" was flattened into its members.'); continue }
+    if (composite !== null) { raw.warnings.push('UML_PARSE_COMPOSITE_FLATTENED: composite state "' + composite[1].trim() + '" was flattened into its members.'); return }
     const description = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.+)$/.exec(line)
-    if (description !== null) { declare(description[1]); if (!raw.display.has(description[1])) raw.display.set(description[1], description[2].trim()); continue }
+    if (description !== null) { declare(description[1]); if (!raw.display.has(description[1])) raw.display.set(description[1], description[2].trim()); return }
     const edge = /^(.+?)\s*-->\s*(.+?)(?:\s*:\s*(.*))?$/.exec(line)
     if (edge !== null) {
       const from = edge[1].trim()
@@ -804,25 +959,26 @@ function parseStateDiagram(text: string, notation: UmlNotation): UmlParseResult
         } else {
           raw.initialState = to
         }
-        continue
+        return
       }
-      if (to === '[*]') { raw.finalMarks.push(from); continue }
+      if (to === '[*]') { raw.finalMarks.push(from); return }
       declare(from)
       declare(to)
+      if (raw.discardedNodes.has(from) || raw.discardedNodes.has(to)) discardedEdges += 1
       raw.edges.push({ from, to, label })
-      continue
+      return
     }
     raw.warnings.push('UML_PARSE_IGNORED_LINE: "' + line + '" is not a state diagram statement; it was ignored.')
-  }
+  })
   const model = rawToModel(raw, directives, raw.warnings)
   const labels = mapLabels(raw.display, directives)
-  return { notation, diagram: 'state', model, labels, warnings: raw.warnings }
+  return { notation, diagram: 'state', model, labels, discardedConstructs: raw.discarded, discardedEdges, warnings: raw.warnings }
 }
 
 function parseActivityDiagram(text: string, notation: UmlNotation): UmlParseResult {
   const lines = text.split(/\r?\n/)
   const { directives, body } = readDirectives(lines, notation)
-  const raw: RawDiagram = { states: [], display: new Map(), edges: [], terminals: [], finalMarks: [], warnings: [] }
+  const raw: RawDiagram = { states: [], display: new Map(), edges: [], terminals: [], finalMarks: [], warnings: [], discarded: [], discardedNodes: new Set() }
   const declared = new Set<string>()
   const declare = (name: string): void => { if (!declared.has(name)) { declared.add(name); raw.states.push(name) } }
   const skip = /^(flowchart|graph)\b|^(classDef|class|style|linkStyle|click|direction)\b|^%%\{/
@@ -858,7 +1014,7 @@ function parseActivityDiagram(text: string, notation: UmlNotation): UmlParseResu
   }
   const model = rawToModel(raw, directives, raw.warnings)
   const labels = mapLabels(raw.display, directives)
-  return { notation, diagram: 'activity', model, labels, warnings: raw.warnings }
+  return { notation, diagram: 'activity', model, labels, discardedConstructs: [], discardedEdges: 0, warnings: raw.warnings }
 }
 
 /**
@@ -892,6 +1048,68 @@ function mapLabels(display: Map<string, string>, directives: Directives): Record
   return out
 }
 
+/** One accepted way of writing a state's meaning into a diagram label. */
+export interface LabelForm {
+  form: string
+  example: string
+  note: string
+}
+
+export interface LabelExplanation {
+  notation: UmlNotation
+  /** The comment prefix a `logicprobe:` directive uses in this notation. */
+  directivePrefix: string
+  directiveLines: Array<{ example: string; meaning: string }>
+  /** Accepted label spellings, in the order `documentedMeaning` accepts them. */
+  acceptedLabelForms: LabelForm[]
+  /** What the renderer itself writes, so a hand-edited diagram can match it. */
+  renderedForm: string
+  ignoredLines: Array<{ pattern: string; behaviour: string }>
+  rules: string[]
+}
+
+/**
+ * What the front end expects of labels and comments, so "why does my hand-drawn diagram
+ * report label drift or ignored lines?" has a printed answer instead of a guess.
+ * `tests/uml/run.mjs` feeds every claim here back through the parser, so this text cannot
+ * drift away from the behaviour it describes.
+ */
+export function explainLabels(notation: UmlNotation = 'mermaid'): LabelExplanation {
+  const prefix = commentPrefix(notation)
+  return {
+    notation,
+    directivePrefix: prefix + DIRECTIVE_NAMESPACE,
+    directiveLines: [
+      { example: prefix + DIRECTIVE_NAMESPACE + 'uml v1 notation=' + notation + ' diagram=state', meaning: 'declares the notation and diagram kind the file was rendered for' },
+      { example: prefix + DIRECTIVE_NAMESPACE + 'init ID', meaning: 'pins the initial state (otherwise it is inferred as the only state nothing enters)' },
+      { example: prefix + DIRECTIVE_NAMESPACE + 'terminal ID', meaning: 'marks a terminal state; comma-separate several' },
+      { example: prefix + DIRECTIVE_NAMESPACE + 'alias NOTATION_ID model_id', meaning: 'restores a state id the notation cannot spell verbatim' },
+      { example: prefix + DIRECTIVE_NAMESPACE + 'variable NAME integer', meaning: 'restores a variable and its kind' },
+    ],
+    acceptedLabelForms: [
+      { form: 'bare id', example: 'state "IDLE" as IDLE', note: 'counts as NO meaning: the state stays undocumented (UML014)' },
+      { form: 'ID（meaning）', example: 'state "IDLE（waiting for power）" as IDLE', note: 'the form the renderer writes; full-width parentheses' },
+      { form: 'ID(meaning)', example: 'state "IDLE(waiting for power)" as IDLE', note: 'accepted as well' },
+      { form: 'a description line', example: 'IDLE : waiting for power', note: 'the same meaning written as a state description' },
+      { form: 'a single-line note', example: 'note right of IDLE : waiting for power', note: 'read as the state meaning, not as a comment' },
+      { form: 'any other text', example: 'state "waiting for power" as IDLE', note: 'taken as the meaning verbatim' },
+    ],
+    renderedForm: 'state "ID（meaning）" as ID',
+    ignoredLines: [
+      { pattern: 'a `' + prefix + '` comment line that is not a `logicprobe:` directive', behaviour: 'UML_PARSE_IGNORED_LINE warning: it carries no state-machine statement' },
+      { pattern: 'a `note …` block written over several lines', behaviour: 'its body is skipped line by line (prose, not a statement) and the block itself is reported once in discardedConstructs' },
+      { pattern: 'notation chrome: @startuml/@enduml, stateDiagram-v2, direction, classDef/style/linkStyle/click, scale, skinparam, title, hide, autonumber', behaviour: 'skipped silently' },
+      { pattern: 'anything else the parser cannot read', behaviour: 'UML_PARSE_IGNORED_LINE warning, and the model is built from what it did read' },
+    ],
+    rules: [
+      'Label drift (UML015) compares the meaning inside the label with narrative.states[id]: the wrapper is stripped, the remaining text must match character for character.',
+      'A meaning that differs only in wording is still drift — one of the two is stale, and the review cannot tell which.',
+      'Keep non-directive comments out of the diagram: `logicprobe:` directives are the only comment lines the parser consumes.',
+      'A missing label is not an error: the state renders as its bare id and is reported as undocumented (UML014).',
+    ],
+  }
+}
+
 /**
  * Parse a Mermaid or PlantUML diagram back into a LogicModelV1.
  *
@@ -907,7 +1125,7 @@ export function parseUml(text: string, notation: UmlNotation | 'auto' = 'auto'):
   const resolved = notation === 'auto' ? detectNotation(text) : notation
   const kind = detectDiagram(text)
   if (kind === 'sequence') {
-    throw new UmlError('a sequence diagram is a trace, not a machine: parsing it would drop every branch the trace did not walk. Render diagram "state" or "activity" and parse that instead.')
+    throw new UmlError('a sequence diagram is a trace, not a machine: parsing it would drop every branch the trace did not walk. Render diagram "state" or "activity" and parse that instead.', 'UML_NOT_A_STATE_DIAGRAM')
   }
   return kind === 'state' ? parseStateDiagram(text, resolved) : parseActivityDiagram(text, resolved)
 }
@@ -1137,8 +1355,22 @@ function structuralFindings(model: LogicModelV1, labels: Record<string, string>
       code: 'UML013_NO_NARRATIVE',
       severity: 'info',
       message: 'the model carries no narrative block: no state, event or scenario has a natural-language meaning, so a reader must re-derive every symbol from the source.',
-      detail: 'Add narrative.states / narrative.events / narrative.scenarios — the schema requires all three and full coverage once the block is present.',
+      detail: 'Add narrative.states / narrative.events / narrative.scenarios — a partial narrative is valid and its coverage is reported; write the states first and fill the rest in later.',
     })
+  } else {
+    // A narrative that covers part of the model is valid: states first, events and
+    // scenarios later is the natural authoring order. The gap is reported as coverage
+    // (and as this info finding), never as a validation failure.
+    const coverage = narrativeCoverageOf(model)
+    if (coverage !== undefined && !narrativeComplete(coverage)) {
+      findings.push({
+        code: 'UML027_NARRATIVE_PARTIAL',
+        severity: 'info',
+        message: 'the narrative covers part of the model: states ' + coverage.states + ', events ' + coverage.events + ', scenarios ' + coverage.scenarios + '. Every uncovered symbol still has to be re-derived from the source.',
+        detail: 'narrativeCoverage carries the same numbers; complete the missing entries when the behaviour settles.',
+        evidence: { narrativeCoverage: coverage },
+      })
+    }
   }
 
   const documented = labels === undefined ? undefined : Object.keys(labels).filter((id) => documentedMeaning(labels[id], id) !== undefined)
@@ -1229,7 +1461,7 @@ function compiledModel(input: unknown): LogicModelV1 {
   return validation.model
 }
 
-function roundTripOf(model: LogicModelV1, notation: UmlNotation, diagram: UmlDiagram, maxSteps: number): { report: UmlRoundTripReport; primary: string } {
+function roundTripOf(model: LogicModelV1, notation: UmlNotation, diagram: UmlDiagram, maxSteps: number): { report: UmlRoundTripReport; primary: string; parsed: UmlParseResult } {
   const rendered = renderUml(model, notation, diagram, maxSteps)
   const parsed = parseUml(rendered.primary, notation)
   const diffs = diffModels(model, parsed.model)
@@ -1238,12 +1470,14 @@ function roundTripOf(model: LogicModelV1, notation: UmlNotation, diagram: UmlDia
       notation,
       diagram,
       ok: diffs.length === 0,
+      hashSpec: DEFAULT_HASH_SPEC,
       modelHash: modelHash(model),
       parsedHash: modelHash(parsed.model),
       diffs,
       warnings: [...rendered.warnings, ...parsed.warnings],
     },
     primary: rendered.primary,
+    parsed,
   }
 }
 
@@ -1320,18 +1554,28 @@ export function reviewUml(options: UmlReviewOptions): UmlReviewReport {
   let parsed: UmlParseResult | undefined
   let primary: string | undefined
   let roundTrip: UmlRoundTripReport | null = null
+  const metadataKeys = metadataKeysOf(hasModel ? options.model : undefined)
+  const metadata = metadataKeys.length === 0 ? {} : { metadataKeys }
+  let discardedConstructs: DiscardedConstruct[] = []
+  let discardedEdges = 0
 
   if (hasDiagram) {
     try {
       parsed = parseUml(options.diagram as string, options.notation ?? 'auto')
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error)
+      const unreadable: UmlFinding = { code: 'UML001_DIAGRAM_UNREADABLE', severity: 'error', message, detail: 'The diagram could not be read as a Mermaid/PlantUML state or activity diagram.' }
       return {
         ok: false,
+        ran: true,
+        ...verdictOfFindings([unreadable]),
+        schema: REPORT_SCHEMAS.umlReview,
         source: hasModel ? 'model+diagram' : 'diagram',
         summary: { errors: 1, warnings: 0, info: 0, states: 0, events: 0, transitions: 0, terminalStates: 0, reachableStates: 0, documentedStates: 0 },
-        findings: [{ code: 'UML001_DIAGRAM_UNREADABLE', severity: 'error', message, detail: 'The diagram could not be read as a Mermaid/PlantUML state or activity diagram.' }],
+        findings: [unreadable],
         roundTrip: null,
+        ...metadata,
+        hashes: { hashSpec: DEFAULT_HASH_SPEC },
         warnings,
         nextSteps: ['Fix the diagram syntax (or render one from a model with logicprobe_uml action=render) and review again.'],
       }
@@ -1339,6 +1583,13 @@ export function reviewUml(options: UmlReviewOptions): UmlReviewReport {
     notation = parsed.notation
     labels = parsed.labels
     warnings.push(...parsed.warnings)
+    // A diagram from another family parses into something; that something must never
+    // be read as a model of this file, so the parse defects are review findings here too.
+    findings.push(...parseFindings(parsed))
+    if (parsed.discardedConstructs.length > 0) {
+      discardedConstructs = parsed.discardedConstructs
+      discardedEdges = parsed.discardedEdges
+    }
     if (hasModel) {
       model = compiledModel(options.model)
       const diffs = diffModels(model, parsed.model)
@@ -1346,6 +1597,7 @@ export function reviewUml(options: UmlReviewOptions): UmlReviewReport {
         notation: parsed.notation,
         diagram: parsed.diagram,
         ok: diffs.length === 0,
+        hashSpec: DEFAULT_HASH_SPEC,
         modelHash: modelHash(model),
         parsedHash: modelHash(parsed.model),
         diffs,
@@ -1431,13 +1683,18 @@ export function reviewUml(options: UmlReviewOptions): UmlReviewReport {
     ? (model.narrative?.states === undefined ? 0 : Object.keys(model.narrative.states).length)
     : Object.keys(labels).filter((id) => documentedMeaning(labels?.[id], id) !== undefined).length
   const events = new Set(model.transitions.map((transition) => transition.event))
+  const narrativeCoverage = narrativeCoverageOf(model)
   const nextSteps: string[] = []
   if (errors > 0) nextSteps.push('Resolve the error findings first — a diagram that cannot be read (or that disagrees with its model) will mislead every later review.')
+  if (findings.some((finding) => finding.code === 'UML_NOT_A_STATE_DIAGRAM')) nextSteps.push('This text is not a state or activity diagram: keep it as its own view and model the machine as a state/activity diagram before reviewing it.')
   nextSteps.push('Run logicprobe_verify on this model for the behavioural checks (S1-S8 structural, A1-A14 adversarial); the review above covers modelling, not behaviour.')
   if (model.narrative === undefined) nextSteps.push('Add narrative.states/events/scenarios so the diagram is readable against the code.')
   if (findings.some((finding) => finding.code === 'UML011_UNBOUNDED_VARIABLE')) nextSteps.push('Declare min/max (or boundaryChecks) before relying on A5 boundary probes.')
   return {
     ok: true,
+    ran: true,
+    ...verdictOfFindings(findings),
+    schema: REPORT_SCHEMAS.umlReview,
     source: hasModel && hasDiagram ? 'model+diagram' : (hasDiagram ? 'diagram' : 'model'),
     summary: {
       errors,
@@ -1455,6 +1712,13 @@ export function reviewUml(options: UmlReviewOptions): UmlReviewReport {
     ...(labels === undefined ? {} : { labels }),
     ...(hasDiagram ? { model } : {}),
     ...(primary === undefined ? {} : { primary }),
+    ...metadata,
+    ...(narrativeCoverage === undefined ? {} : { narrativeCoverage }),
+    hashes: {
+      hashSpec: DEFAULT_HASH_SPEC,
+      ...(roundTrip === null ? {} : { modelHash: roundTrip.modelHash, parsedHash: roundTrip.parsedHash }),
+    },
+    ...(discardedConstructs.length === 0 ? {} : { discardedConstructs, discardedEdges }),
     warnings,
     nextSteps,
   }