dsh-model-everything 0.1.0 → 0.3.0

package/src/automaton.ts

@@ -0,0 +1,375 @@
+/**
+ * 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 (label.length === 1 && !reach[index]) {
+      findings.push({ code: 'AUT001_UNREACHABLE_STATE', severity: 'warning', message: `state "${label[0]}" cannot be reached from init` })
+    }
+    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 || extra !== undefined) {
+          const word = missing ?? extra
+          witness = { word: word ?? [], reason: missing !== undefined ? 'accepted by the first automaton, rejected by the second' : '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: ${word === undefined || word.length === 0 ? 'the empty word' : word.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 errors = findings.filter((finding) => finding.severity === 'error').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: ${findings.find((finding) => finding.severity === 'error')?.code ?? 'unknown'})`
+    : 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 { 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,6 +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.',
+    },
     reportView: {
       type: 'string',
       enum: ['digest', 'full'],
@@ -50,9 +55,14 @@ export const modelComposeTool = defineTool({
       description: 'Composition verification report with C1/C2 findings and, when shared locations are declared, C3/C4/C5.',
     },
     render(args, value) {
-      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
+      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
+    },
+  },  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 { reportCard, reportResultView } from './presentation.js'
 
 export const INTERLEAVING_SCAN_TOOL_NAME = 'model_interleaving_scan'
 
@@ -35,7 +36,12 @@ 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
+    },
+  },  presentResult: reportResultView(INTERLEAVING_SCAN_TOOL_NAME),
+
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {

package/src/data-engine.ts

@@ -1200,7 +1200,7 @@ function dataNextSteps(checks: CheckResult[]): string[] {
   // check looked at the model. `pass` does not say that, and neither does a list of the failures.
   const skipped = checks.filter((check) => check.status === 'skip').map((check) => check.name + ' (' + check.id + ')')
   if (skipped.length > 0) {
-    steps.push('These examined nothing, so their silence is not a result: ' + skipped.join(', ') + '. Declare what each one would need, or accept that the model is unverified on those points.')
+    steps.push('Not checked: ' + skipped.join(', ') + ' examined nothing — silence there is not a pass. Declare what each needs, or treat the model as unverified on those points.')
   }
   if (warningCodes.length > 0) steps.push('Review the warning findings (' + warningCodes.join(', ') + '): a nullable field or a missing index is a decision, not silence.')
   steps.push('Re-run with beforeModel plus the mapping/copy/migration options after the change to prove the data behaviour did not regress: migration coverage, copy consistency, rollback symmetry, and the before/after comparison. Then compare the two reports with `report_diff` rather than reading them side by side.')

package/src/data-tool.ts

@@ -1,8 +1,10 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from './json-value.js'
 import { runDataVerification, DATA_ENGINE_SCHEMA_VERSION } from './data-engine.js'
+import { oneOf } from './model-file.js'
 import { optionRefusal, requireArrayOption, requireObjectOption } from './option-shape.js'
 import { renderReportText } from './report-view.js'
+import { reportCard, reportResultView } from './presentation.js'
 
 export const DATAMODEL_VERIFY_TOOL_NAME = 'model_datamodel_verify'
 
@@ -19,8 +21,11 @@ export const modelDataModelVerifyTool = defineTool({
   parameters: {
     model: {
       type: 'json',
-      required: true,
-      description: 'DataModelV1 data model to verify.',
+      description: 'DataModelV1 data model to verify. Pass this, or modelPath, not both.',
+    },
+    modelPath: {
+      type: 'string',
+      description: 'Path to a JSON file holding the model, instead of inlining it. Formatting does not matter: whitespace, a BOM and pretty printing all parse. Relative paths resolve against the process working directory, which is the session workspace.',
     },
     beforeModel: {
       type: 'json',
@@ -42,6 +47,10 @@ export const modelDataModelVerifyTool = defineTool({
       type: 'json',
       description: 'Optional backup/restore pairs for DA7 rollback symmetry.',
     },
+    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'],
@@ -54,9 +63,14 @@ export const modelDataModelVerifyTool = defineTool({
       description: 'model-everything-datamodel verification report with summary and per-check findings.',
     },
     render(args, value) {
-      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
+      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
+    },
+  },  presentResult: reportResultView(DATAMODEL_VERIFY_TOOL_NAME),
+
   timeoutMs: 10_000,
   isConcurrencySafe: () => true,
   async execute(args) {
@@ -67,7 +81,7 @@ export const modelDataModelVerifyTool = defineTool({
       requireArrayOption(args.copyPairs, 'copyPairs', 'DATA_OPTION_INVALID')
       requireArrayOption(args.migrationMappings, 'migrationMappings', 'DATA_OPTION_INVALID')
       requireArrayOption(args.backupPairs, 'backupPairs', 'DATA_OPTION_INVALID')
-      return runDataVerification(args.model, {
+      return runDataVerification(oneOf(args.model, args.modelPath, 'model', 'modelPath', 'DATA_OPTION_INVALID'), {
         beforeModel: args.beforeModel,
         fieldMapping: args.fieldMapping as Record<string, string> | undefined,
         copyPairs: args.copyPairs as Array<{ id: string; sourceEntity: string; targetEntity: string; mapping: Record<string, string> }> | undefined,

package/src/design-tool.ts

@@ -1,60 +1,74 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from './json-value.js'
-import { REPORT_SCHEMAS } from './engine.js'
-import { runDesignReview } from './design-engine.js'
-import { renderReportText } from './report-view.js'
-
-export const DESIGN_TOOL_NAME = 'model_design_review'
-
-/**
- * Model-visible DSH tool that reviews a *design*: the shape of its dependency graph, and the
- * contracts the design states about itself.
- *
- * This is not `model_verify`. That one asks whether a machine can misbehave; this one asks
- * whether a design keeps its own declarations - which layer may depend on which, which
- * responsibility owns which dependency, which subtype may refuse which event. Two engines,
- * two questions, two verdicts that mean different things.
- */
-export const designTool = defineTool({
-  name: DESIGN_TOOL_NAME,
-  description:
-    'Hold a design to the contracts it declares about itself: layering, responsibility ownership, substitutability, interface width. For auditing a dependency diagram against a matrix use `uml_structure_verify`; this one decides the declarations the design makes about itself and reports the shape of its graph. Violations of a declaration decide `verdict`: DES1 cycle, DES2 layer order, DES3 boundary leak, DES5 unplaced node, DES6 missing required dependency, DES7 substitutability, DES9 split interface. Signals are facts, not defects: DES4 load-bearing element, DES8 uncalled operation, DES10 responsibility gap, DES11 abstraction on a concrete type. A check with nothing to hold the design to is `skip`, not `pass`. `facts` has ranks, fan-in/out, components, density, cyclomatic complexity, and the fewest edges whose removal makes the graph acyclic (exact for a small cyclic part, an upper bound past that: `feedbackArcsExact` says which). Read `verdict`, never `ok`.',
-  parameters: {
-    model: {
-      type: 'json',
-      required: true,
-      description:
-        'DesignModelV1: {schemaVersion: 1, architecture: {nodes: [ids], edges: [[from, to]]}, types?: [{name, stereotype, extends?, implements?, operations?, transitions?, forbids?, responsibilities?, dependsOn?, uses?, layer?}], declare?: {layers?, boundaries?, allowedEdges?, requiredEdges?}}. The schema is closed: an unknown key is refused rather than ignored. `types` is what makes the principle checks possible - with no `extends` there is no substitutability to decide, with no `uses` no interface can be called fat, and no `responsibilities` means nothing to compare the dependencies against.',
-    },
-    reportView: {
-      type: 'string',
-      enum: ['digest', 'full'],
-      description: 'digest (default) prints the readable body; full prints the structured report, which report_diff needs.',
-    },
-  },
-  output: {
-    schema: {
-      type: 'json',
-      description: 'Design review report: every check with its status, `violations` (they decide the verdict), `signals`, `facts` (graph features), summary and next steps.',
-    },
-    render(args, value) {
-      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
-    },
-  },
-  timeoutMs: 10_000,
-  isConcurrencySafe: () => true,
-  async execute(args) {
-    if (args.model === undefined) {
-      return {
-        ok: false,
-        ran: false,
-        verdict: 'fail',
-        verdictReason: 'the tool did not run: pass `model`, a DesignModelV1 with schemaVersion, architecture and the declarations to review it against',
-        schema: REPORT_SCHEMAS.design,
-        errorCode: 'DESIGN_INPUT',
-        error: 'design review needs `model`',
-      } as unknown as JsonValue
-    }
-    return runDesignReview(args.model) as unknown as JsonValue
-  },
-})
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { REPORT_SCHEMAS } from './engine.js'
+import { reportCard, reportResultView } from './presentation.js'
+import { oneOf } from './model-file.js'
+import { runDesignReview } from './design-engine.js'
+import { renderReportText } from './report-view.js'
+
+export const DESIGN_TOOL_NAME = 'model_design_review'
+
+/**
+ * Model-visible DSH tool that reviews a *design*: the shape of its dependency graph, and the
+ * contracts the design states about itself.
+ *
+ * This is not `model_verify`. That one asks whether a machine can misbehave; this one asks
+ * whether a design keeps its own declarations - which layer may depend on which, which
+ * responsibility owns which dependency, which subtype may refuse which event. Two engines,
+ * two questions, two verdicts that mean different things.
+ */
+export const designTool = defineTool({
+  name: DESIGN_TOOL_NAME,
+  description:
+    'Hold a design to the contracts it declares about itself: layering, responsibility ownership, substitutability, interface width. For auditing a dependency diagram against a matrix use `uml_structure_verify`; this one decides the declarations the design makes about itself and reports the shape of its graph. The split matters when a reader has a fact and a rule in one hand: which edges actually exist is the graph tool (it can scan a source tree with `repoPath`), and whether those edges were allowed is this one. Violations of a declaration decide `verdict`: DES1 cycle, DES2 layer order, DES3 boundary leak, DES5 unplaced node, DES6 missing required dependency, DES7 substitutability, DES9 split interface. Signals are facts, not defects: DES4 load-bearing element, DES8 uncalled operation, DES10 responsibility gap, DES11 abstraction on a concrete type. A check with nothing to hold the design to is `skip`, not `pass`. `facts` has ranks, fan-in/out, components, density, cyclomatic complexity, and the fewest edges whose removal makes the graph acyclic (exact for a small cyclic part, an upper bound past that: `feedbackArcsExact` says which). Read `verdict`, never `ok`.',
+  parameters: {
+    model: {
+      type: 'json',
+      description:
+        'DesignModelV1: {schemaVersion: 1, architecture: {nodes: [ids], edges: [[from, to]]}, types?: [{name, stereotype, extends?, implements?, operations?, transitions?, forbids?, responsibilities?, dependsOn?, uses?, layer?}], declare?: {layers?, boundaries?, allowedEdges?, requiredEdges?}}. The schema is closed: an unknown key is refused rather than ignored. `types` is what makes the principle checks possible - with no `extends` there is no substitutability to decide, with no `uses` no interface can be called fat, and no `responsibilities` means nothing to compare the dependencies against.',
+    },
+    modelPath: {
+      type: 'string',
+      description: 'Path to a JSON file holding the model, instead of inlining it. Formatting does not matter: whitespace, a BOM and pretty printing all parse. Relative paths resolve against the process working directory, which is the session workspace.',
+    },
+    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'],
+      description: 'digest (default) prints the readable body; full prints the structured report, which report_diff needs.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Design review report: every check with its status, `violations` (they decide the verdict), `signals`, `facts` (graph features), summary and next steps.',
+    },
+    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, DESIGN_TOOL_NAME) as unknown as JsonValue
+    },
+  },  presentResult: reportResultView(DESIGN_TOOL_NAME),
+
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    if (args.model === undefined && args.modelPath === undefined) {
+      return {
+        ok: false,
+        ran: false,
+        verdict: 'fail',
+        verdictReason: 'the tool did not run: pass `model` (a DesignModelV1 with schemaVersion, architecture and the declarations) or `modelPath` (a JSON file holding one)',
+        schema: REPORT_SCHEMAS.design,
+        errorCode: 'DESIGN_INPUT',
+        error: 'design review needs `model` or `modelPath`',
+      } as unknown as JsonValue
+    }
+    return runDesignReview(oneOf(args.model, args.modelPath, 'model', 'modelPath', 'DESIGN_OPTION_INVALID')) as unknown as JsonValue
+  },
+})