dsh-model-everything 0.2.0 → 0.3.0

package/README.en-US.md

@@ -19,117 +19,123 @@ A native DeepSeek Harness plugin. It turns the assertions a design makes **about
 - **Compare a refactor**: a model before and after, with the two reports side by side.
 - **Leave a record**: conclusions fixed into a report with hashes, recomputable and comparable and exportable.
 
+## It costs more; what it returns is a verdict
+
+This is a capability tool, not a token-saving one.
+
+**How much it costs depends on the size of the task, and the direction is the opposite of intuition.** On a
+fixture of a few hundred lines it costs several times the baseline, because the fixed cost - skill body,
+tool definitions - has nothing to amortise against. On an object of tens of thousands of lines across
+hundreds of files the ratio falls back toward parity: we measured 0.93x to 1.11x. **The larger the task,
+the better the trade**: one decision replaces dozens of `read` calls rather than a few lines of code.
+
+What the extra buys:
+
+- a conclusion that can be **recomputed**: hashes, `verdict`, citations, not a paragraph that reads like one;
+- a **counterexample path**: the steps or the event sequence that breaks the claim;
+- a **portable model**: the same conclusion can be handed to UPPAAL, TLA+, PRISM or SPIN for a second opinion.
+
+When it is not worth it: when one reading of the code settles the claim, or three lines of script count
+it out. **It does not buy speed over reading.** It buys the claims that reading cannot decide.
+
+**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, 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.
+
 ## What it covers
 
 | Domain | What it does |
 |---|---|
 | Claim checking | Enumerates the verifiable claims in a design, spec or review comment. Checks each against the code with a citation, and says plainly which ones it could not settle |
-| Behaviour | State machines and protocols: structural checks, adversarial probes, budgets and deadlines, before/after regression. Composition checks catch deadlock and a rendezvous that never fires |
+| Behaviour | State machines and protocols: structural checks, adversarial probes, budgets and deadlines, before/after regression. Composition checks catch deadlock and a rendezvous that never fires. Finite-word automata decide language relations - equivalence, inclusion - and return the shortest witness word |
 | Diagrams | UML 2.5 diagram families: render, parse and modelling review (including the render→parse fidelity check), in Mermaid and PlantUML |
 | Structure | Component, package, class and deployment diagrams audited as dependency graphs: isolated nodes, dangling endpoints, cycles, matrix and layer violations, missing required edges |
 | Data | Data models and migrations: structure, migration coverage, copy consistency, rollback symmetry, before/after data regression |
 | Concurrency / synchrony / async | Mines claims about how work is executed (thread-safe, locks, interrupts, async/await, the event loop) and routes each to a tool that can decide it. It proves nothing itself |
 | Export | Exports a verified model as input for UPPAAL, TLA+, PRISM or SPIN |
-| Reports | Report body rendering, baseline comparison (`report_diff`), hash specification |
+| Reports | Report body rendering, baseline comparison (`report_diff`), hash specification. Every report also carries a summary for a UI - verdict, the first finding, the next step - while the model still gets the full text |
 
 ## Typical uses
 
-### A refactoring harness
-
-A refactor may change the implementation. It may not change the behaviour. Let an engine settle that, instead of reading the diff:
-
-1. **Before**: extract a BEFORE model from the code as it stands (`uml_parse` reads an existing diagram, or write the model against the schema).
-2. **Refactor**.
-3. **After**: extract an AFTER model.
-4. **Regression**: `model_verify` with `beforeModel` and `stateMapping` runs the before/after regression: behaviour preserved, invariants continuous, the state mapping consistent. On the data side, `model_datamodel_verify` runs the same comparison over data, from its `beforeModel`, `fieldMapping` and `migrationMappings`.
-5. **Verdict and record**: `report_diff` compares against the baseline report. An added error finding is the reason not to accept the refactor. The hashes in the report let the conclusion be recomputed.
+Each one says what to hand over, which field to read, and what the tool does not do.
 
