dsh-model-everything 0.2.0 → 0.3.0

package/src/export-tool.ts

@@ -1,81 +1,87 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from './json-value.js'
-import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, validateModel, verdictOf } from './engine.js'
-import { ExportError, exportModel, type ExportFormat } from './exporters.js'
-import { renderReportText } from './report-view.js'
-
-/** The model hash of an export's input, when the input validates (the success path always does). */
-function exportHashes(model: unknown): { hashSpec: typeof DEFAULT_HASH_SPEC; modelHash?: string } {
-  const validation = validateModel(model)
-  return validation.ok
-    ? { hashSpec: DEFAULT_HASH_SPEC, modelHash: modelHash(validation.model) }
-    : { hashSpec: DEFAULT_HASH_SPEC }
-}
-
-export const EXPORT_TOOL_NAME = 'model_export'
-
-/**
- * DSH tool wrapping the external-tool exporters: turn a LogicModelV1 machine into
- * native input for the tool this plugin routes to (UPPAAL / TLA+ / PRISM / SPIN).
- * v1 translates the core machine; unrepresentable invariants become warnings.
- */
-export const modelExportTool = defineTool({
-  name: EXPORT_TOOL_NAME,
-  description:
-    'Translate a LogicModelV1 into the input language of an external checker - UPPAAL, TLA+, PRISM or SPIN - for a property this plugin does not decide itself (symbolic model checking, unbounded induction, expected reward). format is one of uppaal (.xta + queries), tla (TLC spec + safety property), prism (.pm + .pctl), spin (Promela + ltl). This tool does not verify anything: for the checks it can decide use `model_verify`. Booleans are exported as 0/1 integers; invariants the target cannot express are returned as warnings, never silently dropped. Returns { ok, format, primary, extras?, warnings? } or { ok: false, error } when the model is invalid or the PRISM enumeration is too large.',
-  parameters: {
-    model: {
-      type: 'json',
-      required: true,
-      description: 'LogicModelV1 state-machine model to export.',
-    },
-    format: {
-      type: 'string',
-      required: true,
-      enum: ['uppaal', 'tla', 'prism', 'spin'],
-      description: 'Target tool format.',
-    },
-    reportView: {
-      type: 'string',
-      enum: ['digest', 'full'],
-      description: 'digest (default) prints the generated file verbatim; full prints the structured result as JSON.',
-    },
-  },
-  output: {
-    schema: {
-      type: 'json',
-      description: 'Export result with generated file content.',
-    },
-    render(args, value) {
-      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
-    },
-  },
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    try {
-      const result = exportModel(args.model, args.format as ExportFormat)
-      const warnings = result.warnings ?? []
-      const nextSteps: string[] = []
-      if (warnings.length > 0) nextSteps.push('The target notation cannot express some invariants; the warnings name each one — verify them in the target tool rather than assuming they carried over.')
-      nextSteps.push('Run the exported file through its own tool (verify/compile) before trusting the translation; this plugin guarantees the encoding, not the target checker\'s verdict.')
-      return {
-        ok: true,
-        ran: true,
-        ...verdictOf(0, warnings.length),
-        schema: REPORT_SCHEMAS.export,
-        format: result.format,
-        primary: result.primary,
-        ...(result.extras === undefined ? {} : { extras: result.extras }),
-        hashes: exportHashes(args.model),
-        warnings,
-        nextSteps,
-      } as unknown as JsonValue
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      // The exporter's own refusals carry their code: a limit of the encoding is not a defect in the model.
-      const errorCode = error instanceof ExportError ? error.code : 'MODEL_INVALID'
-      return { ok: false, ran: false, ...refusalVerdict(message), schema: REPORT_SCHEMAS.export, errorCode, error: message } as unknown as JsonValue
-    }
-  },
-})
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, validateModel, verdictOf } from './engine.js'
+import { reportCard, reportResultView } from './presentation.js'
+import { ExportError, exportModel, type ExportFormat } from './exporters.js'
+import { renderReportText } from './report-view.js'
+
+/** The model hash of an export's input, when the input validates (the success path always does). */
+function exportHashes(model: unknown): { hashSpec: typeof DEFAULT_HASH_SPEC; modelHash?: string } {
+  const validation = validateModel(model)
+  return validation.ok
+    ? { hashSpec: DEFAULT_HASH_SPEC, modelHash: modelHash(validation.model) }
+    : { hashSpec: DEFAULT_HASH_SPEC }
+}
+
+export const EXPORT_TOOL_NAME = 'model_export'
+
+/**
+ * DSH tool wrapping the external-tool exporters: turn a LogicModelV1 machine into
+ * native input for the tool this plugin routes to (UPPAAL / TLA+ / PRISM / SPIN).
+ * v1 translates the core machine; unrepresentable invariants become warnings.
+ */
+export const modelExportTool = defineTool({
+  name: EXPORT_TOOL_NAME,
+  description:
+    'Translate a LogicModelV1 into the input language of an external checker - UPPAAL, TLA+, PRISM or SPIN - for a property this plugin does not decide itself (symbolic model checking, unbounded induction, expected reward). format is one of uppaal (.xta + queries), tla (TLC spec + safety property), prism (.pm + .pctl), spin (Promela + ltl). This tool does not verify anything: for the checks it can decide use `model_verify`. Booleans are exported as 0/1 integers; invariants the target cannot express are returned as warnings, never silently dropped. Returns { ok, format, primary, extras?, warnings? } or { ok: false, error } when the model is invalid or the PRISM enumeration is too large.',
+  parameters: {
+    model: {
+      type: 'json',
+      required: true,
+      description: 'LogicModelV1 state-machine model to export.',
+    },
+    format: {
+      type: 'string',
+      required: true,
+      enum: ['uppaal', 'tla', 'prism', 'spin'],
+      description: 'Target tool format.',
+    },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the generated file verbatim; full prints the structured result as JSON.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Export result with generated file content.',
+    },
+    render(args, value) {
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
+    },
+    // The card a UI shows, separated from the text the model reads.
+    presentationMeta(_args, value) {
+      return reportCard(value, EXPORT_TOOL_NAME) as unknown as JsonValue
+    },
+  },  presentResult: reportResultView(EXPORT_TOOL_NAME),
+
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      const result = exportModel(args.model, args.format as ExportFormat)
+      const warnings = result.warnings ?? []
+      const nextSteps: string[] = []
+      if (warnings.length > 0) nextSteps.push('The target notation cannot express some invariants; the warnings name each one — verify them in the target tool rather than assuming they carried over.')
+      nextSteps.push('Run the exported file through its own tool (verify/compile) before trusting the translation; this plugin guarantees the encoding, not the target checker\'s verdict.')
+      return {
+        ok: true,
+        ran: true,
+        ...verdictOf(0, warnings.length),
+        schema: REPORT_SCHEMAS.export,
+        format: result.format,
+        primary: result.primary,
+        ...(result.extras === undefined ? {} : { extras: result.extras }),
+        hashes: exportHashes(args.model),
+        warnings,
+        nextSteps,
+      } as unknown as JsonValue
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      // The exporter's own refusals carry their code: a limit of the encoding is not a defect in the model.
+      const errorCode = error instanceof ExportError ? error.code : 'MODEL_INVALID'
+      return { ok: false, ran: false, ...refusalVerdict(message), schema: REPORT_SCHEMAS.export, errorCode, error: message } as unknown as JsonValue
+    }
+  },
+})

