dsh-model-everything 0.1.0 → 0.3.0

package/src/edit-tool.ts

@@ -0,0 +1,119 @@
+/**
+ * `model_edit`: change a model file by naming the change, then see what the engine now says.
+ *
+ * The loop this replaces is edit-and-re-verify: hand back the whole model, get the whole report,
+ * repeat. Here the file holds the model, an operation holds the change, and the report carries the
+ * structural diff plus the difference in findings - so one call answers "what did I change, and did
+ * it fix anything".
+ *
+ * The description is written for the decision, not the schema: when this tool pays, when another
+ * one does, and what it refuses.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+import { diffReports } from './baseline.js'
+import { applyEdits, readModelFile } from './editor.js'
+import { REPORT_SCHEMAS, runVerification } from './engine.js'
+import { reportCard, reportResultView } from './presentation.js'
+import type { JsonValue } from './json-value.js'
+import { optionRefusal } from './option-shape.js'
+import { renderReportText } from './report-view.js'
+
+export const MODEL_EDIT_TOOL_NAME = 'model_edit'
+
+export const modelEditTool = defineTool({
+  name: MODEL_EDIT_TOOL_NAME,
+  description:
+    'Change a model file by naming one change, then see what the engine now decides. Use it to fix a model over several rounds: write the model to a file once, then add a state, tighten a guard, drop a transition and let the report show whether the finding went away. ' +
+    'It answers with the structural diff and, unless you set verify: false, the difference in findings - new errors, gone findings, before and after verdict - so one call replaces edit-then-verify-then-compare. ' +
+    'It refuses an edit that would leave an invalid model and writes nothing, so the file is always verifiable. ' +
+    'Do not use it to build a model from nothing (write the file or verify inline first), to check work that is not a state machine (`model_datamodel_verify`, `model_design_review`), or to judge the design as a whole (`model_verify` reports; this tool only compares its own edit).',
+  parameters: {
+    modelPath: {
+      type: 'string',
+      required: true,
+      description: 'Path to the model file to edit. It must already exist; the edit is applied to a copy and written back atomically.',
+    },
+    ops: {
+      type: 'json',
+      required: true,
+      description:
+        'Ordered list of operations, applied as one batch. Compact form: {addState: "c"} · {removeState: "c"} · {addTransition: ["from", "event", "to"]} · {removeTransition: ["from", "event"]} · {updateTransition: ["from", "event", {guard: ...}]} · {set: ["/path", value]} · {remove: "/path"}. Long form ({op: ..., state/transition/path/value}) works too, and addState/addTransition take the full object when you need terminal, guard, updates or cost.',
+    },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the changes and the report delta; full prints the structured result, which report_diff needs.',
+    },
+    allowInvalid: {
+      type: 'boolean',
+      description: 'Write the batch even when the result does not validate. Use it only for an edit that needs two calls with a broken model in between; the reply then carries validationErrors, and the next verification will refuse the file.',
+    },
+    verify: {
+      type: 'boolean',
+      description: 'Run the engine on the model before and after the edit and return the difference in findings. Default true; pass false for a batch of edits where only the final state matters.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'the edit result: structural changes, the new verdict, and the report delta when verify ran.',
+    },
+    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, MODEL_EDIT_TOOL_NAME) as unknown as JsonValue
+    },
+  },  presentResult: reportResultView(MODEL_EDIT_TOOL_NAME),
+
+  timeoutMs: 20_000,
+  isConcurrencySafe: () => false,
+  async execute(args) {
+    try {
+      const before = readModelFile(args.modelPath).model
+      const verify = args.verify !== false
+      const beforeReport = verify ? runVerification(before) : undefined
+      const { model, changes, valid, errors } = applyEdits(args.modelPath, args.ops, { allowInvalid: args.allowInvalid === true })
+      const afterReport = verify ? runVerification(model) : undefined
+      // A model that did not decide anything (checksRun 0 - the engine refused its shape) has no
+      // findings to compare. Diffing it would raise, and it would raise after the file was written,
+      // so the reply would claim nothing ran while the edit had landed. Say there is no delta instead.
+      const decided = (report: typeof beforeReport): boolean => (report?.summary?.checksRun ?? 0) > 0
+      const compare = beforeReport !== undefined && afterReport !== undefined && decided(beforeReport) && decided(afterReport)
+      const delta = compare ? diffReports(beforeReport, afterReport) : undefined
+      const noDelta = verify && !compare ? (decided(beforeReport) ? 'the edited model did not decide anything, so there is no after-report to compare' : 'the model before the edit did not decide anything, so there is no before-report to compare') : undefined
+      const verdict = afterReport?.verdict ?? 'pass'
+      const reason =
+        (afterReport === undefined ? 'edit applied, not verified: ' : '') +
+        changes.map((change) => `${change.kind} ${change.what}${change.detail === '' ? '' : ' (' + change.detail + ')'}`).join('; ') +
+        (delta === undefined ? (noDelta === undefined ? '' : ` — ${noDelta}`) : ` — verdict ${String(beforeReport?.verdict ?? '?')} -> ${String(delta.currentVerdict ?? '?')}`)
+      return {
+        ok: true,
+        ran: true,
+        schema: REPORT_SCHEMAS.edit,
+        verdict,
+        verdictReason: reason,
+        changes,
+        ...(valid ? {} : { modelValid: false, validationErrors: errors }),
+        // `undefined` is not lossless JSON: with verify off there is no hash to report, so the field
+        // is omitted rather than filled with nothing.
+        ...(afterReport === undefined ? {} : { hashes: { hashSpec: afterReport.hashSpec, modelHash: afterReport.modelHash } }),
+        ...(beforeReport === undefined ? {} : { before: { verdict: beforeReport.verdict, modelHash: beforeReport.modelHash } }),
+        ...(afterReport === undefined ? {} : { after: { verdict: afterReport.verdict, errors: afterReport.summary?.errors, warnings: afterReport.summary?.warnings } }),
+        ...(delta === undefined ? {} : { reportDelta: delta }),
+        nextSteps:
+          delta === undefined
+            ? [noDelta === undefined
+                ? 'The file now holds the edited model. Run `model_verify` with its `modelPath` when the edits are done.'
+                : 'The edit is on disk. Run `model_verify` on the file: it now decides whether this is a valid model.']
+            : delta.added.length === 0 && delta.removed.length === 0
+              ? ['The edit moved nothing in the findings. Change the part of the model the finding names, or report the finding as unresolved.']
+              : [],
+      } as unknown as JsonValue
+    } catch (error) {
+      return optionRefusal(error, 'EDIT_OPTION_INVALID') as unknown as JsonValue
+    }
+  },
+})

package/src/editor.ts

@@ -0,0 +1,297 @@
+/**
+ * Applying edits to a model file: the delta side of the verification loop.
+ *
+ * A model is the largest thing any of these tools takes. Handing it back whole on every
+ * iteration is what makes a four-round fix cost four models. Here an edit names one change,
+ * the file carries the rest, and the caller gets the structural diff plus - when asked - the
+ * difference in what the engine decided, in the same call.
+ *
+ * Every operation works on a copy and the result is validated before anything is written. A
+ * refused edit leaves the file exactly as it was: an invalid model on disk would make the next
+ * verification spend a round reporting that, which is the cost this tool exists to remove.
+ */
+import { readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { validateModel } from './engine.js'
+import { OptionShapeError } from './option-shape.js'
+
+type Json = Record<string, unknown>
+
+export interface EditOperation {
+  op: string
+  [key: string]: unknown
+}
+
+export interface ModelChange {
+  kind: 'added' | 'removed' | 'updated'
+  what: string
+  detail: string
+}
+
+const CLONE = (value: unknown): unknown => JSON.parse(JSON.stringify(value)) as unknown
+
+/** Read the model at `path`; a missing file is a refusal, not an empty model. */
+export function readModelFile(path: unknown): { model: Json; full: string } {
+  if (typeof path !== 'string' || path.trim() === '') {
+    throw new OptionShapeError('EDIT_OPTION_INVALID', 'modelPath must be a non-empty path to a JSON file.')
+  }
+  const full = resolve(path)
+  let text: string
+  try {
+    text = readFileSync(full, 'utf8')
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new OptionShapeError('EDIT_OPTION_INVALID', `modelPath could not be read: ${reason}. Edits apply to a file that already exists; model_verify can create the model inline first, or write it yourself.`)
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text.replace(/^\uFEFF/, ''))
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new OptionShapeError('EDIT_OPTION_INVALID', `modelPath is not valid JSON: ${reason}.`)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new OptionShapeError('EDIT_OPTION_INVALID', 'modelPath must hold a model object, not a list or a scalar.')
+  }
+  return { model: parsed as Json, full }
+}
+
+function statesOf(model: Json): Json[] {
+  return Array.isArray(model.states) ? (model.states as Json[]) : []
+}
+function transitionsOf(model: Json): Json[] {
+  return Array.isArray(model.transitions) ? (model.transitions as Json[]) : []
+}
+
+function requireString(value: unknown, name: string): string {
+  if (typeof value !== 'string' || value === '') throw new OptionShapeError('EDIT_OPTION_INVALID', `${name} must be a non-empty string.`)
+  return value
+}
+
+/** JSON pointer, so anything without a named operation still has a way to be edited. */
+function pointerParts(path: unknown): string[] {
+  const text = requireString(path, 'path')
+  if (!text.startsWith('/')) throw new OptionShapeError('EDIT_OPTION_INVALID', `path must be a JSON pointer starting with "/", got ${JSON.stringify(text)}.`)
+  return text.split('/').slice(1).map((part) => part.replace(/~1/g, '/').replace(/~0/g, '~'))
+}
+
+function atPointer(model: Json, parts: string[], create: boolean): { parent: Json; key: string } {
+  let node: Json = model
+  for (const part of parts.slice(0, -1)) {
+    const next = (node as Record<string, unknown>)[part]
+    if (next === undefined) {
+      if (!create) throw new OptionShapeError('EDIT_OPTION_INVALID', `path does not exist at "${part}".`)
+      const created: Json = {}
+      ;(node as Record<string, unknown>)[part] = created
+      node = created
+    } else if (next !== null && typeof next === 'object') {
+      node = next as Json
+    } else {
+      throw new OptionShapeError('EDIT_OPTION_INVALID', `path runs through "${part}", which is not an object.`)
+    }
+  }
+  return { parent: node, key: parts[parts.length - 1] ?? '' }
+}
+
+/**
+ * Accept the compact spelling of an operation as well as the long one.
+ *
+ * An operation is a small thing - add a state, wire a transition - and the long form spends more
+ * tokens on key names than on the change. Five operations cost 76 tokens spelled out and 39 in the
+ * compact form, and a batch of twenty is where that difference starts to matter.
+ *
+ *   {addState: "c"}                    {addState: {id: "c", terminal: true}}
+ *   {removeState: "c"}
+ *   {addTransition: ["a", "reset", "c"]}     {addTransition: {from, event, to, guard?, ...}}
+ *   {removeTransition: ["a", "go"]}          {updateTransition: ["a", "go", {guard: ...}]}
+ *   {set: ["/init", "a"]}                    {remove: "/init"}
+ *
+ * The long form is unchanged and is what the errors talk about.
+ */
+export function normalizeOperation(raw: unknown): EditOperation {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new OptionShapeError('EDIT_OPTION_INVALID', 'every op must be an object.')
+  }
+  const value = raw as Record<string, unknown>
+  if (typeof value.op === 'string') return value as EditOperation
+  const keys = Object.keys(value)
+  if (keys.length !== 1) {
+    throw new OptionShapeError('EDIT_OPTION_INVALID', `an operation names exactly one op, got ${JSON.stringify(keys)}.`)
+  }
+  const name = keys[0]
+  const argument = value[name]
+  if (name === 'addState' || name === 'removeState') {
+    if (typeof argument === 'string') {
+      return name === 'addState' ? { op: name, state: { id: argument } } : { op: name, id: argument }
+    }
+    if (name === 'addState' && argument !== null && typeof argument === 'object') return { op: name, state: argument }
+    throw new OptionShapeError('EDIT_OPTION_INVALID', `${name} takes a state id, or a state object for addState.`)
+  }
+  if (name === 'addTransition' || name === 'removeTransition' || name === 'updateTransition') {
+    if (Array.isArray(argument)) {
+      if (name === 'addTransition' && argument.length === 3) {
+        const [from, event, to] = argument
+        return { op: name, transition: { from, event, to } }
+      }
+      if (name === 'removeTransition' && argument.length === 2) {
+        const [from, event] = argument
+        return { op: name, from, event }
+      }
+      if (name === 'updateTransition' && argument.length === 3) {
+        const [from, event, patch] = argument
+        return { op: name, from, event, patch }
+      }
+      throw new OptionShapeError('EDIT_OPTION_INVALID', `${name} takes ${name === 'updateTransition' ? '["from", "event", {patch}]' : name === 'addTransition' ? '["from", "event", "to"]' : '["from", "event"]'}.`)
+    }
+    if (name === 'addTransition' && argument !== null && typeof argument === 'object') return { op: name, transition: argument }
+    throw new OptionShapeError('EDIT_OPTION_INVALID', `${name} takes a list, or a transition object for addTransition.`)
+  }
+  if (name === 'set') {
+    if (Array.isArray(argument) && argument.length === 2) return { op: 'set', path: argument[0], value: argument[1] }
+    if (argument !== null && typeof argument === 'object' && 'path' in (argument as Record<string, unknown>)) {
+      const { path, value } = argument as Record<string, unknown>
+      return { op: 'set', path, value }
+    }
+    throw new OptionShapeError('EDIT_OPTION_INVALID', 'set takes ["/path", value] or {path, value}.')
+  }
+  if (name === 'remove') {
+    if (typeof argument === 'string') return { op: 'remove', path: argument }
+    throw new OptionShapeError('EDIT_OPTION_INVALID', 'remove takes a JSON pointer string.')
+  }
+  throw new OptionShapeError('EDIT_OPTION_INVALID', `unknown op ${JSON.stringify(name)}. Known ops: addState, removeState, addTransition, removeTransition, updateTransition, set, remove.`)
+}
+
+/** Apply one operation to a model copy, returning the changes it made. */
+export function applyOperation(model: Json, operation: EditOperation): ModelChange[] {
+  const op = requireString(operation.op, 'op')
+  const changes: ModelChange[] = []
+  if (op === 'addState') {
+    const state = operation.state as Json | undefined
+    const id = requireString(state?.id, 'state.id')
+    if (statesOf(model).some((entry) => entry.id === id)) {
+      throw new OptionShapeError('EDIT_OPTION_INVALID', `state "${id}" already exists; use update on it instead of adding it twice.`)
+    }
+    model.states = [...statesOf(model), state]
+    changes.push({ kind: 'added', what: 'state ' + id, detail: state?.terminal === true ? 'terminal' : '' })
+    return changes
+  }
+  if (op === 'removeState') {
+    const id = requireString(operation.id, 'id')
+    const before = statesOf(model)
+    if (!before.some((entry) => entry.id === id)) throw new OptionShapeError('EDIT_OPTION_INVALID', `no state "${id}" to remove.`)
+    model.states = before.filter((entry) => entry.id !== id)
+    const dropped = transitionsOf(model).filter((entry) => entry.from === id || entry.to === id)
+    model.transitions = transitionsOf(model).filter((entry) => entry.from !== id && entry.to !== id)
+    changes.push({ kind: 'removed', what: 'state ' + id, detail: dropped.length > 0 ? `and ${String(dropped.length)} transition(s) that used it` : '' })
+    return changes
+  }
+  if (op === 'addTransition') {
+    const transition = operation.transition as Json | undefined
+    const from = requireString(transition?.from, 'transition.from')
+    const event = requireString(transition?.event, 'transition.event')
+    const to = requireString(transition?.to, 'transition.to')
+    if (transitionsOf(model).some((entry) => entry.from === from && entry.event === event)) {
+      throw new OptionShapeError('EDIT_OPTION_INVALID', `a transition for ${from} + ${event} already exists; update it instead of adding another.`)
+    }
+    model.transitions = [...transitionsOf(model), transition]
+    changes.push({ kind: 'added', what: `transition ${from} + ${event}`, detail: 'to ' + to })
+    return changes
+  }
+  if (op === 'removeTransition') {
+    const from = requireString(operation.from, 'from')
+    const event = requireString(operation.event, 'event')
+    const before = transitionsOf(model)
+    const kept = before.filter((entry) => !(entry.from === from && entry.event === event))
+    if (kept.length === before.length) throw new OptionShapeError('EDIT_OPTION_INVALID', `no transition for ${from} + ${event} to remove.`)
+    model.transitions = kept
+    changes.push({ kind: 'removed', what: `transition ${from} + ${event}`, detail: '' })
+    return changes
+  }
+  if (op === 'updateTransition') {
+    const from = requireString(operation.from, 'from')
+    const event = requireString(operation.event, 'event')
+    const patch = operation.patch as Json | undefined
+    if (patch === undefined || typeof patch !== 'object' || Array.isArray(patch)) {
+      throw new OptionShapeError('EDIT_OPTION_INVALID', 'patch must be an object of the fields to replace.')
+    }
+    const list = transitionsOf(model)
+    const index = list.findIndex((entry) => entry.from === from && entry.event === event)
+    if (index < 0) throw new OptionShapeError('EDIT_OPTION_INVALID', `no transition for ${from} + ${event} to update.`)
+    list[index] = { ...list[index], ...patch }
+    model.transitions = list
+    changes.push({ kind: 'updated', what: `transition ${from} + ${event}`, detail: Object.keys(patch).join(', ') })
+    return changes
+  }
+  if (op === 'set') {
+    const parts = pointerParts(operation.path)
+    if (parts.length === 0) throw new OptionShapeError('EDIT_OPTION_INVALID', 'path must name something inside the model.')
+    const { parent, key } = atPointer(model, parts, true)
+    parent[key] = CLONE(operation.value)
+    changes.push({ kind: 'updated', what: 'set ' + String(operation.path), detail: '' })
+    return changes
+  }
+  if (op === 'remove') {
+    const parts = pointerParts(operation.path)
+    if (parts.length === 0) throw new OptionShapeError('EDIT_OPTION_INVALID', 'path must name something inside the model.')
+    const { parent, key } = atPointer(model, parts, false)
+    if (!(key in parent)) throw new OptionShapeError('EDIT_OPTION_INVALID', `nothing at ${String(operation.path)} to remove.`)
+    delete parent[key]
+    changes.push({ kind: 'removed', what: 'remove ' + String(operation.path), detail: '' })
+    return changes
+  }
+  throw new OptionShapeError('EDIT_OPTION_INVALID', `unknown op ${JSON.stringify(op)}. Known ops: addState, removeState, addTransition, removeTransition, updateTransition, set, remove.`)
+}
+
+/** Validate the edited model and write it atomically. A refused edit leaves the file untouched. */
+export interface EditOutcome {
+  model: Json
+  changes: ModelChange[]
+  full: string
+  /** Whether the model as written validates. False only when the caller allowed it. */
+  valid: boolean
+  errors: string[]
+}
+
+export function applyEdits(path: unknown, operations: unknown, options: { allowInvalid?: boolean } = {}): EditOutcome {
+  if (!Array.isArray(operations) || operations.length === 0) {
+    throw new OptionShapeError('EDIT_OPTION_INVALID', 'ops must be a non-empty array of operations.')
+  }
+  const { model: original, full } = readModelFile(path)
+  const next = CLONE(original) as Json
+  const changes: ModelChange[] = []
+  const normalized = (operations as unknown[]).map((raw, index) => {
+    try {
+      return normalizeOperation(raw)
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      throw new OptionShapeError('EDIT_OPTION_INVALID', `operation ${String(index + 1)} was refused: ${reason}`)
+    }
+  })
+  for (const [index, raw] of normalized.entries()) {
+    try {
+      changes.push(...applyOperation(next, raw))
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      throw new OptionShapeError('EDIT_OPTION_INVALID', `operation ${String(index + 1)} (${String((raw as EditOperation).op)}) was refused: ${reason}`)
+    }
+  }
+  const validation = validateModel(next)
+  if (!validation.ok && options.allowInvalid !== true) {
+    // Name the operation the batch first stops validating at, not just the symptom: a caller that
+    // reads "a transition to an unknown state" still has to find which entry introduced it.
+    let firstBad = -1
+    const partial = CLONE(original) as Json
+    for (const [index, raw] of (operations as EditOperation[]).entries()) {
+      try { applyOperation(partial, raw) } catch { firstBad = index; break }
+      if (!validateModel(partial).ok) { firstBad = index; break }
+    }
+    const where = firstBad < 0 ? '' : ` Operation ${String(firstBad + 1)} (${String((operations as EditOperation[])[firstBad]?.op)}) is where it first stops validating.`
+    throw new OptionShapeError('EDIT_RESULT_INVALID', 'the batch would leave an invalid model, so nothing was written: ' + validation.errors.join('; ') + '.' + where + ' Fix the list, or pass allowInvalid to write it anyway and continue in a second call.')
+  }
+  const text = JSON.stringify(validation.ok ? validation.model : next, null, 2) + '\n'
+  const temporary = full + '.tmp'
+  writeFileSync(temporary, text, 'utf8')
+  renameSync(temporary, full)
+  return { model: next, changes, full, valid: validation.ok, errors: validation.ok ? [] : validation.errors }
+}