-It compares the **two models you give it**, not two versions of the code. Whether each model is faithful to its own source is what steps 1 and 3 are for, and it does not do that part for you. It does not read the diff, edit code or run your tests either. It answers "is the behaviour still the same", not "was this a good refactor".
-
-### Reviewing a code flow
-
-Draw the branching logic as a flow, then read what the picture actually says:
-
-1. **Extract the flow**: write the branches of a function or a service as a `LogicModelV1`, or draw a `stateDiagram-v2` / PlantUML diagram by hand.
-2. **Read it back**: give the hand-drawn diagram to `uml_parse`. A line it cannot read becomes a warning rather than disappearing.
-3. **Review it**: `uml_review` reports the structural defects - unreachable states, dead ends, a branch that is ambiguous or not exhaustive, a self-loop with no exit, isolated nodes, cycles - and the documentation gaps.
-4. **Reconcile with the source**: take every finding back to the code. A correct diagram does not make the code correct.
-
-It reviews the diagram and the model you give it. Whether they match the code is what step 1 is for.
-
-### Reviewing a state machine
-
-Build the machine as an executable model and let an engine run it, instead of reading the code and concluding that it cannot get stuck:
-
-1. **Build the model**: `uml_parse` reads a hand-drawn `stateDiagram-v2` or PlantUML state diagram; a `LogicModelV1` can also be written directly against the schema.
-2. **Run the checks**: `model_verify` looks for unreachable states, absorbing cycles, events silently ignored, an allocation with no recovery path, a budget overrun, and a deadline that cannot be met. It reports each as a code whose prefix says which family it belongs to.
-3. **State the always/never claims**: put them in `invariants`. The engine searches every reachable state for a counterexample and returns the shortest one it finds.
-4. **Reconcile with the source**: every error finding goes back to the code.
-
-Concurrency claims split in two: the ones about **two models touching one shared location** are decided here, by `model_compose_verify` (declare `shared` and `accesses`; C3/C4/C5 decide the declaration, the unordered write and the lost update). Source-level data races, interrupt latency, a blocking call and a missing `await` are still routed to TSan/Helgrind/CBMC/TLA+. Hard real-time semantics - deadlines and periods - are outside its scope.
+### A refactoring harness
 
-### Auditing a dependency diagram
+1. Extract the **BEFORE** model; keep the old schema for the data side.
+2. Refactor.
+3. Extract the **AFTER** model.
+4. `model_verify` with `beforeModel` and `stateMapping`; `model_datamodel_verify` with `fieldMapping` for data.
+5. `report_diff` against the baseline report: **a newly added error is the reason to reject the refactor**.
 
-A component diagram is a claim about which modules may depend on which. Read it as a graph, then ask whether the edges are allowed:
+It compares two models, not two codebases. It reads no diff, changes no code, runs no test.
 
-1. **Give it the drawing**: PlantUML component, package, class or deployment source, or a Mermaid class diagram. `uml_structure_verify` parses it into nodes and edges.
-2. **Say what is allowed**, if you have a rule: a matrix of `layers` and `rules`, each rule naming a `source` with `allow` / `deny` / `require` and a `default` for everything else. Without a matrix it reports only structural defects.
-3. **Read the findings**: an isolated node, an endpoint never declared, a cycle with its shortest path, an edge that crosses a layer, a required edge that is missing, and - when no node is declared at all - that the input said nothing to audit.
-4. **Ask the same question about a code flow**, if the drawing is a state or activity diagram: that is `uml_review`, not this.
+### A state machine or a flow
 
-It audits the drawing, not the code. A drawing that is internally consistent can still be wrong about the system, so pair it with a source-side scan. When a hand-drawn diagram reports label drift, `uml_explain_labels` prints the label forms the parser accepts for that notation.
+1. Hand the diagram to `uml_parse`, or write the model against the schema.
+2. `model_verify` runs the structural checks and the adversarial probes: unreachable states, absorbing cycles, silently ignored events, budgets, deadlines.
+3. Put the always/never claims into `invariants` and get the shortest counterexample path back.
+4. For the drawing alone, `uml_review`: are the branches exhaustive, is there a dead end.
+5. Every error finding goes back to the code; fixing the model is `model_edit`, which returns the structural diff and the change in findings in one call.
 
-### Holding a design to its own declarations
+**A correct drawing is not correct code** - that step belongs to the extraction.
 
-A design says things about itself: this layer sits above that one, this component owns that dependency, this interface is narrower than its callers. `model_design_review` decides whether the design keeps those promises:
+### Auditing a dependency graph
 
-1. **Write the design as a model**: the architecture (nodes and edges), plus what it declares - layers, boundaries, allowed and required edges, types with responsibilities, operations, transitions, supertypes.
-2. **Run it**: `model_design_review` reports the places the design contradicts itself, and separately the shape of its graph - cycles and the fewest edges that break them, load-bearing elements, ranks, fan-in and fan-out.
-3. **Read the three lists**: `violations` decide the verdict; `signals` are worth a look and fail nothing; `facts` is a measurement, not a finding. `checksSkipped` says which principles went unchecked because nothing was declared to hold the design to.
+1. Hand over a diagram, or a `repoPath` and let `uml_structure_verify` build the graph from the source.
+2. Optional matrix: `layers` plus `rules`.
+3. Read the findings: cycle, isolated node, dangling endpoint, layer violation, missing required edge. When the parser reports **label drift**, `uml_explain_labels` prints the spellings that notation accepts.
 
-It never judges a design by an outside standard. It reports that the design contradicted **something it declared**, or a structural fact about its graph. Asking whether the design is *good* is a question for a reviewer, and this tool answers a different one: does it hold together on its own terms.
+**Facts belong here, rules do not**: whether an edge exists is this tool's question; whether it was allowed is `model_design_review`.
 
-### Two machines that have to agree
+### A design held to its own declarations
 
