dsh-model-everything 0.2.0 → 0.4.0

package/skills/model-everything/references/automata.md

@@ -0,0 +1,102 @@
+# Automata as a verification target
+
+What `model_automaton_verify` decides, why each decision is a theorem rather than a heuristic, and where
+the boundary sits. Read it when a report has to be defended, or when a question lands on the edge:
+liveness, infinite words, or a product that will not finish.
+
+## Scope
+
+Finite words over an explicit alphabet. A run starts at `init`, reads one symbol per transition, and is
+accepted if it ends in `accepting`.
+
+Not in scope, and the report says so:
+
+- liveness, fairness, "eventually" properties on an infinite run;
+- timing, clocks, deadlines;
+- conformance by observation rather than by language;
+- any abstraction. The tool reads a model, never program source.
+
+## What each check decides, and on what authority
+
+| Check | Decision | Authority |
+|---|---|---|
+| `AUT003` nondeterminism | whether some state has two transitions on one symbol | the definition of a deterministic automaton |
+| `AUT001` unreachable | whether a state is reachable from `init` | reachability is decidable in linear space |
+| `AUT002` trap | whether a reachable state can still reach acceptance | the same reachability, run backwards |
+| `AUT004` empty language | whether any accepting state is reachable | emptiness of a finite automaton is decidable |
+| `AUT005` alphabet mismatch | whether the two machines can be compared at all | a language relation needs one alphabet |
+| `AUT006` equivalence | whether two machines accept the same words | decide `L(A) \ L(B)` and `L(B) \ L(A)` |
+| `AUT007` subset | whether every word of the first is a word of the second | decide `L(A) \ L(B)` |
+| `AUT008` superset | the same, with the sides exchanged | decide `L(B) \ L(A)` |
+| `AUT009` undecided | the product search stopped at its cap | a stopped search proves nothing |
+
+Equivalence and inclusion are decided by exploring the product of the two automata and asking whether an
+accepting side pairs with a rejecting one. A breadth-first walk returns the **shortest** word that does,
+so the witness is the smallest counterexample there is, not merely one that exists.
+
+## The wall, stated plainly
+
+These are decidable problems, not approximations: automaton equivalence is NL-complete, inclusion for
+nondeterministic machines and LTL model checking are PSPACE-complete. The cost is what grows, not the
+certainty. Two machines of `n` states each can produce `n × n` pairs, and a model with counters or
+queues in it can be unbounded before anyone writes a single transition.
+
+So a cap is honest and a larger cap is not a strategy. When the product stops, the report carries
+`AUT009_UNDECIDED` and sets `truncated: true`: the verdict is "not known", never "equal". If the same
+happens to a state machine in `model_verify`, the report names the escalation instead of suggesting a
+bigger budget.
+
+## Reading, by what each one settles
+
+Foundations, for the constructions above:
+
+- Hopcroft, Motwani, Ullman, *Introduction to Automata Theory, Languages, and Computation* — subset
+  construction, product automata, the equivalence test.
+- Sipser, *Introduction to the Theory of Computation* — closure properties and decidability, in the
+  gentler telling.
+
+Model checking, which is where liveness lives and this family stops:
+
+- Baier and Katoen, *Principles of Model Checking* — LTL, CTL, Büchi automata, fairness. The boundary in
+  the scope section above is this book's first half.
+- Clarke, Grumberg, Peled, *Model Checking* — the classical account, including why explicit enumeration
+  runs out.
+
+The automata-theoretic framing this tool is a finite-word shadow of:
+
+- Kurshan, *Computer-Aided Verification of Coordinating Processes* — systems as automata, properties as
+  automata, language inclusion as the decision procedure.
+- Vardi and Wolper, *An automata-theoretic approach to automatic program verification* — the same idea
+  for LTL, with Büchi acceptance.
+
+Conformance, for what "implementation matches specification" means when it is made precise:
+
+- Tretmans, *Model Based Testing with Labelled Transition Systems* — `ioco` and the family of
+  implementation relations; `subset` and `superset` are the language-level versions of that choice.
+- Lynch and Vaandrager, *Forward and backward simulations* — refinement in two directions, which is
+  exactly the difference between asking `subset` and asking `superset`.
+
+## What a pass does not mean
+
+A passing report says the stated words are accepted or rejected as claimed. It does not say the model is
+the system: the alphabet is whatever the modeller wrote, and a property that needs a symbol nobody
+declared cannot be seen. State the alphabet next to the claim, or the verdict is about a machine that
+exists only in the report.
+
+## Provenance
+
+Which parts are borrowed, and which are this repository's own decisions. A check that came from a
+textbook is cited so a reader can check the argument; a choice that is not in any book is marked as one.
+
+| Part | Where it comes from |
+|---|---|
+| subset construction for determinisation | Hopcroft, Motwani and Ullman |
+| deciding equivalence and inclusion on the product | Hopcroft, Motwani and Ullman; Kurshan for the framing |
+| the shortest-witness search | breadth-first search on the product; the choice to return the shortest word is this repository's |
+| the check codes and their grouping | this repository's convention, shared with the other families |
+| `truncated` and the `_UNDECIDED` suffix | this repository's convention: a stopped search is not a pass |
+| the cap on the product | this repository's decision, and a practical one, not a theoretical boundary |
+| `subset` and `superset` as the two refinements | Tretmans; Lynch and Vaandrager |
+
+The theory above decides the checks. Nothing in this family is a heuristic dressed as a decision: every
+code either proves a property or says it could not.