package/src/engine.ts

@@ -291,7 +291,7 @@ function verificationNextSteps(checks: CheckResult[], coverage: NarrativeCoverag
   // named check looked at the model. A list of failures does not say that, and neither does `pass`.
   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.')
   }
   // Named checks above, bare codes here. That is deliberate: each warning is a different kind of thing,
   // so there is no single name to give the set, and the sentence points at where each one IS explained
@@ -300,6 +300,12 @@ function verificationNextSteps(checks: CheckResult[], coverage: NarrativeCoverag
   if (coverage !== undefined && !narrativeComplete(coverage)) {
     steps.push('Complete the narrative (states ' + coverage.states + ', events ' + coverage.events + ', scenarios ' + coverage.scenarios + ') — a partial narrative is valid, but a reader still has to re-derive the missing symbols.')
   }
+  // A truncated search is the one outcome where "look harder" is the wrong advice: the wall is
+  // combinatorial, and raising maxStates buys a constant factor. Name the ladder instead, so the reader
+  // knows this is not a bug to fix but a model to reduce, or a different tool to use.
+  if (hasUndecidedFinding(checks)) {
+    steps.push('The search stopped before deciding, so the undecided checks are neither proven nor refuted. Do not just raise maxStates: first reduce the model (drop variables the property does not read, collapse symmetric states, order independent events), and if it still explodes, move to a tool that does not enumerate every state - SPIN for partial-order reduction, NuSMV/nuXMV for symbolic search, CBMC for bounded SAT. This plugin establishes no abstraction and reads no program source, so a property that needs one is outside it.')
+  }
   // The range is dropped: the code that would be reported back is already named in `findings`, and a
   // reader who has not seen a report yet learns nothing from four digits.
   steps.push('Re-run with beforeModel/stateMapping after the change to prove the behaviour did not regress: behaviour preserved, invariants continuous, the state mapping consistent. Then compare the two reports with `report_diff` rather than reading them side by side.')
@@ -479,6 +485,7 @@ export const REPORT_SCHEMAS = {
   granularity: 'model-everything/granularity/v1',
   design: 'model-everything/design/v1',
   baseline: 'model-everything/baseline/v1',
+  edit: 'model-everything/edit/v1',
 } as const
 
 export type ReportSchema = typeof REPORT_SCHEMAS[keyof typeof REPORT_SCHEMAS]

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