-One machine cannot deadlock *because of another one*. When two components hand-shake, the interesting failures live in the composition:
+1. Write the design and the rules it declares as a `DesignModelV1`.
+2. `model_design_review` reports three lists: `violations` decide the verdict, `signals` are signals, `facts` are measurements.
+3. A check with nothing to hold the design to is `skip`, not `pass`.
 
-1. **Model each machine** on its own, then pass them together: `model_compose_verify` takes an array of models.
-2. **Name the shared events** in `rendezvous` if a handshake is only legal when both sides are ready. An event not named there advances one machine, so a machine waiting on a handshake can take any number of its own steps first.
-3. **Read C1 and C2**: a reachable node where no machine can advance and one of them is not terminal, and a rendezvous that can never fire. Both name the reason per machine, and C1 gives the shortest counterexample.
+It judges no design **by an external standard**. It asks whether the design holds to what it says about itself.
 
-There is no rate ratio and no fairness bound in the model. For one machine on its own - unreachable states, invariants, cost against budget - that is `model_verify`.
+### Two machines that must cooperate
 
-### Concurrency claims, mined and routed
+1. Model each one, hand the array to `model_compose_verify`.
+2. Put the handshakes that need both sides ready into `rendezvous`.
+3. Read C1 (a node no machine can advance from) and C2 (a rendezvous that never fires), each with a per-machine reason and, for C1, the shortest counterexample.
 
-"Thread-safe", "lock-free", "ISR-safe" are claims that need a tool that can settle them, and the first job is finding them:
+A question about one machine alone goes back to `model_verify`. There is no rate ratio and no fairness in a composition.
 
-1. **Scan the text**: `model_interleaving_scan` takes the document, plan or notes and reports the risk points - the claim, the shared state, the interrupt, the critical section, and the async ones (`async`, `await`, `promise`, the event loop, a callback). Every finding carries a `family` (threads / synchronization / async / interrupts / shared-state), and an absolute claim is an error.
-2. **Read what each absolute claim owes**: a claim like "no data race is possible" is reported as an error requiring dedicated verification, and each finding names the analysis that could settle it - TSan or Helgrind for a race, CBMC for a bounded proof, TLA+ for a protocol, RTOS-aware interrupt analysis for an ISR.
-3. **Run that analysis**: this plugin does not run it and proves nothing about concurrency itself.
+### Concurrency claims: mine, then route
 
-It reads text. It does not see your threads, and a clean scan is not a clean bill of health - it means no claim was found, which is a different statement.
+1. `model_interleaving_scan` reads a document and reports absolute claims by `family` (thread-safe, lock-free, ISR-safe ...).
+2. Each one names the analysis that decides it: TSan or Helgrind, CBMC, TLA+, RTOS-aware analysis.
+3. This plugin **runs none of them** and proves nothing about concurrency.
 
-### A migration, before and after
+A clean scan is not a clean bill of health: it says no claim was found.
 
-A migration is two models and a claim that the data survived. Give it both and the claim becomes checkable:
+### A migration: two models, one assertion
 
-1. **Two models**: the schema as it was, and the schema as it will be, each a data model with entities, fields, keys and relationships.
-2. **Say how fields move**: `fieldMapping` from the old path to the new one, plus `migrationMappings` for a field whose source is not simply its own old name.
-3. **Run the comparison**: `model_datamodel_verify` with `beforeModel` checks migration coverage, copy consistency, rollback symmetry and the before/after data regression.
-4. **Read the warning**: a field declared `required` in the new schema with nothing supplying it is reported as `DS2_REQUIRED_FIELD_UNSOURCED`. That is a warning, so the verdict stays `pass_with_findings` - it is a decision to make, not a failure the engine gets to declare.
+1. A data model before and after.
+2. `fieldMapping`; `migrationMappings` for a field whose source is not its own old name.
+3. `model_datamodel_verify` checks migration coverage, copy consistency, rollback symmetry, and the before/after data regression.
+4. `DS2_REQUIRED_FIELD_UNSOURCED` is a **warning**: it is a decision for you, not a failure the engine can announce.
 
-It compares the two models you give it. Whether either is faithful to the database it describes is the extraction step, and this tool does not do it.
+### Language inclusion: two automata
 
-### Importing and exporting diagrams: a frozen record, and a reference for the long run
+1. Write the specification and the implementation as automata: `states`, `alphabet`, `transitions`, `accepting`.
+2. `model_automaton_verify` with `other` and `relation` (`equivalent`, `subset` or `superset`).
+3. When the relation fails you get the **shortest witness word** - accepted by one, rejected by the other, replayable through both.
 
-What is kept here is the **source file**, not a screenshot: `uml_render` writes Mermaid or PlantUML source, and `uml_parse` reads that source back into a model. One diagram therefore serves two purposes:
+Finite words only. Liveness, fairness and timing need a Büchi or timed automaton, which this family does not build.
 