package/src/automaton-tool.ts

@@ -0,0 +1,74 @@
+/**
+ * `model_automaton_verify`: what language does this machine accept, and is it the one it claims.
+ *
+ * The description is written for the decision. A conformance claim - "the implementation allows every run
+ * the specification allows" - is a language inclusion, and the two machines can be small while the
+ * question is still beyond a reading: the witness is a word nobody thought to try.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+import { verifyAutomaton, type AutomatonRelation } from './automaton.js'
+import type { JsonValue } from './json-value.js'
+import { optionRefusal } from './option-shape.js'
+import { renderReportText } from './report-view.js'
+import { reportCallView, reportCard, reportResultView } from './presentation.js'
+
+export const MODEL_AUTOMATON_TOOL_NAME = 'model_automaton_verify'
+
+export const modelAutomatonTool = defineTool({
+  name: MODEL_AUTOMATON_TOOL_NAME,
+  description:
+    'Decide a finite-word automaton: what it accepts, whether it is empty, whether a state is a trap, and whether its language equals, contains or is contained in another automaton. Use it for a conformance claim - the protocol the code implements against the one the specification draws - where the answer is a word that one machine accepts and the other rejects, not an opinion. ' +
+    'Give `other` to compare two automata; `relation` picks equivalent (default), subset (the first is contained in the second) or superset. A failed relation returns the shortest witness word. ' +
+    'Determinism, reachability and trap states are reported whether or not `other` is given. ' +
+    'It decides finite words over an explicit alphabet. Liveness, fairness, timing and infinite words are out of scope: a Büchi or timed model is a different family, and this tool does not build one. For reachability or deadlock in a single state machine use `model_verify`; for machines that must handshake use `model_compose_verify`.',
+  parameters: {
+    automaton: {
+      type: 'json',
+      required: true,
+      description: 'The automaton: {states: [ids], alphabet: [symbols], transitions: [{from, symbol, to}], init, accepting: [ids]}. An NFA is accepted and determinised; nondeterminism is reported.',
+    },
+    other: {
+      type: 'json',
+      description: 'The automaton to compare against, in the same shape. Omit to check this one on its own.',
+    },
+    relation: {
+      type: 'string',
+      enum: ['equivalent', 'subset', 'superset'],
+      description: 'Which language relation `other` must stand in. Default equivalent. subset: the first is contained in the second; superset: the second is contained in the first.',
+    },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the readable body; full prints the structured result.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'the automaton report: verdict, findings, the witness word when a relation fails, and hashes of the inputs.',
+    },
+    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: a verdict and the first thing wrong,
+    // never the whole report.
+    presentationMeta(args, value) {
+      return reportCard(value, MODEL_AUTOMATON_TOOL_NAME) as unknown as JsonValue
+    },
+  },
+  presentCall: reportCallView(MODEL_AUTOMATON_TOOL_NAME),
+  presentResult: reportResultView(MODEL_AUTOMATON_TOOL_NAME),
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      return verifyAutomaton(args.automaton, {
+        ...(args.other === undefined ? {} : { other: args.other }),
+        ...(args.relation === undefined ? {} : { relation: args.relation as AutomatonRelation }),
+      }) as unknown as JsonValue
+    } catch (error) {
+      return optionRefusal(error, 'AUTOMATON_OPTION_INVALID') as unknown as JsonValue
+    }
+  },
+})

package/src/automaton.ts

@@ -0,0 +1,376 @@
+/**
+ * Automata as a verification target: the claims a state machine cannot express.
+ *
+ * A state machine in `model_verify` answers "can this configuration be reached". An automaton answers a
+ * different question: what language does this accept, and is that language contained in, or equal to,
+ * another one. That is the shape of a protocol conformance claim - "every run the implementation allows
+ * is a run the specification allows" - and it is not settled by reading either of the two machines.
+ *
+ * Scope, stated because it is what the report is allowed to claim:
+ *
+ * - finite words over an explicit alphabet; NFAs are determinised first;
+ * - the empty language, universality, reachability, dead states, and the relation between two automata;
+ * - not: liveness, fairness, timing, or infinite words. A Büchi or timed automaton is a different family.
+ */
+import { createHash } from 'node:crypto'
+
+import { canonicalJson } from './engine.js'
+import { OptionShapeError } from './option-shape.js'
+
+export interface AutomatonTransition {
+  from: string
+  symbol: string
+  to: string
+}
+
+export interface Automaton {
+  states: string[]
+  alphabet: string[]
+  transitions: AutomatonTransition[]
+  init: string
+  accepting: string[]
+}
+
+export interface AutomatonFinding {
+  code: string
+  severity: 'error' | 'warning' | 'info'
+  message: string
+  detail?: string
+}
+
+/** One deterministic automaton, with an explicit sink so every word has exactly one run. */
+interface Dfa {
+  start: number
+  accept: boolean[]
+  /** delta[state][symbolIndex] = next state */
+  delta: number[][]
+  /** Which machine state each index came from, for readable witnesses and findings. */
+  labels: string[][]
+}
+
+const SINK = '\u0000sink'
+
+/** Validate the shape, so a refusal says which field is wrong rather than throwing later. */
+export function validateAutomaton(input: unknown): { ok: true; automaton: Automaton } | { ok: false; errors: string[] } {
+  const errors: string[] = []
+  const value = input as Record<string, unknown> | null
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return { ok: false, errors: ['automaton must be an object with states, alphabet, transitions, init and accepting.'] }
+  }
+  const states = value.states
+  if (!Array.isArray(states) || states.length === 0 || states.some((state) => typeof state !== 'string' || state === '')) {
+    errors.push('states: must be a non-empty array of non-empty strings')
+  }
+  const alphabet = value.alphabet
+  if (!Array.isArray(alphabet) || alphabet.length === 0 || alphabet.some((symbol) => typeof symbol !== 'string' || symbol === '')) {
+    errors.push('alphabet: must be a non-empty array of non-empty strings')
+  }
+  const init = value.init
+  if (typeof init !== 'string' || init === '') errors.push('init: must be a non-empty string')
+  const accepting = value.accepting
+  if (!Array.isArray(accepting) || accepting.some((state) => typeof state !== 'string')) {
+    errors.push('accepting: must be an array of state ids')
+  }
+  const transitions = value.transitions
+  if (!Array.isArray(transitions)) errors.push('transitions: must be an array of {from, symbol, to}')
+  if (errors.length > 0) return { ok: false, errors }
+
+  const known = new Set(states as string[])
+  if (typeof init === 'string' && !known.has(init)) errors.push(`init: names "${init}", which is not a declared state`)
+  for (const state of accepting as string[]) {
+    if (!known.has(state)) errors.push(`accepting: names "${state}", which is not a declared state`)
+  }
+  const symbols = new Set(alphabet as string[])
+  for (const [index, raw] of (transitions as unknown[]).entries()) {
+    const transition = raw as Record<string, unknown> | null
+    if (transition === null || typeof transition !== 'object') {
+      errors.push(`transitions[${index}]: must be an object`)
+      continue
+    }
+    if (typeof transition.from !== 'string' || !known.has(transition.from)) errors.push(`transitions[${index}].from: "${String(transition.from)}" is not a declared state`)
+    if (typeof transition.to !== 'string' || !known.has(transition.to)) errors.push(`transitions[${index}].to: "${String(transition.to)}" is not a declared state`)
+    if (typeof transition.symbol !== 'string' || !symbols.has(transition.symbol)) errors.push(`transitions[${index}].symbol: "${String(transition.symbol)}" is not in the alphabet`)
+  }
+  if (errors.length > 0) return { ok: false, errors }
+  return {
+    ok: true,
+    automaton: {
+      states: states as string[],
+      alphabet: alphabet as string[],
+      transitions: (transitions as AutomatonTransition[]).map((transition) => ({ from: transition.from, symbol: transition.symbol, to: transition.to })),
+      init: init as string,
+      accepting: accepting as string[],
+    },
+  }
+}
+
+/** Determinise by subset construction, adding one explicit sink so a word never stops early. */
+function determinise(automaton: Automaton, symbols: string[]): Dfa {
+  const index = new Map<string, number>()
+  const subsets: string[][] = []
+  const delta: number[][] = []
+  const accept: boolean[] = []
+  const accepting = new Set(automaton.accepting)
+  const byFromAndSymbol = new Map<string, string[]>()
+  for (const transition of automaton.transitions) {
+    const key = transition.from + '\u0000' + transition.symbol
+    byFromAndSymbol.set(key, [...(byFromAndSymbol.get(key) ?? []), transition.to])
+  }
+
+  const intern = (label: string[], acceptingHere: boolean): number => {
+    const key = label.join('\u0000')
+    const existing = index.get(key)
+    if (existing !== undefined) return existing
+    const id = subsets.length
+    index.set(key, id)
+    subsets.push(label)
+    accept.push(acceptingHere)
+    delta.push([])
+    return id
+  }
+
+  const start = intern([automaton.init], accepting.has(automaton.init))
+  // Each subset is expanded exactly once: a subset reached again - a self-loop, or a second path into
+  // the same set - only needs its edge recorded, not another pass through its transitions.
+  const pending = [start]
+  const expanded = new Set<number>([start])
+  while (pending.length > 0) {
+    const current = pending.shift() as number
+    for (const [symbolIndex, symbol] of symbols.entries()) {
+      const next = new Set<string>()
+      for (const state of subsets[current]) {
+        for (const target of byFromAndSymbol.get(state + '\u0000' + symbol) ?? []) next.add(target)
+      }
+      const label = [...next].sort()
+      const acceptingNext = label.some((state) => accepting.has(state))
+      const id = intern(label.length === 0 ? [SINK] : label, acceptingNext)
+      delta[current][symbolIndex] = id
+      if (!expanded.has(id)) {
+        expanded.add(id)
+        pending.push(id)
+      }
+    }
+  }
+  return { start, accept, delta, labels: subsets.map((subset) => (subset[0] === SINK ? [] : subset)) }
+}
+
+/** The product search stopped at its cap, so the relation is undecided rather than true. */
+const UNDECIDED = Symbol('undecided')
+
+/**
+ * Shortest word accepted by `a` but not by `b`, when one exists.
+ *
+ * The product has at most |a| x |b| states, which is fine for the machines this family is for and can
+ * still explode on two large ones. The cap turns that into "undecided", because a search that stopped
+ * is not a proof that the languages are equal.
+ */
+function difference(first: Dfa, second: Dfa, symbols: string[], limit = 10_000): string[] | undefined | typeof UNDECIDED {
+  const seen = new Set<string>()
+  const queue: { left: number; right: number; word: string[] }[] = [{ left: first.start, right: second.start, word: [] }]
+  seen.add(first.start + ':' + second.start)
+  let expanded = 0
+  while (queue.length > 0) {
+    if (++expanded > limit) return UNDECIDED
+    const node = queue.shift() as { left: number; right: number; word: string[] }
+    if (first.accept[node.left] && !second.accept[node.right]) return node.word
+    for (const [symbolIndex, symbol] of symbols.entries()) {
+      const left = first.delta[node.left][symbolIndex]
+      const right = second.delta[node.right][symbolIndex]
+      const key = left + ':' + right
+      if (seen.has(key)) continue
+      seen.add(key)
+      queue.push({ left, right, word: [...node.word, symbol] })
+    }
+  }
+  return undefined
+}
+
+/** Every state that can be reached from the start. */
+function reachable(dfa: Dfa, symbols: string[]): boolean[] {
+  const seen = new Array<boolean>(dfa.delta.length).fill(false)
+  seen[dfa.start] = true
+  const queue = [dfa.start]
+  while (queue.length > 0) {
+    const current = queue.shift() as number
+    for (let symbolIndex = 0; symbolIndex < symbols.length; symbolIndex++) {
+      const next = dfa.delta[current][symbolIndex]
+      if (!seen[next]) {
+        seen[next] = true
+        queue.push(next)
+      }
+    }
+  }
+  return seen
+}
+
+/** Every state from which an accepting state can be reached. */
+function productive(dfa: Dfa, symbols: string[]): boolean[] {
+  const reverse = new Map<number, number[]>()
+  for (let state = 0; state < dfa.delta.length; state++) {
+    for (let symbolIndex = 0; symbolIndex < symbols.length; symbolIndex++) {
+      const target = dfa.delta[state][symbolIndex]
+      reverse.set(target, [...(reverse.get(target) ?? []), state])
+    }
+  }
+  const seen = new Array<boolean>(dfa.delta.length).fill(false)
+  const queue: number[] = []
+  for (let state = 0; state < dfa.accept.length; state++) {
+    if (dfa.accept[state]) {
+      seen[state] = true
+      queue.push(state)
+    }
+  }
+  while (queue.length > 0) {
+    const current = queue.shift() as number
+    for (const previous of reverse.get(current) ?? []) {
+      if (!seen[previous]) {
+        seen[previous] = true
+        queue.push(previous)
+      }
+    }
+  }
+  return seen
+}
+
+export type AutomatonRelation = 'equivalent' | 'subset' | 'superset'
+
+export interface AutomatonReport {
+  ok: boolean
+  ran: boolean
+  verdict: 'pass' | 'pass_with_findings' | 'fail'
+  verdictReason: string
+  schema: string
+  automaton: { states: number; transitions: number; alphabet: number; deterministic: boolean }
+  findings: AutomatonFinding[]
+  /** Set when the relation fails: the shortest word that breaks it. */
+  witness?: { word: string[]; reason: string }
+  /** True when the product search stopped before deciding, so `pass` is not a proof of equality. */
+  truncated?: boolean
+  hashes: { automaton: string; other?: string }
+  nextSteps: string[]
+}
+
+/** Determinism, as declared by the input rather than guessed: a repeated (from, symbol) pair. */
+function isDeterministic(automaton: Automaton): boolean {
+  const seen = new Set<string>()
+  for (const transition of automaton.transitions) {
+    const key = transition.from + '\u0000' + transition.symbol
+    if (seen.has(key)) return false
+    seen.add(key)
+  }
+  return true
+}
+
+
+export function verifyAutomaton(input: unknown, options: { other?: unknown; relation?: AutomatonRelation } = {}): AutomatonReport {
+  const parsed = validateAutomaton(input)
+  if (!parsed.ok) {
+    throw new OptionShapeError('AUTOMATON_INVALID', 'the automaton is not well formed: ' + parsed.errors.join('; '))
+  }
+  const automaton = parsed.automaton
+  const symbols = [...automaton.alphabet].sort()
+  const findings: AutomatonFinding[] = []
+  const dfa = determinise(automaton, symbols)
+  const deterministic = isDeterministic(automaton)
+
+  const reach = reachable(dfa, symbols)
+  const canAccept = productive(dfa, symbols)
+  if (!deterministic) {
+    findings.push({ code: 'AUT003_NONDETERMINISTIC', severity: 'info', message: `the automaton is not deterministic: ${String(dfa.delta.length)} subset states after determinisation, ${String(automaton.states.length)} declared. The analysis used the deterministic form.` })
+  }
+  // A state no word can reach is dead weight, and a state from which no accepting state is reachable
+  // accepts nothing: the first is a modelling smell, the second is usually a defect in the intended language.
+  for (const [index, label] of dfa.labels.entries()) {
+    if (label.length === 0) continue
+    if (!dfa.accept[index] && reach[index] && !canAccept[index]) {
+      findings.push({ code: 'AUT002_TRAP_STATE', severity: 'warning', message: `state "${label[0]}" is reachable but can never reach an accepting state` })
+    }
+  }
+  for (const state of automaton.states) {
+    if (!dfa.labels.some((label) => label.includes(state))) {
+      if (!findings.some((finding) => finding.code === 'AUT001_UNREACHABLE_STATE' && finding.message.includes(`"${state}"`))) {
+        findings.push({ code: 'AUT001_UNREACHABLE_STATE', severity: 'warning', message: `state "${state}" cannot be reached from init` })
+      }
+    }
+  }
+
+  const acceptingReachable = reach.some((value, index) => value && dfa.accept[index])
+  if (!acceptingReachable) {
+    findings.push({ code: 'AUT004_EMPTY_LANGUAGE', severity: 'warning', message: 'the automaton accepts nothing: no accepting state is reachable from init' })
+  }
+
+  let witness: AutomatonReport['witness']
+  let otherForHash: Automaton | undefined
+  const relation = options.relation ?? 'equivalent'
+  if (options.other !== undefined) {
+    const otherParsed = validateAutomaton(options.other)
+    if (!otherParsed.ok) {
+      throw new OptionShapeError('AUTOMATON_INVALID', 'the second automaton is not well formed: ' + otherParsed.errors.join('; '))
+    }
+    const other = otherParsed.automaton
+    otherForHash = other
+    if (other.alphabet.length !== automaton.alphabet.length || !other.alphabet.every((symbol) => automaton.alphabet.includes(symbol))) {
+      findings.push({ code: 'AUT005_ALPHABET_MISMATCH', severity: 'error', message: 'the two automata do not share an alphabet, so a language relation between them is not defined', detail: `first: ${automaton.alphabet.join(', ')}; second: ${other.alphabet.join(', ')}` })
+    } else {
+      const second = determinise(other, symbols)
+      const missing = difference(dfa, second, symbols)
+      const extra = difference(second, dfa, symbols)
+      if (missing === UNDECIDED || extra === UNDECIDED) {
+        findings.push({ code: 'AUT009_UNDECIDED', severity: 'warning', message: 'the product search stopped at its state cap before deciding the relation, so equality is neither proven nor refuted', detail: 'the product of two automata can be exponential; reduce one of them, or decide the relation with a tool that searches symbolically' })
+      } else
+      if (relation === 'equivalent') {
+        if (missing !== undefined) {
+          witness = { word: missing, reason: 'accepted by the first automaton, rejected by the second' }
+          findings.push({ code: 'AUT006_NOT_EQUIVALENT', severity: 'error', message: 'the two automata accept different languages', detail: `shortest witness: ${missing.length === 0 ? 'the empty word' : missing.join(' ')}; ${witness.reason}` })
+        } else if (extra !== undefined) {
+          witness = { word: extra, reason: 'accepted by the second automaton, rejected by the first' }
+          findings.push({ code: 'AUT006_NOT_EQUIVALENT', severity: 'error', message: 'the two automata accept different languages', detail: `shortest witness: ${extra.length === 0 ? 'the empty word' : extra.join(' ')}; ${witness.reason}` })
+        }
+      } else if (relation === 'subset') {
+        if (missing !== undefined) {
+          witness = { word: missing, reason: 'accepted by the first automaton, rejected by the second' }
+          findings.push({ code: 'AUT007_NOT_SUBSET', severity: 'error', message: 'the first automaton accepts a word the second rejects', detail: `shortest witness: ${missing.length === 0 ? 'the empty word' : missing.join(' ')}` })
+        }
+      } else if (extra !== undefined) {
+        witness = { word: extra, reason: 'accepted by the second automaton, rejected by the first' }
+        findings.push({ code: 'AUT008_NOT_SUPERSET', severity: 'error', message: 'the second automaton accepts a word the first rejects', detail: `shortest witness: ${extra.length === 0 ? 'the empty word' : extra.join(' ')}` })
+      }
+    }
+  }
+
+  const errorFindings = findings.filter((finding) => finding.severity === 'error')
+  const errors = errorFindings.length
+  const warnings = findings.filter((finding) => finding.severity === 'warning').length
+  const verdict = errors > 0 ? 'fail' : warnings > 0 ? 'pass_with_findings' : 'pass'
+  const reason = errors > 0
+    ? `${String(errors)} error finding(s) (first: ${errorFindings[0].code})`
+    : warnings > 0
+      ? `no error findings; ${String(warnings)} warning finding(s)`
+      : 'every check passed'
+
+  const nextSteps: string[] = []
+  if (findings.some((finding) => finding.code === 'AUT004_EMPTY_LANGUAGE')) nextSteps.push('An automaton that accepts nothing usually has a transition or an accepting set wrong; check that the accepting set is reachable from init.')
+  if (witness !== undefined) nextSteps.push('The witness is the shortest word that separates the two languages; replay it through both automata to see which transition makes the difference.')
+  if (!deterministic) nextSteps.push('The analysis determinised the input; if nondeterminism was accidental, the subset count is the tell.')
+  nextSteps.push('This decides finite-word languages only. Liveness, fairness and timing are not in scope: those need a Büchi or timed model, which this family does not build.')
+
+  return {
+    ok: true,
+    ran: true,
+    verdict,
+    verdictReason: reason,
+    schema: 'model-everything/automaton/v1',
+    automaton: { states: automaton.states.length, transitions: automaton.transitions.length, alphabet: automaton.alphabet.length, deterministic },
+    findings,
+    ...(witness === undefined ? {} : { witness }),
+    ...(findings.some((finding) => finding.code === 'AUT009_UNDECIDED') ? { truncated: true } : {}),
+    hashes: { automaton: hashAutomaton(automaton), ...(otherForHash === undefined ? {} : { other: hashAutomaton(otherForHash) }) },
+    nextSteps,
+  }
+}
+
+const createHashHex = (text: string): string => createHash('sha256').update(text).digest('hex')
+
+function hashAutomaton(automaton: Automaton): string {
+  return createHashHex(canonicalJson({ states: [...automaton.states].sort(), alphabet: [...automaton.alphabet].sort(), transitions: automaton.transitions.map((t) => `${t.from}\u0000${t.symbol}\u0000${t.to}`).sort(), init: automaton.init, accepting: [...automaton.accepting].sort() }))
+}

