dsh-logicprobe 1.0.0 → 1.2.0

package/src/report-view.ts

@@ -0,0 +1,343 @@
+/**
+ * The report body: the text a model reads for a logicprobe result.
+ *
+ * Why this is not `JSON.stringify(value, null, 2)` any more: the structured report is a
+ * contract (schema, verdict, hashes, check ids, finding codes, evidence — a finding's
+ * identity is `check|code|<evidence + path>`, so `logicprobe_report_diff` and the test
+ * suite read the object, never this text). The object is unchanged and still reaches the
+ * client and the file path; this module only decides what the *model* pays for.
+ *
+ * Measured on a real 37,167-character report: 33.1% indentation, 21.7% repeated key names,
+ * 12.7% punctuation; 105 findings carried 47 distinct facts. So the work this module does —
+ * silencing passing checks, grouping repeated (state, event) facts, collapsing identical
+ * lines, dropping warning evidence — is work the model would otherwise have to redo by
+ * reading every finding. Everything a consumer does not need to act on is handled here.
+ *
+ * Determinism: the same report always renders to the same text (first-seen order, stable
+ * check order, no clock, no randomness), so two runs over the same input stay comparable.
+ *
+ * @module logicprobe/report-view
+ */
+import type { JsonValue } from './json-value.js'
+
+/** Rendering limits. Defaults are the shipped behaviour; tests pin them. */
+export interface ReportViewOptions {
+  /** Maximum finding lines per check. Error findings are never dropped, only warnings are capped. */
+  maxFindingsPerCheck?: number
+  /** Evidence is inlined for `error` findings only, truncated to this many characters. */
+  maxEvidenceChars?: number
+  /** Include passing checks' bodies (default false: a passing check carries no actionable finding). */
+  includePassing?: boolean
+  /**
+   * Print the whole structured report instead of the body. This is the escape hatch for a
+   * caller that must hand the report to another tool verbatim — `logicprobe_report_diff`
+   * matches on check + code + evidence, so a body cannot stand in for the object.
+   */
+  full?: boolean
+}
+
+const DEFAULTS = { maxFindingsPerCheck: 24, maxEvidenceChars: 160, includePassing: false, full: false } as const
+
+type Record_ = Record<string, unknown>
+
+const record = (value: unknown): Record_ | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record_) : undefined
+const array = (value: unknown): unknown[] => (Array.isArray(value) ? value : [])
+const text = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined)
+const count = (value: unknown): number | undefined => (typeof value === 'number' && Number.isFinite(value) ? value : undefined)
+
+/** One normalized finding. `evidence` is kept because a finding's identity depends on it. */
+export interface ViewFinding {
+  code: string
+  severity: string
+  message: string
+  evidence?: Record_
+  file?: string
+  line?: number
+  check?: string
+}
+
+/** Normalize one raw finding. Unknown fields are ignored; a missing message renders as the code. */
+export function toViewFinding(value: unknown, check?: string): ViewFinding {
+  const raw = record(value) ?? {}
+  const code = text(raw.code) ?? 'FINDING'
+  const file = text(raw.file)
+  const line = count(raw.line)
+  return {
+    code,
+    severity: text(raw.severity) ?? 'warning',
+    message: text(raw.message) ?? code,
+    ...(record(raw.evidence) === undefined ? {} : { evidence: record(raw.evidence) as Record_ }),
+    ...(file === undefined ? {} : { file }),
+    ...(line === undefined ? {} : { line }),
+    ...(check === undefined ? {} : { check }),
+  }
+}
+
+/**
+ * The fact a finding states, as a comparable key. The verify/datamodel families report the
+ * same (state, event) fact from more than one check, so the key ignores which check said it;
+ * anything else falls back to code + message.
+ */
+export function factKey(finding: ViewFinding): string {
+  const stateEvent = /^(\S+) silently ignores event (\S+)/.exec(finding.message)
+  if (stateEvent !== null) return `event-in-state|${stateEvent[1] ?? ''}|${stateEvent[2] ?? ''}`
+  const eventState = /^Event (\S+) in state (\S+) /.exec(finding.message)
+  if (eventState !== null) return `event-in-state|${eventState[2] ?? ''}|${eventState[1] ?? ''}`
+  return `message|${finding.code}|${finding.message}`
+}
+
+/** `[severity/CODE] message` plus, for errors, a compact evidence tail. */
+function findingLine(finding: ViewFinding, options: Required<ReportViewOptions>): string {
+  const where = finding.file === undefined ? '' : ` (${finding.file}${finding.line === undefined ? '' : ':' + String(finding.line)})`
+  const evidence =
+    finding.evidence === undefined || finding.severity !== 'error'
+      ? ''
+      : ' evidence=' + truncate(JSON.stringify(finding.evidence), options.maxEvidenceChars)
+  return `  [${finding.severity}/${finding.code}] ${finding.message}${where}${evidence}`
+}
+
+function truncate(value: string, limit: number): string {
+  return value.length <= limit ? value : value.slice(0, limit - 1) + '…'
+}
+
+/** Collapse identical lines into `line (xN)`, keeping first-seen order. */
+function collapse(lines: string[]): string[] {
+  const order: string[] = []
+  const seen = new Map<string, number>()
+  for (const line of lines) {
+    if (!seen.has(line)) order.push(line)
+    seen.set(line, (seen.get(line) ?? 0) + 1)
+  }
+  return order.map((line) => (seen.get(line) === 1 ? line : `${line} (x${String(seen.get(line))})`))
+}
+
+/**
+ * Body lines for one group of findings. Findings that restate a fact an earlier check already
+ * reported are dropped (only their count survives), because re-reading them is pure cost;
+ * `error` findings are never dropped.
+ */
+function findingLines(findings: ViewFinding[], options: Required<ReportViewOptions>, seenFacts: Set<string>): string[] {
+  const lines: string[] = []
+  let repeats = 0
+  const fresh: ViewFinding[] = []
+  const addedHere = new Set<string>()
+  for (const finding of findings) {
+    const key = factKey(finding)
+    // A fact another check already reported is dropped here (only its count survives), but a
+    // fact repeated inside this same group is not a cross-check repeat: it collapses below
+    // into one line with a multiplier, which keeps the count visible where it belongs.
+    if (finding.severity !== 'error' && seenFacts.has(key) && !addedHere.has(key)) {
+      repeats += 1
+      continue
+    }
+    addedHere.add(key)
+    seenFacts.add(key)
+    fresh.push(finding)
+  }
+  const stateGroups = new Map<string, { severity: string; code: string; events: string[] }>()
+  const singles: ViewFinding[] = []
+  for (const finding of fresh) {
+    const match = /^(\S+) silently ignores event (\S+)/.exec(finding.message) ?? /^Event (\S+) in state (\S+) /.exec(finding.message)
+    if (match === null) {
+      singles.push(finding)
+      continue
+    }
+    // `event in state` puts the state second; `state ignores event` puts it first.
+    const state = / silently ignores event /.test(finding.message) ? match[1] ?? '' : match[2] ?? ''
+    const event = / silently ignores event /.test(finding.message) ? match[2] ?? '' : match[1] ?? ''
+    const group = stateGroups.get(state) ?? { severity: finding.severity, code: finding.code, events: [] }
+    group.events.push(event)
+    stateGroups.set(state, group)
+  }
+  for (const [state, group] of stateGroups) {
+    lines.push(`  ${state} (${String(group.events.length)}) [${group.severity}/${group.code}]: ${group.events.join(', ')}`)
+  }
+  const rendered = collapse(singles.map((finding) => findingLine(finding, options)))
+  const budget = options.maxFindingsPerCheck
+  const kept: string[] = []
+  let dropped = 0
+  for (const line of [...lines, ...rendered]) {
+    if (kept.length < budget || line.includes('/error]')) kept.push(line)
+    else dropped += 1
+  }
+  if (dropped > 0) kept.push(`  +${String(dropped)} more warning line(s) — ask for this check by id to see them all`)
+  if (repeats > 0) kept.push(`  (${String(repeats)} finding(s) here repeat facts already reported above)`)
+  return kept
+}
+
+/** `ok`/`verdict` header fields, shared by every report family. */
+function headerLines(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const schema = text(report.schema) ?? 'logicprobe/report'
+  const verdict = text(report.verdict)
+  const ok = report.ok
+  const summary = record(report.summary) ?? {}
+  const lines: string[] = []
+  const bits = [
+    `${schema}`,
+    verdict === undefined ? `ok=${String(ok)}` : `verdict=${verdict}`,
+    text(report.verdictReason) ?? '',
+    ok === undefined || verdict === undefined ? '' : `ok=${String(ok)}`,
+  ].filter((bit) => bit !== '')
+  lines.push(bits.join('  '))
+  const hash = text(report.modelHash) ?? text(record(report.hashes)?.modelHash)
+  const counts = ['states', 'transitions', 'errors', 'warnings', 'checksRun']
+    .map((key) => (count(summary[key]) === undefined ? '' : `${key}=${String(count(summary[key]))}`))
+    .filter((bit) => bit !== '')
+  if (counts.length > 0 || hash !== undefined) lines[0] += '  ' + [...(hash === undefined ? [] : [`modelHash=${hash.slice(0, 12)}…`]), ...counts].join(' ')
+  if (report.ran === false) lines.push('note: the tool did not run (the engine refused the input) — the fields below describe the refusal.')
+  const coverage = record(report.narrativeCoverage)
+  if (coverage !== undefined) {
+    const parts = Object.entries(coverage)
+      .filter(([, value]) => count(value) !== undefined)
+      .map(([key, value]) => `${key} ${String(count(value))}`)
+    if (parts.length > 0) lines.push(`NARRATIVE  ${parts.join(' / ')} documented`)
+  }
+  void options
+  return lines
+}
+
+/** Trailing lines: notes about what was not checked, then the next steps. */
+function footerLines(report: Record_): string[] {
+  const lines: string[] = []
+  const notes = array(report.coverageNotes).map(String).filter((note) => note !== '')
+  if (notes.length > 0) lines.push(`COVERAGE  ${notes.join(' ')}`)
+  const steps = array(report.nextSteps).map(String).filter((step) => step !== '')
+  for (const step of steps) lines.push(`NEXT  ${step}`)
+  const comparison = record(report.comparison)
+  if (comparison !== undefined) {
+    const parts = Object.entries(comparison)
+      .filter(([, value]) => count(value) !== undefined || typeof value === 'string')
+      .map(([key, value]) => `${key}=${String(value)}`)
+    if (parts.length > 0) lines.push(`COMPARISON  ${parts.join(' ')}`)
+  }
+  return lines
+}
+
+/** A `checks[]` report (verify, compose, datamodel): silence pass, expand the rest. */
+function renderChecksReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const checks = array(report.checks).map((value) => record(value) ?? {})
+  const byStatus = (status: string): string[] =>
+    checks.filter((check) => text(check.status) === status).map((check) => text(check.id) ?? '?')
+  const inventory = [
+    ['pass', byStatus('pass')],
+    ['fail', byStatus('fail')],
+    ['skip', byStatus('skip')],
+  ]
+    .filter(([, ids]) => (ids as string[]).length > 0)
+    .map(([status, ids]) => `${String(status)} ${(ids as string[]).join(' ')}`)
+    .join(' | ')
+  const lines = [...headerLines(report, options), `CHECKS  ${inventory}`]
+  const seenFacts = new Set<string>()
+  for (const check of checks) {
+    const status = text(check.status) ?? 'skip'
+    const findings = array(check.findings).map((finding) => toViewFinding(finding, text(check.id)))
+    if (status === 'pass' && !options.includePassing) continue
+    const body = findingLines(findings, options, seenFacts)
+    if (status !== 'fail' && body.length === 0) continue
+    lines.push('')
+    lines.push(
+      `${status.toUpperCase()} ${text(check.id) ?? '?'} ${text(check.name) ?? ''} — ${text(check.detail) ?? ''} (${String(findings.length)} finding(s))`.replace(/ +— +$/, ''),
+    )
+    lines.push(...body)
+  }
+  return [...lines, ...wrapFooter(report)]
+}
+
+/** A flat `findings[]` report (uml review, structure, granularity, concurrency). */
+function renderFindingsReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const findings = array(report.findings).map((finding) => toViewFinding(finding))
+  const errors = findings.filter((finding) => finding.severity === 'error').length
+  const warnings = findings.length - errors
+  const byCode = new Map<string, number>()
+  for (const finding of findings) byCode.set(finding.code, (byCode.get(finding.code) ?? 0) + 1)
+  const lines = [
+    ...headerLines(report, options),
+    `FINDINGS  ${String(findings.length)} total (${String(errors)} error, ${String(warnings)} warning): ${[...byCode].map(([code, n]) => `${code} x${String(n)}`).join(' | ')}`,
+  ]
+  const body = findingLines(findings, options, new Set<string>())
+  if (body.length > 0) lines.push('', ...body)
+  return [...lines, ...wrapFooter(report)]
+}
+
+/** A baseline diff report: what a change added, removed or changed. */
+function renderDeltaReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const lines = headerLines(report, options)
+  const delta = record(report.delta) ?? report
+  const section = (key: string): ViewFinding[] => array(delta[key]).map((finding) => toViewFinding(finding))
+  for (const key of ['added', 'removed', 'changed']) {
+    const findings = section(key)
+    if (findings.length === 0) continue
+    lines.push('', `${key.toUpperCase()} (${String(findings.length)})`)
+    lines.push(...findingLines(findings, options, new Set<string>()))
+  }
+  const current = text(report.currentVerdict) ?? text(record(report.current)?.verdict)
+  if (current !== undefined) lines.push(`CURRENT  verdict=${current}`)
+  return [...lines, ...wrapFooter(report)]
+}
+
+/** A payload result (a rendered diagram, an exported file): print the payload, not JSON of it. */
+function renderPayloadReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const lines = headerLines(report, options)
+  const primary = text(report.diagram) ?? text(report.primary)
+  if (primary !== undefined) lines.push('', primary.trimEnd())
+  const extras = record(report.extras)
+  for (const [name, content] of Object.entries(extras ?? {})) {
+    const body = text(content)
+    if (body !== undefined) lines.push('', `--- ${name} ---`, body.trimEnd())
+  }
+  const warnings = array(report.warnings).map(String).filter((warning) => warning !== '')
+  for (const warning of warnings) lines.push(`WARNING  ${warning}`)
+  return [...lines, ...wrapFooter(report)]
+}
+
+function wrapFooter(report: Record_): string[] {
+  const footer = footerLines(report)
+  return footer.length === 0 ? [] : ['', ...footer]
+}
+
+/**
+ * A refusal, or a shape this module does not recognize: state the reason first, then the
+ * remaining fields compactly so nothing is lost, without paying for indentation.
+ */
+function renderFallbackReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const lines = headerLines(report, options)
+  const message = text(report.error)
+  if (message !== undefined) {
+    const code = text(report.errorCode)
+    lines.push(`ERROR  ${message}${code === undefined ? '' : ` [${code}]`}`)
+  }
+  const rest: Record_ = { ...report }
+  delete rest.error
+  delete rest.errorCode
+  lines.push('', JSON.stringify(rest))
+  return [...lines, ...wrapFooter(report)]
+}
+
+/**
+ * Render any logicprobe result as the text a model reads.
+ *
+ * Order of recognition: a `checks[]` report, a flat `findings[]` report, a baseline delta,
+ * a payload result (`diagram`/`primary`), and finally compact JSON so an unrecognized shape
+ * is still readable rather than silently empty.
+ */
+export function renderReportText(value: unknown, options: ReportViewOptions = {}): string {
+  const resolved: Required<ReportViewOptions> = { ...DEFAULTS, ...options }
+  if (resolved.full) return JSON.stringify(value as JsonValue, null, 2)
+  const report = record(value)
+  if (report === undefined) return JSON.stringify(value as JsonValue) ?? String(value)
+  const hasChecks = array(report.checks).some((check) => record(check) !== undefined)
+  const hasFindings = array(report.findings).length > 0
+  const isDelta = array(report.added).length + array(report.removed).length + array(report.changed).length > 0
+  const isPayload = typeof report.diagram === 'string' || typeof report.primary === 'string'
+  const lines = hasChecks
+    ? renderChecksReport(report, resolved)
+    : isDelta
+      ? renderDeltaReport(report, resolved)
+      : hasFindings
+        ? renderFindingsReport(report, resolved)
+        : isPayload
+          ? renderPayloadReport(report, resolved)
+          : renderFallbackReport(report, resolved)
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()
+}

