dsh-model-everything 0.2.0 → 0.4.0

package/src/structure.ts

@@ -107,6 +107,10 @@ export interface StructureSummary {
   errors: number
   warnings: number
   rules: number
+  /** The most depended-on nodes, by incoming edges. What a reader asks first and counts worst. */
+  hubs: { id: string; dependents: number }[]
+  /** Modules nothing depends on (no outgoing edges), capped for the report. */
+  leaves: string[]
 }
 
 export interface StructureReport {
@@ -503,6 +507,10 @@ export function shortestCycle(nodes: string[], edges: StructureEdge[]): string[]
 export interface StructureReviewOptions {
   /** Diagram text to review. */
   diagram: string
+  /** A graph built from source, instead of parsed from a diagram. `diagram` is then ignored. */
+  graph?: StructureGraph
+  /** How the graph was produced, when it came from a scan rather than a drawing. */
+  scan?: { files: number; unresolved: number; packages: number; languages: string[] }
   notation?: 'auto' | StructureNotation
   /** Dependency matrix: allowed/denied edges, layers, required edges. */
   matrix?: unknown
@@ -531,8 +539,9 @@ function requireDiagramText(value: unknown): string {
 export function reviewStructure(options: StructureReviewOptions): StructureReport {
   // Not `if (options.diagram !== undefined)`: a missing `diagram` reached the parser as `undefined`
   // and threw a read of `split` on it - the same defect, one guard narrower.
-  requireDiagramText(options.diagram)
-  const graph = parseStructure(options.diagram, options.notation ?? 'auto')
+  // A graph built from source arrives already parsed; a caller that passes one has no diagram text to
+  // require, so the text guard belongs to the other branch.
+  const graph = options.graph ?? parseStructure(requireDiagramText(options.diagram), options.notation ?? 'auto')
   const warnings = [...graph.warnings]
   const findings: Finding[] = []
   const nodes = graph.nodes
@@ -730,6 +739,26 @@ export function reviewStructure(options: StructureReviewOptions): StructureRepor
     })
   }
 
+  // Degree is what a reader asks first and counts worst: which module everything depends on, and which
+  // depends on nothing. Counting it here means the answer is one line in the report rather than a scan of
+  // the graph by hand, which is where a correct graph still produced a wrong answer.
+  const inDegree = new Map<string, number>()
+  const outDegree = new Map<string, number>()
+  for (const edge of graph.edges) {
+    inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1)
+    outDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1)
+  }
+  const hubs = [...inDegree.entries()]
+    .filter(([, count]) => count > 0)
+    .sort((a, b) => (b[1] === a[1] ? a[0].localeCompare(b[0]) : b[1] - a[1]))
+    .slice(0, 5)
+    .map(([id, dependents]) => ({ id, dependents }))
+  const leaves = nodes
+    .filter((node) => !node.container && (outDegree.get(node.id) ?? 0) === 0)
+    .map((node) => node.id)
+    .sort()
+    .slice(0, 10)
+
   const errors = findings.filter((finding) => finding.severity === 'error').length
   const warningCount = findings.filter((finding) => finding.severity === 'warning').length
   const summary: StructureSummary = {
@@ -745,6 +774,8 @@ export function reviewStructure(options: StructureReviewOptions): StructureRepor
     errors,
     warnings: warningCount,
     rules: rules.length,
+    hubs,
+    leaves,
   }
 
   const nextSteps: string[] = []
@@ -761,10 +792,13 @@ export function reviewStructure(options: StructureReviewOptions): StructureRepor
     notation: graph.notation,
     graph,
     ...(options.matrix === undefined ? {} : { edgeVerdicts }),
