dsh-model-everything 0.2.0 → 0.4.0

package/src/design-tool.ts

@@ -1,68 +1,76 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from './json-value.js'
-import { REPORT_SCHEMAS } from './engine.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. 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 }) }]
-    },
-  },
-  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
-  },
-})
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { REPORT_SCHEMAS } from './engine.js'
+import { designResultView, reportCallView, reportCard } 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
+    },
+  },
+  presentCall: reportCallView(DESIGN_TOOL_NAME),
+  presentResult: designResultView,
+
+  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
+  },
+})

package/src/edit-tool.ts

@@ -0,0 +1,121 @@
+/**
+ * `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 { editResultView, reportCallView, reportCard } 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
+    },
+  },
+  presentCall: reportCallView(MODEL_EDIT_TOOL_NAME),
+  presentResult: editResultView(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

@@ -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]