package/src/compose-tool.ts

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
-import { runCompositionVerification } from './engine.js'
+import { runCompositionVerification } from './engine.js'
+import { reportCallView, reportCard, reportResultView } from './presentation.js'
 import type { SharedAccess, SharedLocation } from './engine.js'
 import { OptionShapeError, optionRefusal, requireArrayOption } from './option-shape.js'
 import { renderReportText } from './report-view.js'
@@ -38,10 +39,10 @@ export const modelComposeTool = defineTool({
       type: 'integer',
       description: 'Maximum composite states to explore. Default 10000.',
     },
-    check: {
-      type: 'string',
-      description: 'Print one check in full when the digest truncated it. Pass the check id the CHECKS line lists (for example A9); the per-check budget no longer applies, and an id this report does not carry is answered with the ids that it does.',
-    },
+    check: {
+      type: 'string',
+      description: 'Print one check in full when the digest truncated it. Pass the check id the CHECKS line lists (for example A9); the per-check budget no longer applies, and an id this report does not carry is answered with the ids that it does.',
+    },
     reportView: {
       type: 'string',
       enum: ['digest', 'full'],
@@ -56,7 +57,14 @@ export const modelComposeTool = 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, COMPOSE_TOOL_NAME) as unknown as JsonValue
+    },
   },