+    ...(options.scan === undefined ? {} : { scan: options.scan }),
     findings,
     summary,
     hashes: {
-      diagram: createHash('sha256').update(options.diagram).digest('hex'),
+      // A graph built from source has no diagram text to hash; hashing the text would hash the empty
+      // string, and every scan would then carry the same input hash.
+      diagram: createHash('sha256').update(options.graph === undefined ? options.diagram : canonicalJson({ nodes: options.graph.nodes.map((node) => node.id), edges: options.graph.edges.map((edge) => ({ from: edge.from, to: edge.to })) })).digest('hex'),
       ...(options.matrix === undefined ? {} : { matrix: createHash('sha256').update(canonicalJson(options.matrix)).digest('hex') }),
     },
     warnings,

package/src/tool.ts

@@ -2,6 +2,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'
+import { reportCallView, reportCard, reportResultView } from './presentation.js'
 import { OptionShapeError, optionRefusal, requireObjectOption } from './option-shape.js'
 import { oneOf } from './model-file.js'
 
@@ -63,7 +64,13 @@ export const modelVerifyTool = defineTool({
     render(args, value) {
       return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full', check: args.check }) }]
     },
+    // The card a UI shows, separated from the text the model reads.
+    presentationMeta(args, value) {
+      return reportCard(value, MODEL_VERIFY_TOOL_NAME) as unknown as JsonValue
+    },
   },
+  presentCall: reportCallView(MODEL_VERIFY_TOOL_NAME),
+  presentResult: reportResultView(MODEL_VERIFY_TOOL_NAME),
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {

package/src/uml-tool.ts

@@ -1,230 +1,245 @@
-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, valueHash, refusalVerdict, verdictOf, verdictOfFindings, type VerdictSummary } from './engine.js'
-import {
-  renderUml, parseUml, parseFindings, reviewUml, explainLabels, checkUmlIntent, UmlError, UML_DIAGRAMS,
-  type UmlDiagram, type UmlFinding, type UmlIntent, type UmlNotation, type UmlParseResult,
-} from './uml.js'
-import { renderReportText } from './report-view.js'
-
-/**
- * The UML front end as four tools, one per job.
- *
- * The split follows the jobs a caller actually has: draw a diagram from a model, read a
- * diagram into a model, audit a diagram or a model, and read the label contract the parser
- * accepts. Bundling them behind one action parameter made every caller read four jobs to
- * find one, and made the tool description a summary of all four.
- *
- * The family list is not written here. It is read from the engine (`UML_DIAGRAMS`), so adding
- * a UML diagram type is a change in the engine and its family module and touches no tool:
- * the schema, the enum and every description follow from the table.
- */
-
-/** Every family the front end knows, in the engine's order. A new family is one edit there. */
-const FAMILIES = [...UML_DIAGRAMS]
-
-export const UML_RENDER_TOOL_NAME = 'uml_render'
-export const UML_PARSE_TOOL_NAME = 'uml_parse'
-export const UML_REVIEW_TOOL_NAME = 'uml_review'
-export const UML_LABELS_TOOL_NAME = 'uml_explain_labels'
-
-const reportViewParameter = {
-  type: 'string',
-  enum: ['digest', 'full'],
-  description: 'digest (default) prints the diagram or the report body; full prints the structured result as JSON.',
-} as const
-
-const notationParameter = {
-  type: 'string',
-  enum: ['auto', 'mermaid', 'plantuml'],
-  description: 'Diagram language. Default auto: detected from the text where there is text, mermaid where a model is drawn.',
-} as const
-
-const kindParameter = {
-  type: 'string',
-  enum: FAMILIES,
-  description: 'UML diagram family. Default state. A family the chosen notation cannot express is refused with the reason, never approximated silently.',
-} as const
-
-const intentParameter = {
-  type: 'string',
-  enum: ['present', 'verify', 'fidelity'],
-  description: 'What the artifact is for, declared up front: present = a human will read it; verify = it must be readable as a model by the verification engine; fidelity = the render-and-reparse proof is the point. A view that cannot serve the declared intent is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes.',
-} as const
-
-const reportOutput = {
-  schema: { type: 'json', description: 'The result: diagram source, a family model, or a modelling review report with findings, round-trip fidelity and next steps.' },
-  render(args: Record<string, unknown>, value: unknown) {
-    // A rendered diagram is source text: the body prints it verbatim, once.
-    return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
-  },
-} as const
-
-/** Draw a model as diagram source. */
-export const umlRenderTool = defineTool({
-  name: UML_RENDER_TOOL_NAME,
-  description:
-    'Turn a model into UML diagram source a human can read, in the notation that can draw that family. It does not judge the model: `uml_review` audits the modelling, `uml_parse` reads a diagram someone else drew. Takes a LogicModelV1 state machine, or the model of another family (use case, class, object, package, component, deployment), and returns Mermaid or PlantUML text that draws it. Use it to turn a verified machine into a diagram a reader can check, or to produce a diagram someone can edit. It never invents structure the model does not have: a construct the notation cannot carry becomes a warning. PlantUML activity is refused instead of approximated, and a family the notation has no view for is refused with the reason. Declare `intent` to have a view that cannot serve the declared purpose refused before any work.',
-  parameters: {
-    model: { type: 'json', required: true, description: 'The model to draw: a LogicModelV1 (state machine) or a family model such as a use case or structure model.' },
-    notation: notationParameter,
-    kind: kindParameter,
-    maxSteps: { type: 'integer', description: 'Cap on the sequence trace length when rendering kind=sequence. Default 60.' },
-    intent: intentParameter,
-    reportView: reportViewParameter,
-  },
-  output: reportOutput,
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    try {
-      if (args.model === undefined) return errorResult('uml_render needs a model: a LogicModelV1 or a family model object')
-      const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation
-      const result = renderUml(args.model, notation, (args.kind ?? 'state') as UmlDiagram, args.maxSteps as number | undefined, args.intent as UmlIntent | undefined)
-      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
-    } catch (error) {
-      return refusal(error)
-    }
-  },
-})
-
-/** Read diagram text into the model of the family it declares. */
-export const umlParseTool = defineTool({
-  name: UML_PARSE_TOOL_NAME,
-  description:
-    'Read UML diagram text into the model of the family it declares, so a hand-drawn diagram can be checked or diffed. It only reads what the notation states: `uml_review` judges the modelling, and a family the notation cannot carry is refused by name. Mermaid and PlantUML are both accepted, and the family is detected from the text: a state machine or activity diagram becomes a LogicModelV1 the verification engine can run, while a use case, class, object, package, component or deployment diagram becomes that family model. Read the verdict, not ok: a diagram whose family has no module in this build is refused with errorCode UML_NOT_A_STATE_DIAGRAM, and the refusal names the family it found. A sequence diagram is refused as well, because a trace cannot reconstruct a machine, and so is text that is not a UML diagram at all.',
-  parameters: {
-    diagram: { type: 'string', required: true, description: 'The UML source text to read.' },
-    notation: notationParameter,
-    intent: intentParameter,
-    reportView: reportViewParameter,
-  },
-  output: reportOutput,
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    try {
-      if (args.diagram === undefined) return errorResult('uml_parse needs diagram text (Mermaid or PlantUML)')
-      checkUmlIntent(args.intent as UmlIntent | undefined, 'parse')
-      const result = parseUml(args.diagram, (args.notation ?? 'auto') as UmlNotation | 'auto')
-      // The parser notes are the parse verdict: an ignored line is information the model does not carry, so
-      // ok: true only ever means the parser ran. They stay in `warnings` - the channel the schema reference names and
-      // the render side uses - and the body prints them, which is where the old contradiction lived: the verdict
-      // counted them while the roster said `FINDINGS none`.
-      const findings = parseFindings(result)
-      return {
-        ok: true,
-        ran: true,
-        ...parseVerdict(result, findings),
-        schema: REPORT_SCHEMAS.umlParse,
-        action: 'parse',
-        notation: result.notation,
-        kind: result.diagram,
-        family: result.family,
-        model: result.model,
-        labels: result.labels,
-        findings,
-        discardedConstructs: result.discardedConstructs,
-        discardedEdges: result.discardedEdges,
-        hashes: { hashSpec: DEFAULT_HASH_SPEC, modelHash: valueHash(result.model), diagram: createHash('sha256').update(args.diagram).digest('hex') },
-        warnings: result.warnings,
-      } as unknown as JsonValue
-    } catch (error) {
-      return refusal(error)
-    }
-  },
-})
-
-/** Audit the modelling: the diagram, the model, or the two against each other. */
-export const umlReviewTool = defineTool({
-  name: UML_REVIEW_TOOL_NAME,
-  description:
-    'Audit UML modelling, and report what a reader would get wrong. Give it a model (is this machine well modelled?), a diagram (what does this diagram actually say?), or both (does the diagram carry the model it is presented with?). It reports structural defects such as unreachable states, dead ends, ambiguous or non-exhaustive branches, isolated nodes and cycles, plus documentation gaps and the fidelity check that re-renders the model and reads it back. Read the verdict, not ok. A family diagram gets its own family checks: use case defects, or the dependency-graph checks for a structure diagram. This audits the modelling; behaviour needs model_verify.',
-  parameters: {
-    model: { type: 'json', description: 'The model to review: a LogicModelV1 or a family model. Provide it, the diagram, or both.' },
-    diagram: { type: 'string', description: 'UML source text to review. Provide it, the model, or both.' },
-    notation: notationParameter,
-    kind: kindParameter,
-    roundTrip: { type: 'boolean', description: 'Render and re-read the model to prove the diagram carries it. Default true.' },
-    maxSteps: { type: 'integer', description: 'Cap on the sequence trace used for the fidelity check.' },
-    intent: intentParameter,
-    reportView: reportViewParameter,
-  },
-  output: reportOutput,
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    try {
-      if (args.model === undefined && args.diagram === undefined) return errorResult('uml_review needs a model, diagram text, or both')
-      const report = reviewUml({
-        model: args.model,
-        diagram: args.diagram,
-        notation: (args.notation ?? 'auto') as UmlNotation | 'auto',
-        diagramKind: (args.kind ?? 'state') as UmlDiagram,
-        roundTrip: args.roundTrip as boolean | undefined,
-        maxSteps: args.maxSteps as number | undefined,
-        intent: args.intent as UmlIntent | undefined,
-      })
-      return report as unknown as JsonValue
-    } catch (error) {
-      return refusal(error)
-    }
-  },
-})
-
-/** Print the label and comment contract the parser accepts. */
-export const umlExplainLabelsTool = defineTool({
-  name: UML_LABELS_TOOL_NAME,
-  description:
-    'Print the label and comment conventions the UML parser accepts, for one notation: the accepted label spellings, the form the renderer writes, the directives that pin what the notation cannot spell, and which lines are ignored. No diagram is needed. Use it when a hand-written diagram reports label drift or ignored lines and the reason is not obvious from the source. It reads no diagram and judges no modelling: `uml_parse` reads a diagram, and `uml_review` audits one.',
-  parameters: {
-    notation: notationParameter,
-    reportView: reportViewParameter,
-  },
-  output: reportOutput,
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    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
-  },
-})
-
-/** The parse verdict counts parser notes as warnings: 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)
-}
-
-/** A front-end refusal travels as a failed result, with the code that says why. */
-function refusal(error: unknown): JsonValue {
-  const message = error instanceof Error ? error.message : String(error)
-  return errorResult(message, error instanceof UmlError ? error.code : undefined)
-}
-
-function errorResult(message: string, errorCode = 'UML_INPUT'): JsonValue {
-  // Carries the refusal schema. Every other family's refusal carries one, and a reader who decides "what am I
-  // holding" from `schema` got nothing from this one - it was the only refusal shaped differently.
-  return { ok: false, ran: false, ...refusalVerdict(message), schema: REPORT_SCHEMAS.umlRefusal, errorCode, error: message } as unknown as JsonValue
-}
+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, valueHash, refusalVerdict, verdictOf, verdictOfFindings, type VerdictSummary } from './engine.js'
+import {
+  renderUml, parseUml, parseFindings, reviewUml, explainLabels, checkUmlIntent, UmlError, UML_DIAGRAMS,
+  type UmlDiagram, type UmlFinding, type UmlIntent, type UmlNotation, type UmlParseResult,
+} from './uml.js'
+import { renderReportText } from './report-view.js'
+import { cardWithSource, reportCallView, reportCard, reportResultView } from './presentation.js'
+
+/**
+ * The UML front end as four tools, one per job.
+ *
+ * The split follows the jobs a caller actually has: draw a diagram from a model, read a
+ * diagram into a model, audit a diagram or a model, and read the label contract the parser
+ * accepts. Bundling them behind one action parameter made every caller read four jobs to
+ * find one, and made the tool description a summary of all four.
+ *
+ * The family list is not written here. It is read from the engine (`UML_DIAGRAMS`), so adding
+ * a UML diagram type is a change in the engine and its family module and touches no tool:
+ * the schema, the enum and every description follow from the table.
+ */
+
+/** Every family the front end knows, in the engine's order. A new family is one edit there. */
+const FAMILIES = [...UML_DIAGRAMS]
+
+export const UML_RENDER_TOOL_NAME = 'uml_render'
+export const UML_PARSE_TOOL_NAME = 'uml_parse'
+export const UML_REVIEW_TOOL_NAME = 'uml_review'
+export const UML_LABELS_TOOL_NAME = 'uml_explain_labels'
+
+const reportViewParameter = {
+  type: 'string',
+  enum: ['digest', 'full'],
+  description: 'digest (default) prints the diagram or the report body; full prints the structured result as JSON.',
+} as const
+
+const notationParameter = {
+  type: 'string',
+  enum: ['auto', 'mermaid', 'plantuml'],
+  description: 'Diagram language. Default auto: detected from the text where there is text, mermaid where a model is drawn.',
+} as const
+
+const kindParameter = {
+  type: 'string',
+  enum: FAMILIES,
+  description: 'UML diagram family. Default state. A family the chosen notation cannot express is refused with the reason, never approximated silently.',
+} as const
+
+const intentParameter = {
+  type: 'string',
+  enum: ['present', 'verify', 'fidelity'],
+  description: 'What the artifact is for, declared up front: present = a human will read it; verify = it must be readable as a model by the verification engine; fidelity = the render-and-reparse proof is the point. A view that cannot serve the declared intent is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes.',
+} as const
+
+const reportOutput = (family: string) => ({
+  schema: { type: 'json' as const, description: 'The result: diagram source, a family model, or a modelling review report with findings, round-trip fidelity and next steps.' },
+  render(args: Record<string, unknown>, value: unknown) {
+    // A rendered diagram is source text: the body prints it verbatim, once.
+    return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
+  },
+  // The card a UI shows, separated from the text the model reads. The family is the tool's own name, so
+  // one shared output does not have to guess which tool is calling it.
+  presentationMeta(_args: unknown, value: unknown) {
+    const report = value as Record<string, unknown>
+    return cardWithSource(value, family, typeof report.diagram === 'string' ? report.diagram : undefined, 'diagram source') as unknown as JsonValue
+  },
+})
+
+/** Draw a model as diagram source. */
+export const umlRenderTool = defineTool({
+  name: UML_RENDER_TOOL_NAME,
+  description:
+    'Turn a model into UML diagram source a human can read, in the notation that can draw that family. It does not judge the model: `uml_review` audits the modelling, `uml_parse` reads a diagram someone else drew. Takes a LogicModelV1 state machine, or the model of another family (use case, class, object, package, component, deployment), and returns Mermaid or PlantUML text that draws it. Use it to turn a verified machine into a diagram a reader can check, or to produce a diagram someone can edit. It never invents structure the model does not have: a construct the notation cannot carry becomes a warning. PlantUML activity is refused instead of approximated, and a family the notation has no view for is refused with the reason. Declare `intent` to have a view that cannot serve the declared purpose refused before any work.',
+  parameters: {
+    model: { type: 'json', required: true, description: 'The model to draw: a LogicModelV1 (state machine) or a family model such as a use case or structure model.' },
+    notation: notationParameter,
+    kind: kindParameter,
+    maxSteps: { type: 'integer', description: 'Cap on the sequence trace length when rendering kind=sequence. Default 60.' },
+    intent: intentParameter,
+    reportView: reportViewParameter,
+  },
+  output: reportOutput(UML_RENDER_TOOL_NAME),
+  presentCall: reportCallView(UML_RENDER_TOOL_NAME),
+  presentResult: reportResultView(UML_RENDER_TOOL_NAME),
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      if (args.model === undefined) return errorResult('uml_render needs a model: a LogicModelV1 or a family model object')
+      const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation
+      const result = renderUml(args.model, notation, (args.kind ?? 'state') as UmlDiagram, args.maxSteps as number | undefined, args.intent as UmlIntent | undefined)
+      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
+    } catch (error) {
+      return refusal(error)
+    }
+  },
+})
+
+/** Read diagram text into the model of the family it declares. */
+export const umlParseTool = defineTool({
+  name: UML_PARSE_TOOL_NAME,
+  description:
+    'Read UML diagram text into the model of the family it declares, so a hand-drawn diagram can be checked or diffed. It only reads what the notation states: `uml_review` judges the modelling, and a family the notation cannot carry is refused by name. Mermaid and PlantUML are both accepted, and the family is detected from the text: a state machine or activity diagram becomes a LogicModelV1 the verification engine can run, while a use case, class, object, package, component or deployment diagram becomes that family model. Read the verdict, not ok: a diagram whose family has no module in this build is refused with errorCode UML_NOT_A_STATE_DIAGRAM, and the refusal names the family it found. A sequence diagram is refused as well, because a trace cannot reconstruct a machine, and so is text that is not a UML diagram at all.',
+  parameters: {
+    diagram: { type: 'string', required: true, description: 'The UML source text to read.' },
+    notation: notationParameter,
+    intent: intentParameter,
+    reportView: reportViewParameter,
+  },
+  output: reportOutput(UML_PARSE_TOOL_NAME),
+  presentCall: reportCallView(UML_PARSE_TOOL_NAME),
+  presentResult: reportResultView(UML_PARSE_TOOL_NAME),
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      if (args.diagram === undefined) return errorResult('uml_parse needs diagram text (Mermaid or PlantUML)')
+      checkUmlIntent(args.intent as UmlIntent | undefined, 'parse')
+      const result = parseUml(args.diagram, (args.notation ?? 'auto') as UmlNotation | 'auto')
+      // The parser notes are the parse verdict: an ignored line is information the model does not carry, so
+      // ok: true only ever means the parser ran. They stay in `warnings` - the channel the schema reference names and
+      // the render side uses - and the body prints them, which is where the old contradiction lived: the verdict
+      // counted them while the roster said `FINDINGS none`.
+      const findings = parseFindings(result)
+      return {
+        ok: true,
+        ran: true,
+        ...parseVerdict(result, findings),
+        schema: REPORT_SCHEMAS.umlParse,
+        action: 'parse',
+        notation: result.notation,
+        kind: result.diagram,
+        family: result.family,
+        model: result.model,
+        labels: result.labels,
+        findings,
+        discardedConstructs: result.discardedConstructs,
+        discardedEdges: result.discardedEdges,
+        hashes: { hashSpec: DEFAULT_HASH_SPEC, modelHash: valueHash(result.model), diagram: createHash('sha256').update(args.diagram).digest('hex') },
+        warnings: result.warnings,
+      } as unknown as JsonValue
+    } catch (error) {
+      return refusal(error)
+    }
+  },
+})
+
+/** Audit the modelling: the diagram, the model, or the two against each other. */
+export const umlReviewTool = defineTool({
+  name: UML_REVIEW_TOOL_NAME,
+  description:
+    'Audit UML modelling, and report what a reader would get wrong. Give it a model (is this machine well modelled?), a diagram (what does this diagram actually say?), or both (does the diagram carry the model it is presented with?). It reports structural defects such as unreachable states, dead ends, ambiguous or non-exhaustive branches, isolated nodes and cycles, plus documentation gaps and the fidelity check that re-renders the model and reads it back. Read the verdict, not ok. A family diagram gets its own family checks: use case defects, or the dependency-graph checks for a structure diagram. This audits the modelling; behaviour needs model_verify.',
+  parameters: {
+    model: { type: 'json', description: 'The model to review: a LogicModelV1 or a family model. Provide it, the diagram, or both.' },
+    diagram: { type: 'string', description: 'UML source text to review. Provide it, the model, or both.' },
+    notation: notationParameter,
+    kind: kindParameter,
+    roundTrip: { type: 'boolean', description: 'Render and re-read the model to prove the diagram carries it. Default true.' },
+    maxSteps: { type: 'integer', description: 'Cap on the sequence trace used for the fidelity check.' },
+    intent: intentParameter,
+    reportView: reportViewParameter,
+  },
+  output: reportOutput(UML_REVIEW_TOOL_NAME),
+  presentCall: reportCallView(UML_REVIEW_TOOL_NAME),
+  presentResult: reportResultView(UML_REVIEW_TOOL_NAME),
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      if (args.model === undefined && args.diagram === undefined) return errorResult('uml_review needs a model, diagram text, or both')
+      const report = reviewUml({
+        model: args.model,
+        diagram: args.diagram,
+        notation: (args.notation ?? 'auto') as UmlNotation | 'auto',
+        diagramKind: (args.kind ?? 'state') as UmlDiagram,
+        roundTrip: args.roundTrip as boolean | undefined,
+        maxSteps: args.maxSteps as number | undefined,
+        intent: args.intent as UmlIntent | undefined,
+      })
+      return report as unknown as JsonValue
+    } catch (error) {
+      return refusal(error)
+    }
+  },
+})
+
+/** Print the label and comment contract the parser accepts. */
+export const umlExplainLabelsTool = defineTool({
+  name: UML_LABELS_TOOL_NAME,
+  description:
+    'Print the label and comment conventions the UML parser accepts, for one notation: the accepted label spellings, the form the renderer writes, the directives that pin what the notation cannot spell, and which lines are ignored. No diagram is needed. Use it when a hand-written diagram reports label drift or ignored lines and the reason is not obvious from the source. It reads no diagram and judges no modelling: `uml_parse` reads a diagram, and `uml_review` audits one.',
+  parameters: {
+    notation: notationParameter,
+    reportView: reportViewParameter,
+  },
+  output: reportOutput(UML_LABELS_TOOL_NAME),
+  presentCall: reportCallView(UML_LABELS_TOOL_NAME),
+  presentResult: reportResultView(UML_LABELS_TOOL_NAME),
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    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
+  },
+})
+
+/** The parse verdict counts parser notes as warnings: 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)
+}
+
+/** A front-end refusal travels as a failed result, with the code that says why. */
+function refusal(error: unknown): JsonValue {
+  const message = error instanceof Error ? error.message : String(error)
+  return errorResult(message, error instanceof UmlError ? error.code : undefined)
+}
+
+function errorResult(message: string, errorCode = 'UML_INPUT'): JsonValue {
+  // Carries the refusal schema. Every other family's refusal carries one, and a reader who decides "what am I
+  // holding" from `schema` got nothing from this one - it was the only refusal shaped differently.
+  return { ok: false, ran: false, ...refusalVerdict(message), schema: REPORT_SCHEMAS.umlRefusal, errorCode, error: message } as unknown as JsonValue
+}