dsh-model-everything 0.2.0 → 0.3.0

package/lib/structure.js

@@ -444,8 +444,9 @@ function requireDiagramText(value) {
 export function reviewStructure(options) {
     // Not `if (options.diagram !== undefined)`: a missing `diagram` reached the parser as `undefined`
     // and threw a read of `split` on it - the same defect, one guard narrower.
-    requireDiagramText(options.diagram);
-    const graph = parseStructure(options.diagram, options.notation ?? 'auto');
+    // A graph built from source arrives already parsed; a caller that passes one has no diagram text to
+    // require, so the text guard belongs to the other branch.
+    const graph = options.graph ?? parseStructure(requireDiagramText(options.diagram), options.notation ?? 'auto');
     const warnings = [...graph.warnings];
     const findings = [];
     const nodes = graph.nodes;
@@ -657,6 +658,25 @@ export function reviewStructure(options) {
             evidence: { missing },
         });
     }
+    // Degree is what a reader asks first and counts worst: which module everything depends on, and which
+    // depends on nothing. Counting it here means the answer is one line in the report rather than a scan of
+    // the graph by hand, which is where a correct graph still produced a wrong answer.
+    const inDegree = new Map();
+    const outDegree = new Map();
+    for (const edge of graph.edges) {
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+        outDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1);
+    }
+    const hubs = [...inDegree.entries()]
+        .filter(([, count]) => count > 0)
+        .sort((a, b) => (b[1] === a[1] ? a[0].localeCompare(b[0]) : b[1] - a[1]))
+        .slice(0, 5)
+        .map(([id, dependents]) => ({ id, dependents }));
+    const leaves = nodes
+        .filter((node) => !node.container && (outDegree.get(node.id) ?? 0) === 0)
+        .map((node) => node.id)
+        .sort()
+        .slice(0, 10);
     const errors = findings.filter((finding) => finding.severity === 'error').length;
     const warningCount = findings.filter((finding) => finding.severity === 'warning').length;
     const summary = {
@@ -672,6 +692,8 @@ export function reviewStructure(options) {
         errors,
         warnings: warningCount,
         rules: rules.length,
+        hubs,
+        leaves,
     };
     const nextSteps = [];
     if (errors > 0)
@@ -689,10 +711,13 @@ export function reviewStructure(options) {
         notation: graph.notation,
         graph,
         ...(options.matrix === undefined ? {} : { edgeVerdicts }),
+        ...(options.scan === undefined ? {} : { scan: options.scan }),
         findings,
         summary,
         hashes: {
-            diagram: createHash('sha256').update(options.diagram).digest('hex'),
+            // A graph built from source has no diagram text to hash; hashing the text would hash the empty
+            // string, and every scan would then carry the same input hash.
+            diagram: createHash('sha256').update(options.graph === undefined ? options.diagram : canonicalJson({ nodes: options.graph.nodes.map((node) => node.id), edges: options.graph.edges.map((edge) => ({ from: edge.from, to: edge.to })) })).digest('hex'),
             ...(options.matrix === undefined ? {} : { matrix: createHash('sha256').update(canonicalJson(options.matrix)).digest('hex') }),
         },
         warnings,

package/lib/tool.js

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { runVerification } from './engine.js';
 import { renderReportText } from './report-view.js';
+import { reportCard, reportResultView } from './presentation.js';
 import { OptionShapeError, optionRefusal, requireObjectOption } from './option-shape.js';
 import { oneOf } from './model-file.js';
 export const MODEL_VERIFY_TOOL_NAME = 'model_verify';
@@ -59,7 +60,12 @@ export const modelVerifyTool = defineTool({
         render(args, value) {
             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, MODEL_VERIFY_TOOL_NAME);
+        },
     },
+    presentResult: reportResultView(MODEL_VERIFY_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {

package/lib/types/automaton-tool.d.ts

@@ -0,0 +1,2 @@
+export declare const MODEL_AUTOMATON_TOOL_NAME = "model_automaton_verify";
+export declare const modelAutomatonTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/automaton.d.ts

@@ -0,0 +1,57 @@
+export interface AutomatonTransition {
+    from: string;
+    symbol: string;
+    to: string;
+}
+export interface Automaton {
+    states: string[];
+    alphabet: string[];
+    transitions: AutomatonTransition[];
+    init: string;
+    accepting: string[];
+}
+export interface AutomatonFinding {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    detail?: string;
+}
+/** Validate the shape, so a refusal says which field is wrong rather than throwing later. */
+export declare function validateAutomaton(input: unknown): {
+    ok: true;
+    automaton: Automaton;
+} | {
+    ok: false;
+    errors: string[];
+};
+export type AutomatonRelation = 'equivalent' | 'subset' | 'superset';
+export interface AutomatonReport {
+    ok: boolean;
+    ran: boolean;
+    verdict: 'pass' | 'pass_with_findings' | 'fail';
+    verdictReason: string;
+    schema: string;
+    automaton: {
+        states: number;
+        transitions: number;
+        alphabet: number;
+        deterministic: boolean;
+    };
+    findings: AutomatonFinding[];
+    /** Set when the relation fails: the shortest word that breaks it. */
+    witness?: {
+        word: string[];
+        reason: string;
+    };
+    /** True when the product search stopped before deciding, so `pass` is not a proof of equality. */
+    truncated?: boolean;
+    hashes: {
+        automaton: string;
+        other?: string;
+    };
+    nextSteps: string[];
+}
+export declare function verifyAutomaton(input: unknown, options?: {
+    other?: unknown;
+    relation?: AutomatonRelation;
+}): AutomatonReport;

package/lib/types/edit-tool.d.ts

@@ -0,0 +1,2 @@
+export declare const MODEL_EDIT_TOOL_NAME = "model_edit";
+export declare const modelEditTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/editor.d.ts

@@ -0,0 +1,46 @@
+type Json = Record<string, unknown>;
+export interface EditOperation {
+    op: string;
+    [key: string]: unknown;
+}
+export interface ModelChange {
+    kind: 'added' | 'removed' | 'updated';
+    what: string;
+    detail: string;
+}
+/** Read the model at `path`; a missing file is a refusal, not an empty model. */
+export declare function readModelFile(path: unknown): {
+    model: Json;
+    full: string;
+};
+/**
+ * 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 declare function normalizeOperation(raw: unknown): EditOperation;
+/** Apply one operation to a model copy, returning the changes it made. */
+export declare function applyOperation(model: Json, operation: EditOperation): ModelChange[];
+/** 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 declare function applyEdits(path: unknown, operations: unknown, options?: {
+    allowInvalid?: boolean;
+}): EditOutcome;
+export {};

package/lib/types/engine.d.ts

@@ -314,6 +314,7 @@ export declare const REPORT_SCHEMAS: {
     readonly granularity: 'model-everything/granularity/v1';
     readonly design: 'model-everything/design/v1';
     readonly baseline: 'model-everything/baseline/v1';
+    readonly edit: 'model-everything/edit/v1';
 };
 export type ReportSchema = typeof REPORT_SCHEMAS[keyof typeof REPORT_SCHEMAS];
 /**

package/lib/types/presentation.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What a UI shows for a report, separated from what the model reads.
+ *
+ * A report is written for a model: it names every check, every finding and the next step, because the
+ * model has to act on all of it. A reader wants four things instead - did it run, what does it decide,
+ * what is the first thing wrong, what to do next - and wants the rest folded away.
+ *
+ * Two host hooks carry that split:
+ *
+ * - `output.presentationMeta` projects a small JSON payload the host persists on the result; a client
+ *   card narrows it without parsing prose.
+ * - `presentResult` returns the card body from that payload, so a UI that supports it shows the summary
+ *   and a UI that does not falls back to the raw text. The model-facing content never changes.
+ *
+ * Both are pure and replayable: they read the persisted value, never the filesystem.
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { ToolResultView } from '@deepseek-ai/dsh-tools';
+/** One finding, as a card needs it: a code to name it and a sentence to read. */
+export interface CardFinding {
+    code: string;
+    severity: string;
+    message: string;
+}
+/** The payload a client card narrows. Small on purpose: a card is a summary, not a second report. */
+export interface ReportCard {
+    verdict?: string;
+    verdictReason?: string;
+    errors: number;
+    warnings: number;
+    checksRun?: number;
+    first: CardFinding | null;
+    /** The one step a reader should take, already a sentence. */
+    next: string | null;
+    /** Which family produced this, so a card can pick an icon and a colour without parsing codes. */
+    family: string;
+    /** What this family owns, and where the case just outside it goes. One table, not a second prose copy. */
+    route?: {
+        owns: string;
+        instead: string;
+    };
+}
+/**
+ * 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 declare function reportCard(value: unknown, family: string): ReportCard;
+/** The card body: four lines, in the order a reader asks the questions. */
+export declare function cardBlocks(card: ReportCard): ContentBlock[];
+/**
+ * `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 declare function reportResultView(family: string): (_args: unknown, result: {
+    content: ContentBlock[];
+    meta?: unknown;
+}) => ToolResultView | undefined;

package/lib/types/routing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 interface Route {
+    /** What this tool decides, in the words its report already uses. */
+    owns: string;
+    /** The case just outside the line, and the tool that owns it. */
+    notFor: {
+        when: string;
+        tool: string;
+    };
+}
+export declare const ROUTES: Record<string, Route>;
+/** The route for a tool, or undefined when the tool has none. */
+export declare function routeFor(tool: string): Route | undefined;
+/** Every tool a route names, for a caller that has to check the table against the registry. */
+export declare function routedTools(): string[];
+/** The tools named as the owner of an adjacent case. */
+export declare function siblingTools(): string[];

package/lib/types/scan.d.ts

@@ -0,0 +1,37 @@
+export interface ScannedEdge {
+    from: string;
+    to: string;
+}
+export interface ScannedGraph {
+    /** Module ids, posix-style and relative to the scanned root. File ids for file languages, directory ids for package languages. */
+    nodes: string[];
+    edges: ScannedEdge[];
+    /** Files read, and files skipped because they are not source. */
+    filesRead: number;
+    /** Relative specifiers that pointed outside the root or at a file that does not exist. */
+    unresolved: string[];
+    /** Bare specifiers seen (a package name), counted once each. */
+    packages: string[];
+    /** Which languages were scanned, and at what granularity. */
+    languages: {
+        language: string;
+        files: number;
+        granularity: 'file' | 'package';
+    }[];
+}
+export type LangGranularity = 'file' | 'package';
+export interface Language {
+    name: string;
+    extensions: string[];
+    granularity: LangGranularity;
+    /** Specifiers this file names, already separated from external ones. */
+    extract(text: string): {
+        local: string[];
+        external: string[];
+    };
+}
+/** Every language this scan understands, by extension. */
+export declare const LANGUAGES: Language[];
+/** Which language a file belongs to, if any. */
+export declare function languageOf(path: string): Language | undefined;
+export declare function scanDependencyGraph(root: unknown): ScannedGraph;

package/lib/types/structure.d.ts

@@ -95,6 +95,13 @@ export interface StructureSummary {
     errors: number;
     warnings: number;
     rules: number;
+    /** The most depended-on nodes, by incoming edges. What a reader asks first and counts worst. */
+    hubs: {
+        id: string;
+        dependents: number;
+    }[];
+    /** Modules nothing depends on (no outgoing edges), capped for the report. */
+    leaves: string[];
 }
 export interface StructureReport {
     /** The tool ran and produced this report; read `verdict` for the outcome. */
@@ -142,6 +149,15 @@ export declare function shortestCycle(nodes: string[], edges: StructureEdge[]):
 export interface StructureReviewOptions {
     /** Diagram text to review. */
     diagram: string;
+    /** A graph built from source, instead of parsed from a diagram. `diagram` is then ignored. */
+    graph?: StructureGraph;
+    /** How the graph was produced, when it came from a scan rather than a drawing. */
+    scan?: {
+        files: number;
+        unresolved: number;
+        packages: number;
+        languages: string[];
+    };
     notation?: 'auto' | StructureNotation;
     /** Dependency matrix: allowed/denied edges, layers, required edges. */
     matrix?: unknown;

package/lib/uml-tool.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, valueHash, refusalVerdict, verdictOf, verdictOfFindings } from './engine.js';
 import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, checkUmlIntent, UmlError, UML_DIAGRAMS, } from './uml.js';
 import { renderReportText } from './report-view.js';
+import { reportCard, reportResultView } from './presentation.js';
 /**
  * The UML front end as four tools, one per job.
  *
@@ -41,13 +42,18 @@ const intentParameter = {
     enum: ['present', 'verify', 'fidelity'],
     description: 'What the artifact is for, declared up front: present = a human will read it; verify = it must be readable as a model by the verification engine; fidelity = the render-and-reparse proof is the point. A view that cannot serve the declared intent is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes.',
 };
-const reportOutput = {
+const reportOutput = (family) => ({
     schema: { type: 'json', description: 'The result: diagram source, a family model, or a modelling review report with findings, round-trip fidelity and next steps.' },
     render(args, value) {
         // A rendered diagram is source text: the body prints it verbatim, once.
         return [{ type: 'text', text: renderReportText(value, { full: args.reportView === 'full' }) }];
     },
-};
+    // The card a UI shows, separated from the text the model reads. The family is the tool's own name, so
+    // one shared output does not have to guess which tool is calling it.
+    presentationMeta(_args, value) {
+        return reportCard(value, family);
+    },
+});
 /** Draw a model as diagram source. */
 export const umlRenderTool = defineTool({
     name: UML_RENDER_TOOL_NAME,
@@ -60,7 +66,8 @@ export const umlRenderTool = defineTool({
         intent: intentParameter,
         reportView: reportViewParameter,
     },
-    output: reportOutput,
+    output: reportOutput(UML_RENDER_TOOL_NAME),
+    presentResult: reportResultView(UML_RENDER_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {
@@ -97,7 +104,8 @@ export const umlParseTool = defineTool({
         intent: intentParameter,
         reportView: reportViewParameter,
     },
-    output: reportOutput,
+    output: reportOutput(UML_PARSE_TOOL_NAME),
+    presentResult: reportResultView(UML_PARSE_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {
@@ -148,7 +156,8 @@ export const umlReviewTool = defineTool({
         intent: intentParameter,
         reportView: reportViewParameter,
     },
-    output: reportOutput,
+    output: reportOutput(UML_REVIEW_TOOL_NAME),
+    presentResult: reportResultView(UML_REVIEW_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {
@@ -179,7 +188,8 @@ export const umlExplainLabelsTool = defineTool({
         notation: notationParameter,
         reportView: reportViewParameter,
     },
-    output: reportOutput,
+    output: reportOutput(UML_LABELS_TOOL_NAME),
+    presentResult: reportResultView(UML_LABELS_TOOL_NAME),
     timeoutMs: 10_000,
     isConcurrencySafe: () => true,
     async execute(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-model-everything",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Modeling abstraction and automated review for designs and code, including a refactoring harness: UML diagrams, executable verification of machines and protocols with before/after regression, data-model and migration checks, concurrency claim routing, export to external checkers, dependency-graph review, and report diffing. Native plugin for DeepSeek Harness (dsh).",
   "type": "module",
   "main": "lib/index.js",
@@ -64,8 +64,9 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint:md": "markdownlint --dot --ignore \"**/node_modules/**\" .",
     "bump": "node scripts/bump-version.mjs",
-    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/design-engine/run.mjs && node tests/catalog/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/uml/run.mjs && node tests/apply-smoke.mjs && node tests/memory/run.mjs && node tests/skills/run.mjs && node tests/gate/run.mjs && node tests/skill-routing/run.mjs && node tests/toolset/run.mjs && node tests/principles/run.mjs && node tests/feature-checklist/run.mjs && node tests/usage/run.mjs && node tests/translation/run.mjs && node tests/documentation/run.mjs && node tests/contributing/run.mjs && node tests/routing-map/run.mjs && node tests/report-reading/run.mjs && node tests/structure/run.mjs && node tests/baseline/run.mjs && node tests/granularity/run.mjs && node tests/exporters/run.mjs && node tests/report-view/run.mjs && node tests/contracts/run.mjs && node tests/tool-boundary/run.mjs && node tests/negatives/run.mjs && node tests/external/run.mjs",
-    "test:full": "npm run build && node tests/full-suite.mjs"
+    "test:engine": "npm run build && node tests/engine/run.mjs && node tests/design-engine/run.mjs && node tests/catalog/run.mjs && node tests/data-engine/run.mjs && node tests/concurrency/run.mjs && node tests/uml/run.mjs && node tests/apply-smoke.mjs && node tests/memory/run.mjs && node tests/skills/run.mjs && node tests/gate/run.mjs && node tests/skill-routing/run.mjs && node tests/toolset/run.mjs && node tests/principles/run.mjs && node tests/feature-checklist/run.mjs && node tests/usage/run.mjs && node tests/translation/run.mjs && node tests/documentation/run.mjs && node tests/contributing/run.mjs && node tests/routing-map/run.mjs && node tests/report-reading/run.mjs && node tests/structure/run.mjs && node tests/automaton/run.mjs && node tests/presentation/run.mjs && node tests/routing/run.mjs && node tests/tool-routing/run.mjs && node tests/tools/run.mjs && node tests/baseline/run.mjs && node tests/granularity/run.mjs && node tests/exporters/run.mjs && node tests/report-view/run.mjs && node tests/contracts/run.mjs && node tests/tool-boundary/run.mjs && node tests/negatives/run.mjs && node tests/external/run.mjs",
+    "test:full": "npm run build && node tests/full-suite.mjs",
+    "check": "npm run lint:md && npm run test:engine"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",

package/skills/model-everything/SKILL.md

@@ -9,7 +9,11 @@ For an unverified design, failure is only a matter of time. Complex code becomes
 
 ## When This Skill Applies
 
-**This is the entry point.** Load this skill whenever you need to check whether something about the code is true, however small the claim looks. It owns the doctrine: enumerate the claims, verify each against the code, cite `file:line`, read `verdict`. It also owns the executable verification for behaviour. A neighbouring domain goes to its own skill through the routing table below.
+**This is the entry point.** Load this skill when a claim about the code has to be settled and a reading will not settle it. It owns the doctrine: enumerate the claims, verify each against the code, cite `file:line`, read `verdict`. It also owns the executable verification for behaviour. A neighbouring domain goes to its own skill through the routing table below.
+
+**It decides small models, not programs.** The engine enumerates states, so a model that explodes is reported `truncated` with the undecided check named. That is not a bug to retry with a larger `maxStates`: reduce the model first (drop variables the property does not read, collapse symmetric states), and if it still explodes the property needs a tool that does not enumerate - SPIN for partial-order reduction, NuSMV for symbolic search, CBMC for bounded SAT. This plugin builds no abstraction and reads no program source.
+
+**This costs more than reading, and less the larger the task.** On a fixture of a few hundred lines it costs several times a plain reading, because the fixed cost has nothing to amortise against. On a tree of tens of thousands of lines the ratio falls to roughly parity. Spend it where the object is large enough for one decision to replace many reads. Reach for it when the claim is about all paths rather than one, when nothing in the repository will go red if it is false, or when the verdict has to be reproducible later. A claim one reading settles belongs in a sentence, not in a model.
 
 | The task involves… | What it does |
 |---|---|
@@ -180,7 +184,7 @@ not a bound on the search.
 
 ### Native dsh Tools
 
-Twelve tools: `model_verify`, `model_compose_verify`, `model_datamodel_verify`, `model_design_review`, `model_interleaving_scan`, `model_export`, `report_diff`, `uml_render`, `uml_parse`, `uml_review`, `uml_explain_labels`, `uml_structure_verify`. Each tool's description states what it decides and what it does not. Read the description before calling it, and read the report's `verdict` afterwards.
+The tools are `model_verify`, `model_edit`, `model_compose_verify`, `model_datamodel_verify`, `model_design_review`, `model_interleaving_scan`, `model_export`, `report_diff`, `uml_render`, `uml_parse`, `uml_review`, `uml_explain_labels`, `uml_structure_verify` and `model_automaton_verify`. `model_automaton_verify` decides a finite-word language and its relation to another automaton, returning the shortest word that separates them; `references/automata.md` states what each of its checks decides, on what authority, and where it stops. `model_edit` changes a model file by naming the change and returns the structural diff plus the difference in findings, so a fix round costs one call instead of three. `uml_structure_verify` builds its graph from a source tree when given `repoPath`, reading each language's own import construct, so a dependency question about code does not start with drawing. Each tool's description states what it decides and what it does not. Read the description before calling it, and read the report's `verdict` afterwards.
 
 A model is the largest argument these tools take. When it is long, or you have edited it more than once, write it to a file and pass `modelPath` instead of inlining it: a streamed argument that long is where invalid JSON comes from, and the file accepts any formatting.
 

package/skills/model-everything/references/automata.md

@@ -0,0 +1,102 @@
+# Automata as a verification target
+
+What `model_automaton_verify` decides, why each decision is a theorem rather than a heuristic, and where
+the boundary sits. Read it when a report has to be defended, or when a question lands on the edge:
+liveness, infinite words, or a product that will not finish.
+
+## Scope
+
+Finite words over an explicit alphabet. A run starts at `init`, reads one symbol per transition, and is
+accepted if it ends in `accepting`.
+
+Not in scope, and the report says so:
+
+- liveness, fairness, "eventually" properties on an infinite run;
+- timing, clocks, deadlines;
+- conformance by observation rather than by language;
+- any abstraction. The tool reads a model, never program source.
+
+## What each check decides, and on what authority
+
+| Check | Decision | Authority |
+|---|---|---|
+| `AUT003` nondeterminism | whether some state has two transitions on one symbol | the definition of a deterministic automaton |
+| `AUT001` unreachable | whether a state is reachable from `init` | reachability is decidable in linear space |
+| `AUT002` trap | whether a reachable state can still reach acceptance | the same reachability, run backwards |
+| `AUT004` empty language | whether any accepting state is reachable | emptiness of a finite automaton is decidable |
+| `AUT005` alphabet mismatch | whether the two machines can be compared at all | a language relation needs one alphabet |
+| `AUT006` equivalence | whether two machines accept the same words | decide `L(A) \ L(B)` and `L(B) \ L(A)` |
+| `AUT007` subset | whether every word of the first is a word of the second | decide `L(A) \ L(B)` |
+| `AUT008` superset | the same, with the sides exchanged | decide `L(B) \ L(A)` |
+| `AUT009` undecided | the product search stopped at its cap | a stopped search proves nothing |
+
+Equivalence and inclusion are decided by exploring the product of the two automata and asking whether an
+accepting side pairs with a rejecting one. A breadth-first walk returns the **shortest** word that does,
+so the witness is the smallest counterexample there is, not merely one that exists.
+
+## The wall, stated plainly
+
+These are decidable problems, not approximations: automaton equivalence is NL-complete, inclusion for
+nondeterministic machines and LTL model checking are PSPACE-complete. The cost is what grows, not the
+certainty. Two machines of `n` states each can produce `n × n` pairs, and a model with counters or
+queues in it can be unbounded before anyone writes a single transition.
+
+So a cap is honest and a larger cap is not a strategy. When the product stops, the report carries
+`AUT009_UNDECIDED` and sets `truncated: true`: the verdict is "not known", never "equal". If the same
+happens to a state machine in `model_verify`, the report names the escalation instead of suggesting a
+bigger budget.
+
+## Reading, by what each one settles
+
+Foundations, for the constructions above:
+
+- Hopcroft, Motwani, Ullman, *Introduction to Automata Theory, Languages, and Computation* — subset
+  construction, product automata, the equivalence test.
+- Sipser, *Introduction to the Theory of Computation* — closure properties and decidability, in the
+  gentler telling.
+
+Model checking, which is where liveness lives and this family stops:
+
+- Baier and Katoen, *Principles of Model Checking* — LTL, CTL, Büchi automata, fairness. The boundary in
+  the scope section above is this book's first half.
+- Clarke, Grumberg, Peled, *Model Checking* — the classical account, including why explicit enumeration
+  runs out.
+
+The automata-theoretic framing this tool is a finite-word shadow of:
+
+- Kurshan, *Computer-Aided Verification of Coordinating Processes* — systems as automata, properties as
+  automata, language inclusion as the decision procedure.
+- Vardi and Wolper, *An automata-theoretic approach to automatic program verification* — the same idea
+  for LTL, with Büchi acceptance.
+
+Conformance, for what "implementation matches specification" means when it is made precise:
+
+- Tretmans, *Model Based Testing with Labelled Transition Systems* — `ioco` and the family of
+  implementation relations; `subset` and `superset` are the language-level versions of that choice.
+- Lynch and Vaandrager, *Forward and backward simulations* — refinement in two directions, which is
+  exactly the difference between asking `subset` and asking `superset`.
+
+## What a pass does not mean
+
+A passing report says the stated words are accepted or rejected as claimed. It does not say the model is
+the system: the alphabet is whatever the modeller wrote, and a property that needs a symbol nobody
+declared cannot be seen. State the alphabet next to the claim, or the verdict is about a machine that
+exists only in the report.
+
+## Provenance
+
+Which parts are borrowed, and which are this repository's own decisions. A check that came from a
+textbook is cited so a reader can check the argument; a choice that is not in any book is marked as one.
+
+| Part | Where it comes from |
+|---|---|
+| subset construction for determinisation | Hopcroft, Motwani and Ullman |
+| deciding equivalence and inclusion on the product | Hopcroft, Motwani and Ullman; Kurshan for the framing |
+| the shortest-witness search | breadth-first search on the product; the choice to return the shortest word is this repository's |
+| the check codes and their grouping | this repository's convention, shared with the other families |
+| `truncated` and the `_UNDECIDED` suffix | this repository's convention: a stopped search is not a pass |
+| the cap on the product | this repository's decision, and a practical one, not a theoretical boundary |
+| `subset` and `superset` as the two refinements | Tretmans; Lynch and Vaandrager |
+
+The theory above decides the checks. Nothing in this family is a heuristic dressed as a decision: every
+code either proves a property or says it could not.