-- **A frozen record of the design**: commit the diagram source, the model and that round's verification report together, as the design as it stood at a point in time. The model may carry `_`-prefixed metadata - a ticket number, a date, an owner, the caveats left by the extraction - and those keys take no part in the hash, so archive notes do not change the identity of a conclusion.
-- **A reference for the long run**: on the next change, extract the model again, run the verification again, and compare with the frozen report through `report_diff`. An added error is what this change introduced; a finding that disappeared is an old problem solved. The hashes decide whether this is still the same model, instead of an eyeball comparison of two pictures.
+### Diagrams as source: freeze and iterate
 
-When an external checker is needed, the same model can be exported with `model_export` as native input for UPPAAL, TLA+, PRISM or SPIN.
+1. `uml_render` writes Mermaid or PlantUML source; `uml_parse` reads it back into a model.
+2. Commit the source, the model and the report of that run together, as the design record at a point in time.
+3. On the next change, re-extract, re-run, and compare with `report_diff`.
+4. For a second opinion, `model_export` writes UPPAAL, TLA+, PRISM or SPIN input.
 
-The limit: it stores and compares **model and diagram source**; a rendered picture is a by-product. A diagram that changed while the model did not - or the reverse - shows up at the next parse or comparison.
+What is kept is the **source file**; a rendered image is a by-product.
 
 ## Tools
 
@@ -144,8 +150,10 @@ The limit: it stores and compares **model and diagram source**; a rendered pictu
 | `model_datamodel_verify` | Data models and migrations |
 | `model_interleaving_scan` | Mines and routes concurrency, synchrony and async claims |
 | `model_export` | Exports to an external checker (UPPAAL, TLA+, PRISM, SPIN) |
-| `uml_structure_verify` | Dependency-graph audit, including a dependency matrix and multi-level refinement |
+| `uml_structure_verify` | Dependency-graph audit, including a dependency matrix and multi-level refinement; give it `repoPath` and it builds the graph from each language's own import construct (C/C++, Python, TypeScript/JavaScript, Go, Rust, Java/Kotlin/Scala, C#, PHP, Ruby, Lua, Zig, Dart, Elixir) |
 | `model_design_review` | Design review: the dependency graph's shape, plus the contracts the design declares about itself - layering, responsibility boundaries, substitutability, interface width |
+| `model_automaton_verify` | Finite-word automata: empty language, trap states, reachability, and the equivalence or inclusion relation against another automaton, with the **shortest witness word** when it fails |
+| `model_edit` | Changes a model file by naming one change (add/remove a state, add/remove/update a transition, pointer set/remove): returns the structural diff and the difference in findings, so edit-verify-compare takes one call |
 | `report_diff` | Compares two reports: what a change added, removed or changed |
 
 `model_verify`, `model_datamodel_verify` and `model_design_review` also take `modelPath`: a JSON file in the workspace, in any formatting (indentation, a BOM and a trailing newline all parse). It is the alternative to an inline `model`; passing both is refused.

package/README.md

@@ -19,117 +19,114 @@ DeepSeek Harness 原生插件。把设计与代码里**关于行为的断言**
 - **对照重构**：重构前后各建一份模型，两份报告摆一起比。
 - **留痕**：结论固化成带哈希的报告，可复算、可比对、可导出。
 
+## 它更贵，但它给的是判定
+
+这是一个**能力型工具，不是省钱工具**。
+
+**贵多少取决于任务大小，而且是反过来的**：几百行的夹具上它贵出数倍——固定成本（技能正文、工具定义）摊不开；对象涨到几万行、上百文件，比例回落到持平附近，我们测到 0.93×–1.11×。**任务越大，这笔钱越值**：一次判定替代的是几十次 `read`，而不是几行代码。
+
+换来的是别的东西：
+
+- 一条**可复算**的结论：哈希、`verdict`、出处，而不是一段读起来像结论的散文；
+- 一条**反例路径**：哪几步、哪个事件序列让断言不成立；
+- 一份**可导出的模型**：同一条结论能交给 UPPAAL、TLA+、PRISM、SPIN 复核。
+
+什么时候不值得：断言能靠通读一次代码、或者写三行脚本数出来的时候。**它买不到比读一遍更快**；它买到的是「读一遍给不出判定」的那类断言。
+
+**它判定的是小模型，不是程序。** 引擎显式枚举状态，模型炸开时会报 `truncated` 并点名未决的检查。那不是重试一个更大的 `maxStates` 就能解决的：先减模型（去掉性质不读的变量、合并对称状态），仍然炸开就换不靠枚举的工具——SPIN 的偏序归约、NuSMV 的符号化、CBMC 的有界 SAT。本插件不建立抽象，也不读程序源码。
+
 ## 能力范围
 
 | 域 | 做什么 |
 |---|---|
 | 事实核验 | 把一份设计/规格/评审意见里的可验证断言列出来，逐条对着代码核验并给出出处。核不了的直接说明 |