package/src/index.ts

@@ -39,6 +39,8 @@ import { umlRenderTool, umlParseTool, umlReviewTool, umlExplainLabelsTool } from
 import { umlStructureTool } from './structure-tool.js'
 import { designTool } from './design-tool.js'
 import { reportDiffTool } from './report-diff-tool.js'
+import { modelEditTool } from './edit-tool.js'
+import { modelAutomatonTool } from './automaton-tool.js'
 import { ENGINE_SCHEMA_VERSION } from './engine.js'
 
 // DSH 0.1.7-alpha.1 (session format v4) retires the shared
@@ -245,6 +247,8 @@ export function apply(ctx: Context, config: Config): void {
       ctx.effect(() => tools.register(umlStructureTool), 'dsh-model-everything: structure tool')
       ctx.effect(() => tools.register(designTool), 'dsh-model-everything: design review tool')
       ctx.effect(() => tools.register(reportDiffTool), 'dsh-model-everything: report diff tool')
+      ctx.effect(() => tools.register(modelEditTool), 'dsh-model-everything: model edit tool')
+      ctx.effect(() => tools.register(modelAutomatonTool), 'dsh-model-everything: automaton tool')
       toolRegistered = true
       dataToolRegistered = true
       concurrencyToolRegistered = true

package/src/presentation.ts

@@ -0,0 +1,125 @@
+/**
+ * What a UI shows for a report, separated from what the model reads.
+ *
+ * A report is written for a model: it names every check, every finding and the next step, because the
+ * model has to act on all of it. A reader wants four things instead - did it run, what does it decide,
+ * what is the first thing wrong, what to do next - and wants the rest folded away.
+ *
+ * Two host hooks carry that split:
+ *
+ * - `output.presentationMeta` projects a small JSON payload the host persists on the result; a client
+ *   card narrows it without parsing prose.
+ * - `presentResult` returns the card body from that payload, so a UI that supports it shows the summary
+ *   and a UI that does not falls back to the raw text. The model-facing content never changes.
+ *
+ * Both are pure and replayable: they read the persisted value, never the filesystem.
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { routeFor } from './routing.js'
+import type { ToolResultView } from '@deepseek-ai/dsh-tools'
+
+/** One finding, as a card needs it: a code to name it and a sentence to read. */
+export interface CardFinding {
+  code: string
+  severity: string
+  message: string
+}
+
+/** The payload a client card narrows. Small on purpose: a card is a summary, not a second report. */
+export interface ReportCard {
+  verdict?: string
+  verdictReason?: string
+  errors: number
+  warnings: number
+  checksRun?: number
+  first: CardFinding | null
+  /** The one step a reader should take, already a sentence. */
+  next: string | null
+  /** Which family produced this, so a card can pick an icon and a colour without parsing codes. */
+  family: string
+  /** What this family owns, and where the case just outside it goes. One table, not a second prose copy. */
+  route?: { owns: string; instead: string }
+}
+
+const SHORT = 160
+
+function shorten(text: string, limit = SHORT): string {
+  const flat = text.replace(/\s+/g, ' ').trim()
+  return flat.length <= limit ? flat : flat.slice(0, limit - 1).trimEnd() + '…'
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined
+}
+
+function array(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+/**
+ * Project a report into the card payload.
+ *
+ * Read defensively: this runs on replay too, and a payload that once had a shape may come back with a
+ * field missing. A card that throws would take the whole session view with it.
+ */
+export function reportCard(value: unknown, family: string): ReportCard {
+  const report = record(value) ?? {}
+  const findings = array(report.findings)
+    .map((entry) => record(entry))
+    .filter((entry): entry is Record<string, unknown> => entry !== undefined)
+  const severity = (entry: Record<string, unknown>): string => String(entry.severity ?? 'info')
+  const errors = findings.filter((entry) => severity(entry) === 'error')
+  const warnings = findings.filter((entry) => severity(entry) === 'warning')
+  const summary = record(report.summary)
+  const checksRun = typeof summary?.checksRun === 'number'
+    ? summary.checksRun
+    : array(report.checks).length > 0
+      ? array(report.checks).length
+      : undefined
+  const first = errors[0] ?? warnings[0]
+  const next = array(report.nextSteps).map((step) => String(step))[0]
+  return {
+    ...(typeof report.verdict === 'string' ? { verdict: report.verdict } : {}),
+    ...(typeof report.verdictReason === 'string' ? { verdictReason: shorten(report.verdictReason) } : {}),
+    errors: errors.length,
+    warnings: warnings.length,
+    ...(checksRun === undefined ? {} : { checksRun }),
+    first: first === undefined
+      ? null
+      : { code: String(first.code ?? 'UNKNOWN'), severity: severity(first), message: shorten(String(first.message ?? '')) },
+    next: next === undefined ? null : shorten(next),
+    family,
+    ...(routeFor(family) === undefined
+      ? {}
+      : { route: { owns: routeFor(family)?.owns ?? '', instead: routeFor(family)?.notFor.tool ?? '' } }),
+  }
+}
+
+/** The card body: four lines, in the order a reader asks the questions. */
+export function cardBlocks(card: ReportCard): ContentBlock[] {
+  const lines: string[] = []
+  const head = card.verdict === undefined ? card.family : card.verdict.toUpperCase()
+  const counts = card.checksRun === undefined
+    ? `${String(card.errors)} error(s), ${String(card.warnings)} warning(s)`
+    : `${String(card.checksRun)} checks · ${String(card.errors)} error(s) · ${String(card.warnings)} warning(s)`
+  lines.push(head + '  —  ' + counts)
+  if (card.verdictReason !== undefined) lines.push(card.verdictReason)
+  if (card.first !== null) {
+    lines.push((card.first.severity === 'error' ? '✗ ' : '⚠ ') + card.first.code + ': ' + card.first.message)
+  }
+  if (card.next !== null) lines.push('next: ' + card.next)
+  return [{ type: 'text', text: lines.join('\n') }]
+}
+
+/**
+ * `presentResult` for a report tool: render the card from the persisted payload, and fall back to the
+ * raw content by returning undefined when there is none.
+ */
+export function reportResultView(family: string) {
+  return (_args: unknown, result: { content: ContentBlock[]; meta?: unknown }): ToolResultView | undefined => {
+    const card = record(result.meta) as unknown as ReportCard | undefined
+    if (card === undefined || card === null) return undefined
+    if (card.verdict === undefined && card.next === null && card.first === null) return undefined
+    return { card: 'generic', title: family + '  ' + (card.verdict ?? '') , content: cardBlocks(card) }
+  }
+}

package/src/report-diff-tool.ts

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { diffReports } from './baseline.js'
 import { refusalVerdict } from './engine.js'
+import { reportCard, reportResultView } from './presentation.js'
 import { renderReportText } from './report-view.js'
 
 export const REPORT_DIFF_TOOL_NAME = 'report_diff'
@@ -54,7 +55,12 @@ export const reportDiffTool = defineTool({
     render(args, value) {
       return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
     },
-  },
+    // The card a UI shows, separated from the text the model reads.
+    presentationMeta(_args, value) {
+      return reportCard(value, REPORT_DIFF_TOOL_NAME) as unknown as JsonValue
+    },
+  },  presentResult: reportResultView(REPORT_DIFF_TOOL_NAME),
+
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {

package/src/report-view.ts

@@ -199,6 +199,29 @@ function headerLines(report: Record_, options: Required<ReportViewOptions>): str
     ok === undefined || verdict === undefined ? '' : `ok=${String(ok)}`,
   ].filter((bit) => bit !== '')
   lines.push(bits.join('  '))
+  // A graph report answers "which module is the hub" in one line: counting incoming edges off the graph by
+  // hand is where a correct graph still produced a wrong answer, in both conditions of the round that asked.
+  const degreeSummary = record(report.summary)
+  const hubs = array(degreeSummary?.hubs).map((entry) => record(entry)).filter((entry) => entry !== undefined)
+  if (hubs.length > 0) {
+    const counts = degreeSummary?.nodes !== undefined && degreeSummary?.edges !== undefined ? `  ${String(degreeSummary.nodes)} modules, ${String(degreeSummary.edges)} edges` : ''
+    lines.push(`GRAPH${counts}`)
+    lines.push('  ' + hubs.map((entry) => `${String(entry.id)} (${String(entry.dependents)} dependents)`).join(', '))
+    const leaves = array(degreeSummary?.leaves).map((leaf) => String(leaf))
+    if (leaves.length > 0) lines.push('  imports nothing: ' + leaves.join(', '))
+  }
+  // A scan has to say what it covered, or a model that cannot see the boundary recounts the tree by hand
+  // and spends more than the tool saved. The numbers are the boundary: files read, references resolved.
+  const scan = record(report.scan)
+  if (scan !== undefined) {
+    const files = String(scan.files ?? '?')
+    const unresolved = Number(scan.unresolved ?? 0)
+    const languages = array(scan.languages).map((entry) => String(entry))
+    lines.push(`SCAN  ${files} files read, ${String(unresolved)} unresolved${languages.length === 0 ? '' : ', ' + languages.join(', ')}`)
+    lines.push(unresolved === 0
+      ? '  this is the whole tree: every relative reference resolved, so a recount by hand cannot find more'
+      : '  the unresolved lines above are outside this tree; count nothing twice')
+  }
   // A refusal carries no model to hash, and the field is an empty string rather than absent, so it rendered
   // as `modelHash=…` - which reads as a truncated hash rather than as nothing to hash. An empty value means
   // the same thing as a missing one here.
@@ -259,6 +282,29 @@ function footerLines(report: Record_): string[] {
 }
 
 /** A `checks[]` report (verify, compose, datamodel): silence pass, expand the rest. */
+/**
+ * An edit result: what changed in the model, then what changed in the findings.
+ *
+ * The two belong together because the second is the reason the first happened. The delta is
+ * rendered by the delta renderer rather than restated here, so an edit and a `report_diff` of the
+ * same two reports cannot drift apart.
+ */
+function renderEditReport(report: Record_, options: Required<ReportViewOptions>): string[] {
+  const lines = headerLines(report, options)
+  const changes = array(report.changes).map((value) => record(value) ?? {})
+  const added = changes.filter((change) => text(change.kind) === 'added').length
+  const removed = changes.filter((change) => text(change.kind) === 'removed').length
+  const updated = changes.filter((change) => text(change.kind) === 'updated').length
+  lines.push(`CHANGES  ${String(added)} added, ${String(removed)} removed, ${String(updated)} updated`)
+  for (const change of changes) {
+    const detail = text(change.detail)
+    lines.push(`  ${text(change.kind) ?? '?'} ${text(change.what) ?? '?'}${detail === undefined || detail === '' ? '' : ` — ${detail}`}`)
+  }
+  const delta = record(report.reportDelta)
+  if (delta !== undefined) lines.push('', ...renderDeltaReport(delta, options))
+  return [...lines, ...wrapFooter(report)]
+}
+
 function renderChecksReport(report: Record_, options: Required<ReportViewOptions>): string[] {
   const checks = array(report.checks).map((value) => record(value) ?? {})
   const byStatus = (status: string): string[] =>
@@ -286,7 +332,8 @@ function renderChecksReport(report: Record_, options: Required<ReportViewOptions
     .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 lines = [...headerLines(report, options)]
+  lines.push(`CHECKS  ${inventory}`)
   const requested = options.check
   const ids = checks.map((check) => text(check.id)).filter((id): id is string => id !== undefined)
   const selected = requested === undefined ? checks : checks.filter((check) => text(check.id) === requested)
@@ -470,7 +517,11 @@ export function renderReportText(value: unknown, options: ReportViewOptions = {}
   // which printed the whole object as JSON.
   const isDelta = Array.isArray(report.added) || Array.isArray(report.removed) || Array.isArray(report.changed) || typeof report.currentVerdict === 'string'
   const isPayload = typeof report.diagram === 'string' || typeof report.primary === 'string'
-  const lines = hasChecks
+  // An edit result names its changes; the findings it brings along are a delta, which already has a renderer.
+  const isEdit = Array.isArray(report.changes)
+  const lines = isEdit
+    ? renderEditReport(report, resolved)
+    : hasChecks
     ? renderChecksReport(report, resolved)
     : isDelta
       ? renderDeltaReport(report, resolved)

package/src/routing.ts

@@ -0,0 +1,96 @@
+/**
+ * Which tool owns which question, in one table.
+ *
+ * Two consumers read this, and they used to read two different things: the result a model gets
+ * (`nextSteps` naming a sibling) and the toolset map a human reads (hand-written prose). That is how the
+ * map came to say "about ten thousand characters" while the descriptions measured twenty-nine: a fact
+ * stated twice drifts, and nothing fails when it does.
+ *
+ * So the table states the routing once. `routeFor` hands it to the card a UI draws; the toolset map
+ * generator reads the same table and refuses to write a map for a tool that is missing from it.
+ *
+ * What it is not: a decision. The tool a request should use is chosen by the model from the descriptions.
+ * This table says what each tool owns and which neighbour takes the case just outside that line, so a
+ * report can redirect without a reader having to remember the roster.
+ */
+
+export interface Route {
+  /** What this tool decides, in the words its report already uses. */
+  owns: string
+  /** The case just outside the line, and the tool that owns it. */
+  notFor: { when: string; tool: string }
+}
+
+export const ROUTES: Record<string, Route> = {
+  model_verify: {
+    owns: 'one machine: reachable states, invariants, deadlock, and a before/after regression',
+    notFor: { when: 'two or more machines must handshake or share a location', tool: 'model_compose_verify' },
+  },
+  model_compose_verify: {
+    owns: 'several machines run together: rendezvous, shared locations, lost updates',
+    notFor: { when: 'the question is about one machine on its own', tool: 'model_verify' },
+  },
+  model_automaton_verify: {
+    owns: 'a finite-word language, and its relation to another automaton',
+    notFor: { when: 'the question is reachability or deadlock inside one state machine', tool: 'model_verify' },
+  },
+  model_edit: {
+    owns: 'one editing round on a model file, answered with the structural diff and the change in findings',
+    notFor: { when: 'the edit is done and the model has to be decided again', tool: 'model_verify' },
+  },
+  model_datamodel_verify: {
+    owns: 'entities, keys, migrations, and whether the data survived them',
+    notFor: { when: 'the question is about behaviour over time rather than stored state', tool: 'model_verify' },
+  },
+  model_design_review: {
+    owns: "a design's own declarations: layering, responsibility, substitutability, interface width",
+    notFor: { when: 'the question is a fact about the graph - does this edge exist', tool: 'uml_structure_verify' },
+  },
+  model_interleaving_scan: {
+    owns: 'mining a document or plan for concurrency claims, and routing each to the analysis that decides it',
+    notFor: { when: 'the protocol itself has to be decided', tool: 'model_compose_verify' },
+  },
+  model_export: {
+    owns: 'a model translated into UPPAAL, TLA+, PRISM or SPIN for a property this plugin does not decide',
+    notFor: { when: 'the property can be decided here', tool: 'model_verify' },
+  },
+  report_diff: {
+    owns: 'what changed between two reports of the same family',
+    notFor: { when: 'the current report does not exist yet', tool: 'model_verify' },
+  },
+  uml_render: {
+    owns: 'drawing a model in the notation that can carry its family',
+    notFor: { when: 'the question is whether the modelling is sound', tool: 'uml_review' },
+  },
+  uml_parse: {
+    owns: 'reading a diagram back into the model its family declares',
+    notFor: { when: 'the question is whether the diagram says something sound', tool: 'uml_review' },
+  },
+  uml_review: {
+    owns: 'auditing the modelling: reachability, ambiguity, round-trip fidelity, family-specific defects',
+    notFor: { when: 'the claim is about behaviour rather than the drawing', tool: 'model_verify' },
+  },
+  uml_explain_labels: {
+    owns: 'the label spellings a notation accepts and the directives that pin the rest',
+    notFor: { when: 'a diagram has to be read rather than explained', tool: 'uml_parse' },
+  },
+  uml_structure_verify: {
+    owns: 'a dependency graph as a graph - cycles, layers, dangling edges - from a drawing or a source tree',
+    notFor: { when: 'the question is a rule the design declared for itself, not an edge that exists', tool: 'model_design_review' },
+  },
+}
+
+/** The route for a tool, or undefined when the tool has none. */
+export function routeFor(tool: string): Route | undefined {
+  return ROUTES[tool]
+}
+
+/** Every tool a route names, for a caller that has to check the table against the registry. */
+export function routedTools(): string[] {
+  return Object.keys(ROUTES)
+}
+
+/** The tools named as the owner of an adjacent case. */
+export function siblingTools(): string[] {
+  return [...new Set(Object.values(ROUTES).map((route) => route.notFor.tool))].sort()
+}