dsh-model-everything 0.2.0 → 0.3.0

package/lib/editor.js

@@ -0,0 +1,293 @@
+/**
+ * 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';
+const CLONE = (value) => JSON.parse(JSON.stringify(value));
+/** Read the model at `path`; a missing file is a refusal, not an empty model. */
+export function readModelFile(path) {
+    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;
+    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;
+    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, full };
+}
+function statesOf(model) {
+    return Array.isArray(model.states) ? model.states : [];
+}
+function transitionsOf(model) {
+    return Array.isArray(model.transitions) ? model.transitions : [];
+}
+function requireString(value, name) {
+    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) {
+    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, parts, create) {
+    let node = model;
+    for (const part of parts.slice(0, -1)) {
+        const next = node[part];
+        if (next === undefined) {
+            if (!create)
+                throw new OptionShapeError('EDIT_OPTION_INVALID', `path does not exist at "${part}".`);
+            const created = {};
+            node[part] = created;
+            node = created;
+        }
+        else if (next !== null && typeof next === 'object') {
+            node = next;
+        }
+        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) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new OptionShapeError('EDIT_OPTION_INVALID', 'every op must be an object.');
+    }
+    const value = raw;
+    if (typeof value.op === 'string')
+        return value;
+    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) {
+            const { path, value } = argument;
+            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, operation) {
+    const op = requireString(operation.op, 'op');
+    const changes = [];
+    if (op === 'addState') {
+        const state = operation.state;
+        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;
+        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;
+        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.`);
+}
+export function applyEdits(path, operations, options = {}) {
+    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);
+    const changes = [];
+    const normalized = operations.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.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);
+        for (const [index, raw] of operations.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[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/lib/engine.js

@@ -62,6 +62,12 @@ function verificationNextSteps(checks, coverage) {
     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.');
@@ -181,6 +187,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',
 };
 export function narrativeCoverageOf(model) {
     const narrative = model.narrative;

package/lib/export-tool.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, validateModel, verdictOf } from './engine.js';
+import { reportCard, reportResultView } from './presentation.js';
 import { ExportError, exportModel } 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). */
@@ -44,7 +45,11 @@ export const modelExportTool = defineTool({
         render(args, value) {
             return [{ type: 'text', 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);
+        },
+    }, presentResult: reportResultView(EXPORT_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {

package/lib/index.js

@@ -33,6 +33,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
 // `{ kind: 'plugin', plugin }` wrapper: native admission rejects it in every
@@ -192,6 +194,8 @@ export function apply(ctx, config) {
             ctx.effect(() => tools.register(umlStructureTool), 'dsh-model-everything: structure tool');
             ctx.effect(() => tools.register(designTool), 'dsh-model-everything: design review tool');
             ctx.effect(() => tools.register(reportDiffTool), 'dsh-model-everything: report diff tool');
+            ctx.effect(() => tools.register(modelEditTool), 'dsh-model-everything: model edit tool');
+            ctx.effect(() => tools.register(modelAutomatonTool), 'dsh-model-everything: automaton tool');
             toolRegistered = true;
             dataToolRegistered = true;
             concurrencyToolRegistered = true;

package/lib/presentation.js

@@ -0,0 +1,81 @@
+import { routeFor } from './routing.js';
+const SHORT = 160;
+function shorten(text, limit = SHORT) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length <= limit ? flat : flat.slice(0, limit - 1).trimEnd() + '…';
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function array(value) {
+    return Array.isArray(value) ? value : [];
+}
+/**
+ * Project a report into the card payload.
+ *
+ * Read defensively: this runs on replay too, and a payload that once had a shape may come back with a
+ * field missing. A card that throws would take the whole session view with it.
+ */
+export function reportCard(value, family) {
+    const report = record(value) ?? {};
+    const findings = array(report.findings)
+        .map((entry) => record(entry))
+        .filter((entry) => entry !== undefined);
+    const severity = (entry) => String(entry.severity ?? 'info');
+    const errors = findings.filter((entry) => severity(entry) === 'error');
+    const warnings = findings.filter((entry) => severity(entry) === 'warning');
+    const summary = record(report.summary);
+    const checksRun = typeof summary?.checksRun === 'number'
+        ? summary.checksRun
+        : array(report.checks).length > 0
+            ? array(report.checks).length
+            : undefined;
+    const first = errors[0] ?? warnings[0];
+    const next = array(report.nextSteps).map((step) => String(step))[0];
+    return {
+        ...(typeof report.verdict === 'string' ? { verdict: report.verdict } : {}),
+        ...(typeof report.verdictReason === 'string' ? { verdictReason: shorten(report.verdictReason) } : {}),
+        errors: errors.length,
+        warnings: warnings.length,
+        ...(checksRun === undefined ? {} : { checksRun }),
+        first: first === undefined
+            ? null
+            : { code: String(first.code ?? 'UNKNOWN'), severity: severity(first), message: shorten(String(first.message ?? '')) },
+        next: next === undefined ? null : shorten(next),
+        family,
+        ...(routeFor(family) === undefined
+            ? {}
+            : { route: { owns: routeFor(family)?.owns ?? '', instead: routeFor(family)?.notFor.tool ?? '' } }),
+    };
+}
+/** The card body: four lines, in the order a reader asks the questions. */
+export function cardBlocks(card) {
+    const lines = [];
+    const head = card.verdict === undefined ? card.family : card.verdict.toUpperCase();
+    const counts = card.checksRun === undefined
+        ? `${String(card.errors)} error(s), ${String(card.warnings)} warning(s)`
+        : `${String(card.checksRun)} checks · ${String(card.errors)} error(s) · ${String(card.warnings)} warning(s)`;
+    lines.push(head + '  —  ' + counts);
+    if (card.verdictReason !== undefined)
+        lines.push(card.verdictReason);
+    if (card.first !== null) {
+        lines.push((card.first.severity === 'error' ? '✗ ' : '⚠ ') + card.first.code + ': ' + card.first.message);
+    }
+    if (card.next !== null)
+        lines.push('next: ' + card.next);
+    return [{ type: 'text', text: lines.join('\n') }];
+}
+/**
+ * `presentResult` for a report tool: render the card from the persisted payload, and fall back to the
+ * raw content by returning undefined when there is none.
+ */
+export function reportResultView(family) {
+    return (_args, result) => {
+        const card = record(result.meta);
+        if (card === undefined || card === null)
+            return undefined;
+        if (card.verdict === undefined && card.next === null && card.first === null)
+            return undefined;
+        return { card: 'generic', title: family + '  ' + (card.verdict ?? ''), content: cardBlocks(card) };
+    };
+}

package/lib/report-diff-tool.js

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

package/lib/report-view.js

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

package/lib/routing.js

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