-| 行为验证 | 状态机与协议：结构检查、对抗性探测、预算与时限、before/after 回归。多机组合查死锁，以及永不发生的会合（握手事件） |
+| 行为验证 | 状态机与协议：结构检查、对抗性探测、预算与时限、before/after 回归。多机组合查死锁，以及永不发生的会合（握手事件）。有限词自动机判语言关系（等价、包含）并给出最短反例词 |
 | 图 | UML 2.5 各图族的渲染、解析与建模审查（含 render→parse 往返一致性对照），覆盖 Mermaid 与 PlantUML 两种记号 |
 | 结构 | 组件/包/类/部署图按依赖图审计：孤立节点、悬空引用、环、矩阵与分层违规、缺失的必需边 |
 | 数据 | 数据模型与迁移：结构、迁移覆盖、拷贝一致性、回滚对称、前后数据回归 |
 | 并发 / 同步 / 异步 | 挖掘"工作怎么被执行"的断言（线程安全、锁、中断、async/await、事件循环…）并路由到能判定它的工具；它自己不证明 |
 | 导出 | 已验证模型导出为 UPPAAL / TLA+ / PRISM / SPIN 的输入 |
-| 报告 | 报告正文渲染、基线比对（`report_diff`）、哈希规范 |
+| 报告 | 报告正文渲染、基线比对（`report_diff`）、哈希规范。每份报告另带一份给界面用的摘要：verdict、首条问题、下一步，正文照旧给模型 |
 
 ## 典型用法
 
-### 重构 harness
-
-重构可以改实现，不能改行为。这个判断交给引擎，不必通读 diff：
-
-1. **重构前**：从当前代码抽出 BEFORE 模型（`uml_parse` 读已有的图，或按 schema 手写）。
-2. **重构**。
-3. **重构后**：抽出 AFTER 模型。
-4. **回归**：`model_verify` 带 `beforeModel` 与 `stateMapping` 跑前后回归：行为是否保持、不变式是否连续、状态映射是否自洽。数据侧用 `model_datamodel_verify` 的 `beforeModel` / `fieldMapping` / `migrationMappings` 做同一件事的**数据版**。
-5. **判定与留痕**：`report_diff` 拿基线报告比对。新增的 error 发现，就是这次重构不接受的理由。报告里的哈希让结论可复算。
+每个场景都只讲「给什么、看哪个字段、它不管什么」。
 
-它比较的是**你给的两份模型**，不是两份代码。每份模型是否忠实于对应代码，由第 1、3 步负责，它不代替你做。它也不读 diff、不改代码、不跑你的测试。它回答的是"行为还一样吗"，不是"重构得好不好"。
-
-### 代码流程审查
-
-先把分支逻辑画成流程，再看这张图到底说了什么：
-
-1. **抽流程**：把函数或服务里的分支写成 `LogicModelV1`，或者手画一张 `stateDiagram-v2` / PlantUML 图。
-2. **读回模型**：手画的图交给 `uml_parse` 转成模型。读不动的行会变成警告，不会悄悄跳过。
-3. **审查**：`uml_review` 报结构缺陷——不可达状态、死端、分支有歧义或没穷尽、自环没有出口、孤立节点、环——以及文档缺口。
-4. **落回源码**：每条发现都回到代码核验。图画对了，不等于代码写对了。
+### 重构 harness
 
-它审的是你给的那张图和那份模型。图与代码是否一致，由第 1 步的抽取负责。
+1. 重构前抽 **BEFORE** 模型；数据侧留一份旧 schema。
+2. 重构。
+3. 抽 **AFTER** 模型。
+4. `model_verify` 带 `beforeModel` 与 `stateMapping`；数据侧用 `model_datamodel_verify` 的 `fieldMapping`。
+5. `report_diff` 拿基线报告比对：**新增的 error 就是拒绝这次重构的理由**。
 
-### 状态机审查
+它比的是两份模型，不是两份代码；也不读 diff、不改代码、不跑测试。
 
-把状态机建成可执行模型，让引擎去跑，而不是通读代码判断它会不会卡死：
+### 状态机与流程图
 
-1. **建模型**：手画的 `stateDiagram-v2` 或 PlantUML 状态图交给 `uml_parse`；也可以直接按 schema 写 `LogicModelV1`。
-2. **跑检查**：`model_verify` 找的是不可达状态、吸收环、被静默忽略的事件、没有恢复路径的资源申请、预算超限，以及无法满足的时限。每一项都作为一个**带码**的发现报出，而码的前缀说明它属于哪一族。
-3. **写清"永远/绝不"**：把这类断言写进 `invariants`，引擎会在全部可达状态上搜反例，并给出它找到的最短路径。
-4. **落回源码**：报告里的 error 发现逐条回到代码。
+1. 图交给 `uml_parse`，或直接按 schema 写模型。
+2. `model_verify` 跑结构检查与对抗探测：不可达、吸收环、被静默忽略的事件、预算、时限。
+3. 把「永远 / 绝不」写进 `invariants`，拿回最短反例路径。
+4. 只看图本身用 `uml_review`：分支是否穷尽、有没有死端。
+5. 每条 error 回到代码核验；改模型用 `model_edit`，一次调用拿回结构 diff 与发现 diff。
 