+  presentCall: reportCallView(COMPOSE_TOOL_NAME),
+  presentResult: reportResultView(COMPOSE_TOOL_NAME),
+
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {

package/src/concurrency-tool.ts

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { runConcurrencyScan } from './concurrency.js'
 import { renderReportText } from './report-view.js'
+import { reportCallView, reportCard, scanResultView } from './presentation.js'
 
 export const INTERLEAVING_SCAN_TOOL_NAME = 'model_interleaving_scan'
 
@@ -35,7 +36,14 @@ export const modelConcurrencyScanTool = 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, INTERLEAVING_SCAN_TOOL_NAME) as unknown as JsonValue
+    },
   },
+  presentCall: reportCallView(INTERLEAVING_SCAN_TOOL_NAME),
+  presentResult: scanResultView,
+
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {

package/src/data-tool.ts

@@ -4,6 +4,7 @@ import { runDataVerification, DATA_ENGINE_SCHEMA_VERSION } from './data-engine.j
 import { oneOf } from './model-file.js'
 import { optionRefusal, requireArrayOption, requireObjectOption } from './option-shape.js'
 import { renderReportText } from './report-view.js'
+import { reportCallView, reportCard, reportResultView } from './presentation.js'
 
 export const DATAMODEL_VERIFY_TOOL_NAME = 'model_datamodel_verify'
 
@@ -64,7 +65,14 @@ export const modelDataModelVerifyTool = 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, DATAMODEL_VERIFY_TOOL_NAME) as unknown as JsonValue
+    },
   },
+  presentCall: reportCallView(DATAMODEL_VERIFY_TOOL_NAME),
+  presentResult: reportResultView(DATAMODEL_VERIFY_TOOL_NAME),
+
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {