dsh-model-everything 0.1.0 → 0.3.0

package/lib/automaton.js

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

package/lib/compose-tool.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { runCompositionVerification } from './engine.js';
+import { reportCard, reportResultView } from './presentation.js';
 import { OptionShapeError, optionRefusal, requireArrayOption } from './option-shape.js';
 import { renderReportText } from './report-view.js';
 export const COMPOSE_TOOL_NAME = 'model_compose_verify';
@@ -33,6 +34,10 @@ export const modelComposeTool = defineTool({
             type: 'integer',
             description: 'Maximum composite states to explore. Default 10000.',
         },
+        check: {
+            type: 'string',
+            description: 'Print one check in full when the digest truncated it. Pass the check id the CHECKS line lists (for example A9); the per-check budget no longer applies, and an id this report does not carry is answered with the ids that it does.',
+        },
         reportView: {
             type: 'string',
             enum: ['digest', 'full'],
@@ -45,9 +50,13 @@ export const modelComposeTool = defineTool({
             description: 'Composition verification report with C1/C2 findings and, when shared locations are declared, C3/C4/C5.',
         },
         render(args, value) {
-            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full', check: args.check }) }];
         },
-    },
+        // The card a UI shows, separated from the text the model reads.
+        presentationMeta(_args, value) {
+            return reportCard(value, COMPOSE_TOOL_NAME);
+        },
+    }, presentResult: reportResultView(COMPOSE_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {

package/lib/concurrency-tool.js

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { runConcurrencyScan } from './concurrency.js';
 import { renderReportText } from './report-view.js';
+import { reportCard, reportResultView } from './presentation.js';
 export const INTERLEAVING_SCAN_TOOL_NAME = 'model_interleaving_scan';
 /**
  * Model-visible DSH tool that mines design documents/plans for concurrency-related
@@ -31,7 +32,11 @@ export const modelConcurrencyScanTool = 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, INTERLEAVING_SCAN_TOOL_NAME);
+        },
+    }, presentResult: reportResultView(INTERLEAVING_SCAN_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {

package/lib/data-engine.js

@@ -1132,7 +1132,7 @@ function dataNextSteps(checks) {
     // check looked at the model. `pass` does not say that, and neither does a list of the failures.
     const skipped = checks.filter((check) => check.status === 'skip').map((check) => check.name + ' (' + check.id + ')');
     if (skipped.length > 0) {
-        steps.push('These examined nothing, so their silence is not a result: ' + skipped.join(', ') + '. Declare what each one would need, or accept that the model is unverified on those points.');
+        steps.push('Not checked: ' + skipped.join(', ') + ' examined nothing — silence there is not a pass. Declare what each needs, or treat the model as unverified on those points.');
     }
     if (warningCodes.length > 0)
         steps.push('Review the warning findings (' + warningCodes.join(', ') + '): a nullable field or a missing index is a decision, not silence.');

package/lib/data-tool.js

@@ -1,7 +1,9 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { runDataVerification, DATA_ENGINE_SCHEMA_VERSION } from './data-engine.js';
+import { oneOf } from './model-file.js';
 import { optionRefusal, requireArrayOption, requireObjectOption } from './option-shape.js';
 import { renderReportText } from './report-view.js';
+import { reportCard, reportResultView } from './presentation.js';
 export const DATAMODEL_VERIFY_TOOL_NAME = 'model_datamodel_verify';
 /**
  * Model-visible DSH tool wrapping the bundled data-model verification engine.
@@ -15,8 +17,11 @@ export const modelDataModelVerifyTool = defineTool({
     parameters: {
         model: {
             type: 'json',
-            required: true,
-            description: 'DataModelV1 data model to verify.',
+            description: 'DataModelV1 data model to verify. Pass this, or modelPath, not both.',
+        },
+        modelPath: {
+            type: 'string',
+            description: 'Path to a JSON file holding the model, instead of inlining it. Formatting does not matter: whitespace, a BOM and pretty printing all parse. Relative paths resolve against the process working directory, which is the session workspace.',
         },
         beforeModel: {
             type: 'json',
@@ -38,6 +43,10 @@ export const modelDataModelVerifyTool = defineTool({
             type: 'json',
             description: 'Optional backup/restore pairs for DA7 rollback symmetry.',
         },
+        check: {
+            type: 'string',
+            description: 'Print one check in full when the digest truncated it. Pass the check id the CHECKS line lists (for example A9); the per-check budget no longer applies, and an id this report does not carry is answered with the ids that it does.',
+        },
         reportView: {
             type: 'string',
             enum: ['digest', 'full'],
@@ -50,9 +59,13 @@ export const modelDataModelVerifyTool = defineTool({
             description: 'model-everything-datamodel verification report with summary and per-check findings.',
         },
         render(args, value) {
-            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
+            return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full', check: args.check }) }];
         },
-    },
+        // The card a UI shows, separated from the text the model reads.
+        presentationMeta(_args, value) {
+            return reportCard(value, DATAMODEL_VERIFY_TOOL_NAME);
+        },
+    }, presentResult: reportResultView(DATAMODEL_VERIFY_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {
@@ -63,7 +76,7 @@ export const modelDataModelVerifyTool = defineTool({
             requireArrayOption(args.copyPairs, 'copyPairs', 'DATA_OPTION_INVALID');
             requireArrayOption(args.migrationMappings, 'migrationMappings', 'DATA_OPTION_INVALID');
             requireArrayOption(args.backupPairs, 'backupPairs', 'DATA_OPTION_INVALID');
-            return runDataVerification(args.model, {
+            return runDataVerification(oneOf(args.model, args.modelPath, 'model', 'modelPath', 'DATA_OPTION_INVALID'), {
                 beforeModel: args.beforeModel,
                 fieldMapping: args.fieldMapping,
                 copyPairs: args.copyPairs,

package/lib/design-tool.js

@@ -1,5 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { REPORT_SCHEMAS } from './engine.js';
+import { reportCard, reportResultView } from './presentation.js';
+import { oneOf } from './model-file.js';
 import { runDesignReview } from './design-engine.js';
 import { renderReportText } from './report-view.js';
 export const DESIGN_TOOL_NAME = 'model_design_review';
@@ -14,13 +16,20 @@ export const DESIGN_TOOL_NAME = 'model_design_review';
  */
 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`.',
+    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',
-            required: true,
             description: 'DesignModelV1: {schemaVersion: 1, architecture: {nodes: [ids], edges: [[from, to]]}, types?: [{name, stereotype, extends?, implements?, operations?, transitions?, forbids?, responsibilities?, dependsOn?, uses?, layer?}], declare?: {layers?, boundaries?, allowedEdges?, requiredEdges?}}. The schema is closed: an unknown key is refused rather than ignored. `types` is what makes the principle checks possible - with no `extends` there is no substitutability to decide, with no `uses` no interface can be called fat, and no `responsibilities` means nothing to compare the dependencies against.',
         },
+        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'],
@@ -33,23 +42,27 @@ export const designTool = defineTool({
             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', text: renderReportText(value, { full: args.reportView === 'full' }) }];
+            return [{ type: 'text', 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);
+        },
+    }, presentResult: reportResultView(DESIGN_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {
-        if (args.model === undefined) {
+        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 to review it against',
+                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`',
+                error: 'design review needs `model` or `modelPath`',
             };
         }
-        return runDesignReview(args.model);
+        return runDesignReview(oneOf(args.model, args.modelPath, 'model', 'modelPath', 'DESIGN_OPTION_INVALID'));
     },
 });

package/lib/edit-tool.js

@@ -0,0 +1,111 @@
+/**
+ * `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 { 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', 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);
+        },
+    }, 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) => (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.']
+                        : [],
+            };
+        }
+        catch (error) {
+            return optionRefusal(error, 'EDIT_OPTION_INVALID');
+        }
+    },
+});