-并发断言分两半：**两个模型都碰同一个共享位置**这一类，由我们自己的 `model_compose_verify` 判（声明 `shared` 与 `accesses` 之后的 C3/C4/C5，包括丢更新）；源码级数据竞争、中断延迟、阻塞调用与漏掉的 `await` 仍路由到 TSan/Helgrind/CBMC/TLA+。硬实时语义（deadline、period）不在它的范围内。
+**图画对了不等于代码写对了**——那一步由抽取负责。
 
 ### 审计一张依赖图
 
-组件图是关于「哪些模块可以依赖哪些」的断言。把它当图读，再问那些边是否被允许：
-
-1. **给图**：PlantUML 的组件/包/类/部署图源码，或 Mermaid 类图。`uml_structure_verify` 把它解析成节点与边。
-2. **说清什么被允许**（如果有规则）：一个含 `layers` 与 `rules` 的矩阵，每条规则点名一个 `source` 并给 `allow` / `deny` / `require`，再用 `default` 管其余。没有矩阵时，它只报结构缺陷。
-3. **读发现**：孤立节点、从未声明过的端点、带最短路径的环、越过层的边、缺失的必需边，以及——一个节点都没声明时——**这份输入没有任何可审的东西**。
-4. **换一种图就换个工具**：如果这张图是状态图或活动图，那是 `uml_review`，不是它。
+1. 给图，或给 `repoPath` 让 `uml_structure_verify` 直接从源码建图。
+2. 有规则就给矩阵：`layers` 加 `rules`。
+3. 读发现：环、孤立节点、悬空端点、越层边、缺失的必需边。解析器报**标签漂移**时，`uml_explain_labels` 打印该记号接受的写法。
 
-它审的是**图**，不是代码。一张自洽的图仍可能画错了系统，所以要和源码侧扫描配对。手画的图报「标签漂移」时，`uml_explain_labels` 会打印该记号下解析器接受的标签写法。
+**事实归它，规则不归它**：某条边到底存不存在，问这个工具；该不该允许，是 `model_design_review`。
 
 ### 让设计对自己作出的声明负责
 
-设计会对自己作出断言：这一层在那层之上、这个组件拥有那条依赖、这个接口比它的调用方窄。`model_design_review` 判定设计是否守住了这些承诺：
+1. 把设计与它声明的规则写成 `DesignModelV1`。
+2. `model_design_review` 报三类：`violations` 决定判定，`signals` 只是信号，`facts` 是测量。
+3. 没声明任何可对照的东西时，对应检查是 `skip`，不是 pass。
 
-1. **把设计写成模型**：架构（节点与边），加上它声明的——分层、边界、允许与必需的边、带职责的类型、操作、转移、父类型。
-2. **跑它**：`model_design_review` 报出设计与自相矛盾的地方，并**另外**报出它图的形状——环与打断环所需的最少边、承重元素、层级、扇入扇出。
-3. **读那三个列表**：`violations` 决定判定；`signals` 值得一看但不使任何东西失败；`facts` 是**测量**，不是发现。`checksSkipped` 说明哪些原则因为**没声明任何可对照的东西**而没有检查。
-
-**它从不按外部标准评判设计。** 它报的是：设计**与它自己声明的某件事**矛盾，或关于它的图的一个结构事实。问「这个设计好不好」是评审者的问题；这个工具回答的是另一个：**它就自己的说法而言，站得住吗**。
+它**不按外部标准**评判设计，只问：它就自己的说法而言站得住吗。
 
 ### 两台必须互相配合的机器
 
-一台机器**不会因为另一台**而死锁。当两个组件握手时，真正有意思的失败在**组合**里：
-
-1. **各自建模**，然后一起给：`model_compose_verify` 收一个模型数组。
-2. **点名共享事件**：如果一个握手只有在双方都就绪时才合法，把它写进 `rendezvous`。没写进去的事件只推进一台机器，所以等握手的机器可以先走任意多步自己的路。
-3. **读 C1 与 C2**：一个可达节点上没有任何机器能前进、且有机器不是终止态（C1），以及一个**永远不会触发**的会合（C2）。两者都逐机给出理由，C1 还给最短反例。
+1. 各自建模，一起给 `model_compose_verify`。
+2. 需要双方同时就绪的会合写进 `rendezvous`。
+3. 读 C1 死锁与 C2 永不触发的会合，各自带逐机理由与最短反例。
 
-模型里**没有速率比，也没有公平性约束**。单台机器自己的问题——不可达状态、不变式、成本对预算——用 `model_verify`。
+单台机器自己的问题回 `model_verify`；组合里没有速率比，也没有公平性。
 
 ### 并发声明：挖掘并路由
 