package/src/structure-tool.ts

@@ -3,6 +3,7 @@ import type { JsonValue } from './json-value.js'
 import { REPORT_SCHEMAS } from './engine.js'
 import { reviewStructure } from './structure.js'
 import { reviewGranularity, type GranularityDiagram } from './granularity.js'
+import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_STRUCTURE_TOOL_NAME = 'logicprobe_structure_verify'
 
@@ -36,14 +37,19 @@ export const logicProbeStructureTool = defineTool({
       type: 'json',
       description: 'Optional dependency matrix: {rules: [{id, source, allow?, deny?, require?}], layers: [{name, members}], default: "allow"|"deny"}. Every edge is judged against it and the matched rule ids are reported.',
     },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the readable body; full prints the structured report, which logicprobe_report_diff needs.',
+    },
   },
   output: {
     schema: {
       type: 'json',
       description: 'Structure review report: graph (nodes/edges), findings UML020-UML026, per-edge matrix verdicts, summary and next steps.',
     },
-    render(_args, value) {
-      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    render(args, value) {
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
   },
   timeoutMs: 10_000,

package/src/tool.ts

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { runVerification } from './engine.js'
+import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_VERIFY_TOOL_NAME = 'logicprobe_verify'
 
@@ -39,14 +40,19 @@ export const logicProbeVerifyTool = defineTool({
       type: 'json',
       description: 'Optional object mapping BEFORE state ids to AFTER state ids. Omit for identity mapping (same state names).',
     },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the readable body; full prints the structured report, which logicprobe_report_diff needs.',
+    },
   },
   output: {
     schema: {
       type: 'json',
       description: 'logicprobe verification report with summary and per-check findings.',
     },
-    render(_args, value) {
-      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    render(args, value) {
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
   },
   timeoutMs: 10_000,

package/src/uml-tool.ts

@@ -2,7 +2,8 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { createHash } from 'node:crypto'
 import type { JsonValue } from './json-value.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'
+import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, UmlError, type UmlDiagram, type UmlFinding, type UmlNotation, type UmlParseResult } from './uml.js'
+import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
 
@@ -21,13 +22,13 @@ 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 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.',
+    '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. action="explain-labels" prints the label and comment conventions the parser accepts, without needing a diagram. 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',
       required: true,
-      enum: ['render', 'parse', 'review'],
-      description: 'render = model → UML source; parse = UML source → model; review = audit the modelling (and its fidelity to the model).',
+      enum: ['render', 'parse', 'review', 'explain-labels'],
+      description: 'render = model → UML source; parse = UML source → model; review = audit the modelling (and its fidelity to the model); explain-labels = print the label and comment conventions this parser accepts.',
     },
     model: {
       type: 'json',
@@ -55,23 +56,21 @@ export const logicProbeUmlTool = defineTool({
       type: 'integer',
       description: 'Cap on the sequence trace length when rendering kind=sequence. Default 60.',
     },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the diagram or report body; full prints the structured result as JSON.',
+    },
   },
   output: {
     schema: {
       type: 'json',
       description: 'Render result (diagram source), parse result (LogicModelV1 + labels), or the modelling review report with findings, round-trip diff and next steps.',
     },
-    render(_args, value) {
-      const record = value as unknown as Record<string, unknown>
-      // A rendered diagram is source text: print it verbatim so it can be copied
-      // into a file, then the structured result (warnings, notation, kind).
-      if (typeof record.diagram === 'string') {
-        return [
-          { type: 'text' as const, text: record.diagram },
-          { type: 'text' as const, text: JSON.stringify(value, null, 2) },
-        ]
-      }
-      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    render(args, value) {
+      // A rendered diagram is source text: the report body prints it verbatim, once.
+      // Echoing the whole result as JSON printed the same diagram a second time, escaped.
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
   },
   timeoutMs: 10_000,
@@ -107,6 +106,19 @@ export const logicProbeUmlTool = defineTool({
           warnings: result.warnings,
         } as unknown as JsonValue
       }
+      // R9: the label contract was documented in the library and in `explainLabels()`, but no
+      // tool exposed it, so it was reachable only by reading the source or the docs.
+      if (args.action === 'explain-labels') {
+        const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation
+        return {
+          ok: true,
+          ran: true,
+          ...verdictOf(0, 0),
+          schema: REPORT_SCHEMAS.umlExplainLabels,
+          action: 'explain-labels',
+          ...explainLabels(notation),
+        } as unknown as JsonValue
+      }
       const report = reviewUml({
         model: args.model,
         diagram: args.diagram,

package/src/uml.ts

@@ -870,19 +870,23 @@ function declaredIdentifier(text: string): string | undefined {
  * 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 []
+  // 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 parsed.discardedConstructs) counts.set(entry.construct, (counts.get(entry.construct) ?? 0) + 1)
+  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 = parsed.discardedConstructs.slice(0, 12).map((entry) => 'line ' + String(entry.line) + ': ' + entry.text).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(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' : ''),
+    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' : ''),
   }]
 }
 
@@ -916,7 +920,16 @@ function parseStateDiagram(text: string, notation: UmlNotation): UmlParseResult
     // 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 }
+    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])
@@ -1084,7 +1097,7 @@ export function explainLabels(notation: UmlNotation = 'mermaid'): LabelExplanati
     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: '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' },
     ],