dsh-logicprobe 0.9.0 → 1.0.0

package/src/tool.ts

@@ -10,13 +10,13 @@ export const LOGICPROBE_VERIFY_TOOL_NAME = 'logicprobe_verify'
  * the 22-check report (S1-S8 structural, A1-A14), or a 26-check
  * report when beforeModel is supplied (D1 behavioral preservation, D2
  * invariant continuity, D3 regression delta, D4 deadlock/liveness regression).
- * This is the dsh-native replacement for hand-filling the Python template
- * shipped in the skill references.
+ * This is the dsh-native path: the model is built and run here, with no
+ * template to fill in by hand.
  */
 export const logicProbeVerifyTool = defineTool({
   name: LOGICPROBE_VERIFY_TOOL_NAME,
   description:
-    'Run executable state-machine verification (logicprobe). Takes a LogicModelV1 object with schemaVersion=1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?, cost?}), variables?, invariants?, concurrentPairs?, boundaryChecks?, resourcePairs?, idempotentEvents?, narrative?. Guards are structured ({variable, op, value} | {all} | {any} | {not}); invariants support never-states, var-in-range ({variable, min?, max?, when?} — when scopes the range to a state ({state}) or a guard node, is evaluated on the post-state of every transition, leaves the initial state checked unconditionally, and is rejected on any other invariant kind), event-before-state, leads-to (`to` is one state id or a non-empty array of them: every path must reach at least one member), sequence, atomicity, budget (transition cost defaults to 1; A12 checks every reachable path stays within the declared budget and reports the shortest over-budget counterexample), and probability (transition weight, default 1, makes the model a DTMC; A13 checks P(hit target) against the bound by value iteration), and deadline (declaring maxTicks on a state is how many tick steps it may stay resident and the top-level tickEvents list names those steps; A14 reports the over-residency path, and A14_NO_TICK_EVENTS when maxTicks is declared without tickEvents). The schema is closed: an undeclared key on any model part (model, state, transition, update, variable, invariant, boundaryCheck, resourcePair, narrative, scenario) is a validation error, never ignored. Variables support monotonic inc/dec. The optional narrative block carries natural-language descriptions of states (narrative.states), events (narrative.events), and (state, event) scenarios (narrative.scenarios: [{from, event, scenario}]); when present it must fully cover the model and is echoed in the report. Returns a report with S1-S8 structural checks and A1-A14 adversarial, cost, probability and deadline probes, including counterexample paths (shortest where the search is breadth-first). If beforeModel is provided, also runs D1-D4 before/after regression checks. See skills/logicprobe/references/dsh-model-schema.md.',
+    'Run state-machine verification on a LogicModelV1 object. Model shape: schemaVersion 1, init, states ({id, terminal?}), transitions ({from, event, to, guard?, updates?, cost?}), plus optional variables, invariants, concurrentPairs, boundaryChecks, resourcePairs, idempotentEvents and narrative. Guards are structured: {variable, op, value}, {all}, {any} or {not}. Invariants cover never-states, var-in-range, event-before-state, leads-to, sequence, atomicity, budget, probability and deadline. `cost` defaults to 1 and drives the A12 budget check. `weight` defaults to 1 and makes the model a DTMC for A13. A state with `maxTicks` needs top-level `tickEvents`; A14 reports over-residency. The schema is closed: an undeclared key is a validation error. Keys starting with `_` are metadata: ignored, kept out of `modelHash`, and echoed as `metadataKeys`. Variables support monotonic inc and dec. Pass `beforeModel` and `stateMapping` to add the D1-D4 regression. Read `verdict`, never `ok`. The full schema is in the `logicprobe` skill: references/dsh-model-schema.md.',
   parameters: {
     model: {
       type: 'json',

package/src/uml-tool.ts

@@ -1,6 +1,8 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createHash } from 'node:crypto'
 import type { JsonValue } from './json-value.js'
-import { renderUml, parseUml, reviewUml, UmlError, type UmlDiagram, type UmlNotation } from './uml.js'
+import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, verdictOf, verdictOfFindings, type VerdictSummary } from './engine.js'
+import { renderUml, parseUml, parseFindings, reviewUml, UmlError, type UmlDiagram, type UmlFinding, type UmlNotation, type UmlParseResult } from './uml.js'
 
 export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
 
@@ -19,7 +21,7 @@ export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
 export const logicProbeUmlTool = defineTool({
   name: LOGICPROBE_UML_TOOL_NAME,
   description:
-    'Model a code flow as UML, and review the modelling. action="render" turns a LogicModelV1 (schemaVersion=1) into diagram source: notation mermaid (state | activity flowchart | sequence) or plantuml (state | sequence). action="parse" reads Mermaid/PlantUML state or activity text back into a LogicModelV1 (plus the display labels it found), so a hand-drawn diagram can be verified with logicprobe_verify; a sequence diagram is refused because a trace cannot reconstruct a machine. action="review" audits the modelling: structural defects (UML002 unreachable state, UML003 dead end, UML004 ambiguous branch, UML005 overlapping guard, UML006 inexhaustive branch, UML007 unused event, UML008 self-loop with no exit, UML009 duplicate transition), documentation gaps (UML010 unused variable, UML011 unbounded variable, UML012 no terminal, UML013 no narrative, UML014 undocumented state, UML015 label drift), and the fidelity check — the diagram is rendered and re-parsed and any structural difference is reported as UML017 round-trip mismatch. Give review a model (checks it, renders and re-parses it), a diagram (parses and reviews that), or both (checks the diagram against the model). Rendering never invents structure and never silently drops a construct the notation cannot express: those become warnings. Review does NOT replace logicprobe_verify — it covers the modelling, not behaviour; findings name the engine check to run next.',
+    'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Read `verdict`, not `ok`: error findings mean a failed review.',
   parameters: {
     action: {
       type: 'string',
@@ -79,12 +81,31 @@ export const logicProbeUmlTool = defineTool({
       if (args.action === 'render') {
         if (args.model === undefined) return errorResult('action=render needs `model` (a LogicModelV1 object)')
         const result = renderUml(args.model, (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation, (args.kind ?? 'state') as UmlDiagram, args.maxSteps)
-        return { ok: true, action: 'render', notation: result.notation, kind: result.diagram, diagram: result.primary, warnings: result.warnings } as unknown as JsonValue
+        return { ok: true, ran: true, ...verdictOf(0, result.warnings.length), schema: REPORT_SCHEMAS.umlRender, action: 'render', notation: result.notation, kind: result.diagram, diagram: result.primary, hashes: { diagram: createHash('sha256').update(result.primary).digest('hex') }, warnings: result.warnings } as unknown as JsonValue
       }
       if (args.action === 'parse') {
         if (args.diagram === undefined) return errorResult('action=parse needs `diagram` (Mermaid or PlantUML text)')
         const result = parseUml(args.diagram, args.notation ?? 'auto')
-        return { ok: true, action: 'parse', notation: result.notation, kind: result.diagram, model: result.model, labels: result.labels, warnings: result.warnings } as unknown as JsonValue
+        // A diagram from another family still parses into *something*. `parseFindings`
+        // says so, and the verdict is what stops that something from being trusted:
+        // `ok: true` only means the parser ran.
+        const findings = parseFindings(result)
+        return {
+          ok: true,
+          ran: true,
+          ...parseVerdict(result, findings),
+          schema: REPORT_SCHEMAS.umlParse,
+          action: 'parse',
+          notation: result.notation,
+          kind: result.diagram,
+          model: result.model,
+          labels: result.labels,
+          findings,
+          discardedConstructs: result.discardedConstructs,
+          discardedEdges: result.discardedEdges,
+          hashes: { hashSpec: DEFAULT_HASH_SPEC, modelHash: modelHash(result.model), diagram: createHash('sha256').update(args.diagram).digest('hex') },
+          warnings: result.warnings,
+        } as unknown as JsonValue
       }
       const report = reviewUml({
         model: args.model,
@@ -96,11 +117,20 @@ export const logicProbeUmlTool = defineTool({
       })
       return report as unknown as JsonValue
     } catch (error) {
-      return errorResult(error instanceof Error ? error.message : String(error), error instanceof UmlError) as unknown as JsonValue
+      const message = error instanceof Error ? error.message : String(error)
+      return errorResult(message, error instanceof UmlError ? error.code : undefined) as unknown as JsonValue
     }
   },
 })
 
-function errorResult(message: string, isUmlError = false): JsonValue {
-  return { ok: false, ...(isUmlError ? { errorCode: 'UML_INPUT' } : {}), error: message } as unknown as JsonValue
+/** The parse verdict counts parser notes as findings: an ignored line is information the model does not carry. */
+function parseVerdict(result: UmlParseResult, findings: UmlFinding[]): VerdictSummary {
+  const errors = findings.filter((finding) => finding.severity === 'error').length
+  const warnings = findings.filter((finding) => finding.severity === 'warning').length + result.warnings.length
+  const firstCode = findings.find((finding) => finding.severity === 'error')?.code ?? findings.find((finding) => finding.severity === 'warning')?.code
+  return verdictOf(errors, warnings, firstCode)
+}
+
+function errorResult(message: string, errorCode = 'UML_INPUT'): JsonValue {
+  return { ok: false, ran: false, ...refusalVerdict(message), errorCode, error: message } as unknown as JsonValue
 }

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,94 @@ 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[] {
+  if (parsed.discardedConstructs.length === 0) return []
+  const counts = new Map<string, number>()
+  for (const entry of parsed.discardedConstructs) 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 = parsed.discardedConstructs.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(parsed.discardedConstructs.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 + (parsed.discardedConstructs.length > 12 ? ' | … ' + String(parsed.discardedConstructs.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)) { 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 +946,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 +1001,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 +1035,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: 'skipped silently (a block is not a state meaning)' },
+      { 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 +1112,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 +1342,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 +1448,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 +1457,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 +1541,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 +1570,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 +1584,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 +1670,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 +1699,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,
   }