-「线程安全」「lock-free」「ISR 安全」都是需要某个能判定它们的工具的断言，而第一步是**把它们找出来**：
+1. `model_interleaving_scan` 扫文本，按 `family` 报出绝对断言（线程安全、lock-free、ISR 安全…）。
+2. 每条点名能判定它的分析：TSan / Helgrind、CBMC、TLA+、RTOS 感知分析。
+3. 本插件**不运行**那个分析，也不对并发安全作任何证明。
 
-1. **扫文本**：`model_interleaving_scan` 收文档、计划或笔记，报出风险点——那条声明、共享状态、中断、临界区，以及异步的那些（`async`、`await`、`promise`、事件循环、回调）。每条发现都带 `family`（threads / synchronization / async / interrupts / shared-state），绝对式断言按 error 报。
-2. **看每条绝对声明欠着什么**：「不可能有数据竞争」这类声明会被报为 error，要求**专门的**验证，且每条发现都点名能判定它的分析——竞争用 TSan 或 Helgrind，有界证明用 CBMC，协议用 TLA+，中断用 RTOS 感知的分析。
-3. **去做那个分析**：本插件不运行它，也不对并发安全作任何证明。
-
-它读的是**文本**。它看不见你的线程，而**一次干净的扫描不是健康证明**——它的含义是没找到声明，这是另一个命题。
+一次干净的扫描不是健康证明——它的含义只是没找到声明。
 
 ### 一次迁移：前后两份模型
 
-迁移是两份模型，加一个「数据活下来了」的断言。把两份都给出去，这个断言就变成可核查的：
-
-1. **两份模型**：改动前的 schema 与改动后的 schema，各自是含实体、字段、键与关系的数据模型。
-2. **说清字段怎么走**：`fieldMapping` 从旧路径到新路径，加上 `migrationMappings`——用于来源不是它自己旧名字的字段。
-3. **跑比对**：`model_datamodel_verify` 带 `beforeModel`，检查迁移覆盖、拷贝一致性、回滚对称，以及前后数据回归。
-4. **读那条警告**：新 schema 里声明为 `required`、却没有任何东西供给它的字段，会报 `DS2_REQUIRED_FIELD_UNSOURCED`。它是 **warning**，所以判定停在 `pass_with_findings`——**这是一个要做的决定，不是引擎可以替你宣布的失败**。
+1. 前后各一份数据模型。
+2. 给 `fieldMapping`；来源不是自己旧名字的字段用 `migrationMappings`。
+3. `model_datamodel_verify` 查迁移覆盖、拷贝一致性、回滚对称、前后数据回归。
+4. `DS2_REQUIRED_FIELD_UNSOURCED` 是 **warning**：它是要你做的决定，不是引擎能替你宣布的失败。
 
-它比较的是**你给的两份模型**。任一份是否忠实于它所描述的数据库，是抽取那一步的事，这个工具不做。
+### 语言包含：两台自动机
 
-### 图的导入与导出：设计冻结与长期迭代
+1. 把规范与实现各自写成自动机：`states`、`alphabet`、`transitions`、`accepting`。
+2. `model_automaton_verify` 带 `other` 与 `relation`（`equivalent` / `subset` / `superset`）。
+3. 关系不成立时拿走**最短反例词**——一个实现接受、规范拒绝的词，可以直接在两台机器上重放。
 
-这里存的是**源文件**，不是截图：`uml_render` 写出 Mermaid / PlantUML 源，`uml_parse` 把源读回模型。一份图因此能当两种东西用：
+只判有限词。liveness、公平性与时序需要 Büchi 或时间自动机，这个族不做。
 
-- **设计冻结的留档**：把图源、模型和那一次的验证报告一起提交进仓库，作为某个时间点的设计记录。模型里可以放 `_` 前缀的元数据（单据号、日期、负责人、抽取时留下的保留意见），这些键不参与哈希，补档案信息不会改变结论的身份。
-- **长期迭代的参考**：下一次改动时重新抽出模型、重跑验证，再用 `report_diff` 与冻结的那份报告比对。新增的 error 是这次改动引入的，消失的说明旧问题已经解决；哈希让"还是不是同一份模型"可判定，不必肉眼比图。
+### 图的导入与导出：冻结与迭代
 
-需要交给外部检查器时，同一份模型可以用 `model_export` 导出成 UPPAAL / TLA+ / PRISM / SPIN 的原生输入。
+1. `uml_render` 写出 Mermaid / PlantUML 源，`uml_parse` 读回模型。
+2. 图源、模型与那次验证的报告一起提交，作为某个时间点的设计记录。
+3. 下次改动重抽、重跑，用 `report_diff` 与冻结的那份比对。
+4. 要交给外部检查器，用 `model_export` 出 UPPAAL / TLA+ / PRISM / SPIN。
 
-界线：它保存并比对的是**模型与图的源文件**，渲染出来的图片只是副产品。图变了模型没变、或模型变了图没变，都会在下一次解析或比对时暴露。
+它保留的是**源文件**，渲染出的图片只是副产品。
 
 ## 工具
 
@@ -144,8 +141,10 @@ DeepSeek Harness 原生插件。把设计与代码里**关于行为的断言**
 | `model_datamodel_verify` | 数据模型与迁移验证 |
 | `model_interleaving_scan` | 并发 / 同步 / 异步声明的挖掘与路由 |
 | `model_export` | 导出到外部检查器（UPPAAL / TLA+ / PRISM / SPIN） |
-| `uml_structure_verify` | 依赖图审计（含依赖矩阵与多层级细化） |
+| `uml_structure_verify` | 依赖图审计（含依赖矩阵与多层级细化）；也可以直接给 `repoPath`，由工具按语言的 import 构造建图（C/C++、Python、TypeScript/JavaScript、Go、Rust、Java/Kotlin/Scala、C#、PHP、Ruby、Lua、Zig、Dart、Elixir） |
 | `model_design_review` | 设计审阅：依赖图形状 + 设计自身声明的契约（分层、职责边界、可替换性、接口宽度） |
+| `model_automaton_verify` | 有限词自动机：空语言、陷阱状态、可达性，以及与另一台自动机的等价/包含关系；关系不成立时给出**最短反例词** |
+| `model_edit` | 按条改动模型文件（加/删状态、加/删/改迁移、指针 set/remove）：返回结构 diff 与发现 diff，一次调用完成「改—验—比」 |
 | `report_diff` | 两份报告比对：新增/消失/变化的发现 |
 
 `model_verify`、`model_datamodel_verify`、`model_design_review` 另收 `modelPath`：从工作区里的 JSON 文件读模型，缩进、BOM、尾随换行都不影响。它与内联的 `model` 二选一，两个都给会被拒绝。

package/lib/automaton-tool.js

@@ -0,0 +1,69 @@
+/**
+ * `model_automaton_verify`: what language does this machine accept, and is it the one it claims.
+ *
+ * The description is written for the decision. A conformance claim - "the implementation allows every run
+ * the specification allows" - is a language inclusion, and the two machines can be small while the
+ * question is still beyond a reading: the witness is a word nobody thought to try.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { verifyAutomaton } from './automaton.js';
+import { optionRefusal } from './option-shape.js';
+import { renderReportText } from './report-view.js';
+import { reportCard, reportResultView } from './presentation.js';
+export const MODEL_AUTOMATON_TOOL_NAME = 'model_automaton_verify';
+export const modelAutomatonTool = defineTool({
+    name: MODEL_AUTOMATON_TOOL_NAME,
+    description: 'Decide a finite-word automaton: what it accepts, whether it is empty, whether a state is a trap, and whether its language equals, contains or is contained in another automaton. Use it for a conformance claim - the protocol the code implements against the one the specification draws - where the answer is a word that one machine accepts and the other rejects, not an opinion. ' +
+        'Give `other` to compare two automata; `relation` picks equivalent (default), subset (the first is contained in the second) or superset. A failed relation returns the shortest witness word. ' +
+        'Determinism, reachability and trap states are reported whether or not `other` is given. ' +
+        'It decides finite words over an explicit alphabet. Liveness, fairness, timing and infinite words are out of scope: a Büchi or timed model is a different family, and this tool does not build one. For reachability or deadlock in a single state machine use `model_verify`; for machines that must handshake use `model_compose_verify`.',
+    parameters: {
+        automaton: {
+            type: 'json',
+            required: true,
+            description: 'The automaton: {states: [ids], alphabet: [symbols], transitions: [{from, symbol, to}], init, accepting: [ids]}. An NFA is accepted and determinised; nondeterminism is reported.',
+        },
+        other: {
+            type: 'json',
+            description: 'The automaton to compare against, in the same shape. Omit to check this one on its own.',
+        },
+        relation: {
+            type: 'string',
+            enum: ['equivalent', 'subset', 'superset'],
+            description: 'Which language relation `other` must stand in. Default equivalent. subset: the first is contained in the second; superset: the second is contained in the first.',
+        },
+        reportView: {
+            type: 'string',
+            enum: ['digest', 'full'],
+            description: 'digest (default) prints the readable body; full prints the structured result.',
+        },
+    },
+    output: {
+        schema: {
+            type: 'json',
+            description: 'the automaton report: verdict, findings, the witness word when a relation fails, and hashes of the inputs.',
+        },
+        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: a verdict and the first thing wrong,
+        // never the whole report.
+        presentationMeta(_args, value) {
+            return reportCard(value, MODEL_AUTOMATON_TOOL_NAME);
+        },
+    },
+    presentResult: reportResultView(MODEL_AUTOMATON_TOOL_NAME),
+    timeoutMs: 10_000,
+    isConcurrencySafe: () => true,
+    async execute(args) {
+        try {
+            return verifyAutomaton(args.automaton, {
+                ...(args.other === undefined ? {} : { other: args.other }),
+                ...(args.relation === undefined ? {} : { relation: args.relation }),
+            });
+        }
+        catch (error) {
+            return optionRefusal(error, 'AUTOMATON_OPTION_INVALID');
+        }
+    },
+});