dsh-logicprobe 0.7.1 → 0.8.1

package/skills/logicprobe/references/uml-modeling-guide.md

@@ -0,0 +1,166 @@
+# UML Modelling Guide
+
+This guide covers two jobs: drawing a code flow as UML, and reviewing that drawing. Load it when the task is "show me the flow" rather than "check this claim". Typical cases are reverse-engineering a handler, documenting a protocol, or auditing a diagram somebody else drew.
+
+One rule runs through the whole guide. **A diagram is a model, and a model can be wrong.** A tidy flow chart is not evidence about the code. Worse, a diagram that disagrees with the model it came from will mislead every reader who trusts it.
+
+## When to use this
+
+| Situation | View that answers it |
+|---|---|
+| "What are the states of this handler, and what moves between them?" | State machine |
+| "What does this function actually do, including its error paths?" | Activity (flow) |
+| "In what order do these messages arrive, and what is the state after each?" | Sequence |
+| "Somebody gave me a diagram. Is it right?" | Any view. Feed it to the review and compare it against the code. |
+| "This diagram and this model disagree." | Feed both to the review. The round-trip check names every difference. |
+
+Do not use this guide for a behavioural claim about a specific machine. That is the job of `logicprobe_verify` (S1-S8 and A1-A14). The review here covers the modelling, not the behaviour. Every finding it produces names the engine check that settles the behavioural half.
+
+## The three views
+
+One machine, three projections. They are not interchangeable. The review reports which view it saw, and the differences matter.
+
+**State machine** (`stateDiagram-v2`, or a PlantUML state diagram). This view shows the whole topology: every state, every event-and-guard branch, and every terminal state as `--> [*]`. Model code flow into this view, and use it for review. It is the only view that round-trips without loss.
+
+**Activity** (`flowchart TD` in Mermaid). This view draws the same machine as work rather than as states. Each edge carries `event [guard] / actions`. It suits a reader who thinks in steps. It holds the same information as the state view. PlantUML activity is **not** generated: its structured-flowchart syntax needs a while/if reconstruction for any graph with a merge or a cycle. A diagram that quietly reshapes the machine is exactly the failure this feature exists to prevent, so the tool refuses that combination.
+
+**Sequence** (`sequenceDiagram`). This view shows one BFS trace: the messages in the order a walker meets them, with a note per state change. A trace is not a machine. Branches appear as separate guarded messages, paths the walk never took are absent, and the trace is capped. Use it to show a protocol exchange to a human. It cannot be the review's fidelity input, because `parse` refuses it and `review` reports the check as inapplicable (`UML019`).
+
+## Modelling a code flow from source
+
+Extraction follows the same discipline as `logic-verification-guide.md`, applied to code instead of a plan.
+
+1. **Fix the boundary.** Decide which function, task, or module is the machine. In scope: state the code holds across calls, such as statics, fields, enums, and task state variables. Out of scope: the call stack inside one invocation, hardware behaviour, and scheduler preemption.
+2. **Name the states from the code.** A state exists if something survives a call boundary and is tested later. An enum, a `state` field, or a task-local variable that gates the next entry all qualify. A local variable inside one function does not.
+3. **Name the events from the code.** Every edge must trace to a call site, a message, a timer expiry, or an ISR. An edge with no call site is a guess. Put it in the review findings instead of the model.
+4. **Record guards and actions verbatim.** A guard must be the real condition, with the real variable and the real constant. A retry limit of 3 modelled as "a few" is a model of your assumption, not of the code.
+5. **Mark the terminals.** An absorbing state is `terminal: true`. Examples are power-off, fatal, and done. If nothing is terminal, say so. The review will flag it either way.
+6. **Write the narrative as you go.** The `narrative` block holds natural-language meanings for states and events, plus a scenario for each state-and-event pair. It is what lets a reader check the diagram against the code without re-deriving every symbol. Once the block is present, the schema requires all three parts and full coverage, so it cannot rot half-way.
+
+### Evidence rule
+
+Every state, event, guard and action needs a citation. Use `file:line` for code and a section reference for a document. A UML model without citations is a drawing. It cannot be reviewed, only admired. Present the citations together with the model.
+
+### Confirming the model
+
+The usual gate applies: show the extracted transition table or the diagram, and get confirmation before treating the model as fact. In `logicprobe interaction=auto`, skip the question. Instead, cite evidence for every element, round-trip the model (render, parse, compare), and mark the result `UNCONFIRMED`.
+
+## Rendering
+
+In DSH:
+
+```json
+{ "action": "render", "model": { "...LogicModelV1..." }, "notation": "mermaid", "kind": "state" }
+```
+
+`logicprobe_uml` with `action=render` returns the diagram source plus `warnings`. Read those warnings. They list every construct the notation could not carry verbatim: a state id that needed an alias, a label containing `[` or `/`, a trace that was capped.
+
+Without the DSH tool, run the standalone engine:
+
+```bash
+python skills/logicprobe/references/logicprobe-engine.py uml-render model.json --notation mermaid --diagram state
+```
+
+You can also write the diagram by hand. The generator is a convenience, not a requirement. A hand-written diagram is parsed and reviewed exactly like a generated one.
+
+### Directives in generated diagrams
+
+Generated text carries comment lines. Mermaid and PlantUML ignore them. The parser reads them:
+
+```text
+%%logicprobe:uml v1 notation=mermaid diagram=state
+%%logicprobe:init INIT
+%%logicprobe:terminal FATAL
+%%logicprobe:alias S_1 1st state
+%%logicprobe:variable retry integer
+```
+
+These lines exist because the notation cannot express everything the model knows. `[*]` marks an initial state, but a flowchart has no such marker. A state id may contain characters the notation cannot spell. A boolean assignment (`armed := 1`) looks exactly like an integer one. Pinning those facts in comments is what makes the round-trip check exact instead of approximate. PlantUML uses `'` instead of `%%`.
+
+A hand-written diagram needs none of these directives. Adding `%%logicprobe:init` and `%%logicprobe:terminal` to a flowchart is how you say which node starts and which one ends.
+
+## Reviewing the modelling
+
+```json
+{ "action": "review", "model": { "...LogicModelV1..." } }
+```
+
+Four input shapes, four different questions:
+
+| Input | Question answered |
+|---|---|
+| `model` only | Is this machine well-modelled? The review checks its structure, then renders and re-parses it to prove the diagram carries it. |
+| `diagram` only | What does this diagram actually say? The diagram is parsed into a model, and that model is reviewed. Fidelity to code is **unchecked** (`UML018`). |
+| `model` + `diagram` | Does the diagram match the model? Every structural difference is a modelling defect (`UML017`). |
+| `model` + `kind: "sequence"` | The trace is rendered and the structure is reviewed, but the fidelity check **does not apply** (`UML019`). A trace cannot be parsed back into a machine, so the review says so instead of pretending it verified the diagram. `maxSteps` caps the trace. |
+
+### Findings
+
+| Code | Severity | What it means |
+|---|---|---|
+| `UML001_DIAGRAM_UNREADABLE` | error | The text is not readable as a Mermaid or PlantUML state or activity diagram. |
+| `UML002_UNREACHABLE_STATE` | error | No transition can enter this state from init. The diagram draws flow nobody can reach. The check is structural and ignores guards; S1 is the guard-aware check. |
+| `UML003_DEAD_END_STATE` | error | A non-terminal state has no outgoing transition. Either it is terminal, or the outgoing flow was never modelled. |
+| `UML004_AMBIGUOUS_BRANCH` | error | Two unconditional arrows share one state and event. No reader and no implementation can resolve that. S4 is the authoritative check. |
+| `UML005_OVERLAPPING_GUARD` | warning | The same guard text appears twice in one branch group. |
+| `UML006_INEXHAUSTIVE_BRANCH` | warning or info | The branch group has only guarded branches and no default. The severity is `warning` when the guards do not look complementary. It is `info` when a complementary pair such as `k < 3` and `k >= 3` is present, which is probably exhaustive. Only S6 can settle it. |
+| `UML007_UNUSED_EVENT` | warning | The event fires only from unreachable states. The diagram shows messages that never arrive. |
+| `UML008_SELF_LOOP_NO_EXIT` | warning | An unguarded self-loop has no other exit. The diagram presents it as progress, but the flow never leaves. S3 reports absorbing cycles. |
+| `UML009_DUPLICATE_TRANSITION` | warning | The same from, event, guard, actions and target row appears twice. |
+| `UML010_UNUSED_VARIABLE` | warning | No guard reads this variable and no action writes it. It is a symbol with no source. |
+| `UML011_UNBOUNDED_VARIABLE` | info | An integer variable has no min or max, so no range invariant can be checked and A5 has no declared domain. |
+| `UML012_NO_TERMINAL` | warning | No state is terminal, so completion, failure and a stuck flow all look the same. |
+| `UML013_NO_NARRATIVE` | info | The model carries no meanings, so a reader must re-derive every symbol from the source. |
+| `UML014_UNDOCUMENTED_STATE` | info | These states render as their bare id, so the diagram cannot be read against the code. |
+| `UML015_LABEL_DRIFT` | warning | A diagram label disagrees with the model narrative. One of the two is stale, and the review cannot tell which. |
+| `UML016_DIAGRAM_PARSE_NOTES` | info | Notes collected while rendering or reading the diagram. They mark information the notation could not carry. |
+| `UML017_ROUND_TRIP_MISMATCH` | error | The diagram does not carry the model. Transitions were lost or invented, or init, terminals or variables differ. The `roundTrip.diffs` array lists each one. |
+| `UML018_FIDELITY_UNCHECKED` | info | Only a diagram was supplied, so nothing here proves it matches the code. |
+| `UML019_ROUND_TRIP_SKIPPED` | warning | The fidelity check could not run, either because the view is not round-trippable or because it was switched off. |
+
+`ok: true` means the review ran. It does not mean the model is good. Read the findings and the `summary` counts.
+
+### What the round trip proves
+
+It proves the diagram is a faithful rendering of the model:
+
+- the same initial state
+- the same set of states and terminal states
+- the same transitions, with the same guards and actions
+- the same variables and kinds
+
+It does **not** prove the model matches the code. Only a citation-per-element comparison does that, as described under "Evidence rule". It also does not prove the machine is correct. That is the job of `logicprobe_verify`.
+
+A failing round trip means the notation lost something. In practice that is a real finding: an unlabelled arrow, a guard the parser could not read, or a diagram that was hand-edited away from its model.
+
+## Worked example
+
+The code under review is a handshake that retries on timeout and gives up.
+
+```text
+INIT --power_ready--> STARTING
+STARTING --ack--> ACTIVE
+STARTING --timeout [retry < 3] / retry := retry + 1--> ERROR
+STARTING --timeout [retry >= 3]--> FATAL (terminal)
+ERROR --cooldown--> STARTING
+```
+
+Render it as a state machine, then review it. The review reports two modelling gaps:
+
+```text
+UML006_INEXHAUSTIVE_BRANCH (info)  guards look complementary on retry
+UML013_NO_NARRATIVE       (info)  no state, event or scenario meanings
+```
+
+Neither is a behaviour bug. Add the narrative so a reader can check the diagram against the code, then run `logicprobe_verify` for S1-S8 and A1-A14.
+
+Now delete the `ERROR --cooldown--> STARTING` arrow and review again. `ACTIVE` and `ERROR` become dead ends (`UML003`), and `cooldown` becomes an event that only fires from an unreachable state (`UML007`). The diagram still looks plausible. That is the whole point.
+
+## Limits
+
+- The review is **structural**. It evaluates no guard over any valuation. "Probably exhaustive" is a shape test, not a proof. S6 is the check that decides.
+- Reachability ignores guards (`UML002`). A state reachable only under an unsatisfiable guard is a behaviour finding (S1 and S6), not a modelling one.
+- Sequence diagrams are traces. They are neither round-tripped nor parsed. Reviewing one renders the trace, reports the structure findings, and marks the fidelity check inapplicable (`UML019`).
+- PlantUML activity is refused by design, as described above.
+- Renaming a state in the diagram does not rename it in the code. The review can only tell you the two disagree. Resolving it needs the source.
+- The generated diagram is a faithful view of the **model**, never of the **program**. If the model is wrong, the diagram is wrong in exactly the same way.

package/src/compose-tool.ts

@@ -1,4 +1,5 @@
-import { defineTool, type JsonValue } from '@deepseek-ai/dsh-tools'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
 import { runCompositionVerification } from './engine.js'
 
 export const LOGICPROBE_COMPOSE_TOOL_NAME = 'logicprobe_compose_verify'

package/src/concurrency-tool.ts

@@ -1,4 +1,5 @@
-import { defineTool, type JsonValue } from '@deepseek-ai/dsh-tools'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
 import { runConcurrencyScan } from './concurrency.js'
 
 export const LOGICPROBE_CONCURRENCY_SCAN_TOOL_NAME = 'logicprobe_concurrency_scan'

package/src/data-tool.ts

@@ -1,4 +1,5 @@
-import { defineTool, type JsonValue } from '@deepseek-ai/dsh-tools'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
 import { runDataVerification, DATA_ENGINE_SCHEMA_VERSION } from './data-engine.js'
 
 export const LOGICPROBE_DATAMODEL_VERIFY_TOOL_NAME = 'logicprobe_datamodel_verify'

package/src/engine.ts

@@ -1824,26 +1824,68 @@ function S8_monotonicVariables(model: LogicModelV1): CheckResult {
   return checkResult('S8', 'Monotonic Variables', findings, findings.length === 0 ? 'Monotonic variables are respected' : 'Monotonic findings: ' + findings.length)
 }
 
+/**
+ * Find a run from `start` that never reaches `target`, or return undefined when
+ * every run does. The property is universal (see the A9 row in `SKILL.md`): one
+ * branch that loops forever, or that stops before the target, refutes it.
+ *
+ * The search is a depth-first walk of the run graph with three colours, and target
+ * runs are success leaves that are never expanded:
+ *
+ * - a node reached while it is on the current walk (GRAY) closes a cycle that avoids
+ *   the target, so some run never reaches it;
+ * - a node with no outgoing step at all stops the machine where it stands, which is
+ *   the same violation for a different reason;
+ * - a node whose walk completed without a violation is BLACK, and reaching it again
+ *   from another branch is a shared sub-graph, not a cycle.
+ *
+ * That last point is why the colour map cannot be a plain visited set: a diamond
+ * (two branches rejoining) is acyclic and must pass, while a genuine cycle must not.
+ * A run is identified by its state plus its variable values, so the same state id
+ * with different values is a different node.
+ */
 function findLeadsToBadPath(model: LogicModelV1, start: RuntimeState, target: string): { path: PathStep[]; reason: string } | undefined {
   if (start.state === target) return undefined
-  const visited = new Set<string>()
-  const queue: Array<{ runtime: RuntimeState; path: PathStep[] }> = [{ runtime: start, path: [] }]
-  while (queue.length > 0) {
-    const entry = queue.shift()!
-    const key = runtimeKey(entry.runtime)
-    if (entry.runtime.state === target) continue
-    if (visited.has(key)) return { path: entry.path, reason: 'Cycle avoids target ' + target }
-    visited.add(key)
-    const nexts: Array<{ next: RuntimeState; event: string }> = []
-    for (const event of allEvents(model)) {
-      for (const next of stepRuntime(model, entry.runtime, event)) nexts.push({ next, event })
+  const GRAY = 1
+  const BLACK = 2
+  interface LeadFrame {
+    runtime: RuntimeState
+    path: PathStep[]
+    /** Outgoing steps, filled on first expansion; `undefined` means "not expanded yet". */
+    nexts: Array<{ next: RuntimeState; event: string }> | undefined
+    index: number
+  }
+  const color = new Map<string, number>()
+  const stack: LeadFrame[] = [{ runtime: start, path: [], nexts: undefined, index: 0 }]
+  color.set(runtimeKey(start), GRAY)
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1]
+    if (frame.nexts === undefined) {
+      const nexts: Array<{ next: RuntimeState; event: string }> = []
+      for (const event of allEvents(model)) {
+        for (const next of stepRuntime(model, frame.runtime, event)) nexts.push({ next, event })
+      }
+      frame.nexts = nexts
+      if (nexts.length === 0) return { path: frame.path, reason: 'Dead end before target ' + target }
     }
-    if (nexts.length === 0) return { path: entry.path, reason: 'Dead end before target ' + target }
-    for (const { next, event } of nexts) {
-      queue.push({ runtime: next, path: [...entry.path, { from: entry.runtime.state, event, to: next.state }] })
+    if (frame.index >= frame.nexts.length) {
+      color.set(runtimeKey(frame.runtime), BLACK)
+      stack.pop()
+      continue
     }
+    const { next, event } = frame.nexts[frame.index]
+    frame.index += 1
+    const step: PathStep = { from: frame.runtime.state, event, to: next.state }
+    if (next.state === target) continue
+    const key = runtimeKey(next)
+    const seen = color.get(key)
+    if (seen === GRAY) return { path: [...frame.path, step], reason: 'Cycle avoids target ' + target }
+    if (seen === BLACK) continue
+    color.set(key, GRAY)
+    stack.push({ runtime: next, path: [...frame.path, step], nexts: undefined, index: 0 })
   }
-  return { path: [], reason: 'No path reaches target ' + target }
+  // Every branch either reached the target or rejoined a branch that did.
+  return undefined
 }
 
 function A9_leadsTo(model: LogicModelV1, exploration: Exploration): CheckResult {

package/src/export-tool.ts

@@ -1,4 +1,5 @@
-import { defineTool, type JsonValue } from '@deepseek-ai/dsh-tools'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
 import { exportModel, type ExportFormat } from './exporters.js'
 
 export const LOGICPROBE_EXPORT_TOOL_NAME = 'logicprobe_export'

package/src/index.ts

@@ -39,6 +39,7 @@ import { logicProbeDataModelVerifyTool, DATA_ENGINE_SCHEMA_VERSION } from './dat
 import { logicProbeConcurrencyScanTool } from './concurrency-tool.js'
 import { logicProbeComposeTool } from './compose-tool.js'
 import { logicProbeExportTool } from './export-tool.js'
+import { logicProbeUmlTool } from './uml-tool.js'
 import { ENGINE_SCHEMA_VERSION } from './engine.js'
 
 // DSH 0.1.7-alpha.1 (session format v4) retires the shared
@@ -85,7 +86,7 @@ Plugin logicprobe is active. Documents are not truth — code is. Verify every v
 | "I'll verify while implementing" | Verification happens before implementation, not during. |
 | "I can check this with reasoning alone" | Behavioral claims are verified with code/models, not intuition. One counter-example refutes a universal claim. |
 
-**Native verification path**: In dsh, prefer the \`logicprobe_verify\` tool for state-machine checks and \`logicprobe_datamodel_verify\` for data-model/schema migration checks. Both support before/after regression and common domain constraints (idempotency, monotonic, sequence, leads-to, atomicity). Python harnesses remain the fallback for non-dsh hosts.
+**Native verification path**: In dsh, prefer the \`logicprobe_verify\` tool for state-machine checks and \`logicprobe_datamodel_verify\` for data-model/schema migration checks. Both support before/after regression and common domain constraints (idempotency, monotonic, sequence, leads-to, atomicity). To model a code flow as UML, or to audit such a modelling, use \`logicprobe_uml\` (render | parse | review). Python harnesses remain the fallback for non-dsh hosts.
 
 **Proactive suggestion**: When a user asks code-level behavioral questions — "could this state machine deadlock", "is this retry limit safe", "check this timing sequence for bugs", "is this migration non-breaking", "does this copy cover all required fields" — suggest logicprobe as an optional verification pass (do not auto-escalate).
 </EXTREMELY_IMPORTANT>`
@@ -211,6 +212,7 @@ function modeContextText(config: Config, session: Session): string {
   const interaction = resolveInteraction(config, session)
   const lines = [
     'logicprobe: use `logicprobe_verify` for state machines and `logicprobe_datamodel_verify` for data models; both cover before/after regression and common domain constraints.',
+    'logicprobe: use `logicprobe_uml` to model a code flow as UML (render), to read a UML diagram back into a model (parse), or to audit the modelling (review: structural defects, documentation gaps, diagram-vs-model round-trip fidelity).',
     interaction === 'auto'
       ? 'logicprobe interaction=auto: do NOT call ask_user_question for model confirmation; run round-trip validation of the extracted transition table and mark the result UNCONFIRMED.'
       : 'logicprobe interaction=ask: show the extracted transition table and get user confirmation before running verification.',
@@ -234,7 +236,7 @@ interface SystemPromptLike {
  * lets the model read this plugin's runtime status without guessing. Mirrors
  * the registration pattern of the official dsh-tool-cordis host providers.
  */
-function inspectProvider(config: Config, isToolRegistered: () => boolean, isDataToolRegistered: () => boolean, isConcurrencyToolRegistered: () => boolean, isComposeToolRegistered: () => boolean, isExportToolRegistered: () => boolean): HostCordisInspectProviderRegistration {
+function inspectProvider(config: Config, isToolRegistered: () => boolean, isDataToolRegistered: () => boolean, isConcurrencyToolRegistered: () => boolean, isComposeToolRegistered: () => boolean, isExportToolRegistered: () => boolean, isUmlToolRegistered: () => boolean): HostCordisInspectProviderRegistration {
   return {
     manifest: {
       id: 'logicprobe',
@@ -260,10 +262,11 @@ function inspectProvider(config: Config, isToolRegistered: () => boolean, isData
               concurrencyToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_concurrency_scan tool is registered on ctx.tools.' },
               composeToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_compose_verify tool is registered on ctx.tools.' },
               exportToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_export tool is registered on ctx.tools.' },
+              umlToolRegistered: { type: 'boolean', description: 'Whether the logicprobe_uml tool (UML modelling + modelling review) is registered on ctx.tools.' },
               engineSchemaVersion: { type: 'integer', description: 'Model schema version the bundled state-machine verification engine accepts.' },
               dataEngineSchemaVersion: { type: 'integer', description: 'Model schema version the bundled data-model verification engine accepts.' },
             },
-            required: ['enabled', 'gateContentLength', 'interaction', 'toolRegistered', 'dataToolRegistered', 'concurrencyToolRegistered', 'composeToolRegistered', 'exportToolRegistered', 'engineSchemaVersion', 'dataEngineSchemaVersion'],
+            required: ['enabled', 'gateContentLength', 'interaction', 'toolRegistered', 'dataToolRegistered', 'concurrencyToolRegistered', 'composeToolRegistered', 'exportToolRegistered', 'umlToolRegistered', 'engineSchemaVersion', 'dataEngineSchemaVersion'],
             additionalProperties: false,
           },
         },
@@ -280,6 +283,7 @@ function inspectProvider(config: Config, isToolRegistered: () => boolean, isData
           concurrencyToolRegistered: isConcurrencyToolRegistered(),
           composeToolRegistered: isComposeToolRegistered(),
           exportToolRegistered: isExportToolRegistered(),
+          umlToolRegistered: isUmlToolRegistered(),
           engineSchemaVersion: ENGINE_SCHEMA_VERSION,
           dataEngineSchemaVersion: DATA_ENGINE_SCHEMA_VERSION,
         }
@@ -299,13 +303,14 @@ export function apply(ctx: Context, config: Config): void {
   let concurrencyToolRegistered = false
   let composeToolRegistered = false
   let exportToolRegistered = false
+  let umlToolRegistered = false
   let modeContextRegistered = false
   const registerProvider = (): void => {
     if (providerRegistered) return
     const inspect = ctx.get('cordisInspect')
     if (inspect === undefined) return
     try {
-      ctx.effect(() => inspect.register(inspectProvider(config, () => toolRegistered, () => dataToolRegistered, () => concurrencyToolRegistered, () => composeToolRegistered, () => exportToolRegistered)), 'logicprobe: inspect provider')
+      ctx.effect(() => inspect.register(inspectProvider(config, () => toolRegistered, () => dataToolRegistered, () => concurrencyToolRegistered, () => composeToolRegistered, () => exportToolRegistered, () => umlToolRegistered)), 'logicprobe: inspect provider')
       providerRegistered = true
     } catch (err) {
       console.warn('[logicprobe] inspect provider registration failed', err)
@@ -321,11 +326,13 @@ export function apply(ctx: Context, config: Config): void {
       ctx.effect(() => tools.register(logicProbeConcurrencyScanTool), 'logicprobe: concurrency scan tool')
       ctx.effect(() => tools.register(logicProbeComposeTool), 'logicprobe: compose tool')
       ctx.effect(() => tools.register(logicProbeExportTool), 'logicprobe: export tool')
+      ctx.effect(() => tools.register(logicProbeUmlTool), 'logicprobe: uml tool')
       toolRegistered = true
       dataToolRegistered = true
       concurrencyToolRegistered = true
       composeToolRegistered = true
       exportToolRegistered = true
+      umlToolRegistered = true
     } catch (err) {
       console.warn('[logicprobe] logicprobe_verify/logicprobe_datamodel_verify tool registration failed', err)
     }

package/src/json-value.ts

@@ -0,0 +1,20 @@
+/**
+ * Structural mirror of the JSON value union the dsh tool registry accepts.
+ *
+ * `@deepseek-ai/dsh-tools` exported this type through the 0.1.x line and stopped
+ * exporting it in 0.2.x, where the same type now lives in
+ * `@deepseek-ai/dsh-util-values`. This package declares peer support for both
+ * lines, so it cannot import the type from either one without breaking the other
+ * build. Declaring the one-line union here keeps `npm run typecheck` green against
+ * both, and it costs nothing at runtime: every use is a type-only cast on a value
+ * this package already produced.
+ *
+ * Keep it structurally identical to the official type. A cast through `unknown` to
+ * this alias is only a way to satisfy `defineTool`'s return-type constraint; if the
+ * official union ever widens, this alias must widen with it.
+ *
+ * @module logicprobe-json-value
+ */
+
+/** JSON-serializable value: null, boolean, number, string, or an array/object of those. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }

package/src/tool.ts

@@ -1,4 +1,5 @@
-import { defineTool, type JsonValue } from '@deepseek-ai/dsh-tools'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
 import { runVerification } from './engine.js'
 
 export const LOGICPROBE_VERIFY_TOOL_NAME = 'logicprobe_verify'

package/src/uml-tool.ts

@@ -0,0 +1,106 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { renderUml, parseUml, reviewUml, UmlError, type UmlDiagram, type UmlNotation } from './uml.js'
+
+export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
+
+/**
+ * DSH tool wrapping the UML front end: model a code flow as a UML diagram
+ * (`action: "render"`), read a UML diagram back into a LogicModelV1
+ * (`action: "parse"`), or review the modelling itself (`action: "review"`).
+ *
+ * review is the half that makes the feature a check rather than a drawing
+ * utility: it reports structural defects the diagram would present as valid
+ * flow (unreachable states, dead ends, ambiguous and non-exhaustive branches,
+ * self-loops with no exit), documentation gaps (a symbol no reader can map back
+ * to code), and — the fidelity check — whether the rendered diagram reads back
+ * as the model it was drawn from.
+ */
+export const logicProbeUmlTool = defineTool({
+  name: LOGICPROBE_UML_TOOL_NAME,
+  description:
+    'Model a code flow as UML, and review the modelling. action="render" turns a LogicModelV1 (schemaVersion=1) into diagram source: notation mermaid (state | activity flowchart | sequence) or plantuml (state | sequence). action="parse" reads Mermaid/PlantUML state or activity text back into a LogicModelV1 (plus the display labels it found), so a hand-drawn diagram can be verified with logicprobe_verify; a sequence diagram is refused because a trace cannot reconstruct a machine. action="review" audits the modelling: structural defects (UML002 unreachable state, UML003 dead end, UML004 ambiguous branch, UML005 overlapping guard, UML006 inexhaustive branch, UML007 unused event, UML008 self-loop with no exit, UML009 duplicate transition), documentation gaps (UML010 unused variable, UML011 unbounded variable, UML012 no terminal, UML013 no narrative, UML014 undocumented state, UML015 label drift), and the fidelity check — the diagram is rendered and re-parsed and any structural difference is reported as UML017 round-trip mismatch. Give review a model (checks it, renders and re-parses it), a diagram (parses and reviews that), or both (checks the diagram against the model). Rendering never invents structure and never silently drops a construct the notation cannot express: those become warnings. Review does NOT replace logicprobe_verify — it covers the modelling, not behaviour; findings name the engine check to run next.',
+  parameters: {
+    action: {
+      type: 'string',
+      required: true,
+      enum: ['render', 'parse', 'review'],
+      description: 'render = model → UML source; parse = UML source → model; review = audit the modelling (and its fidelity to the model).',
+    },
+    model: {
+      type: 'json',
+      description: 'LogicModelV1 machine. Required for render; accepted by review (alone, or next to diagram to check the two against each other).',
+    },
+    diagram: {
+      type: 'string',
+      description: 'UML source text. Required for parse; accepted by review.',
+    },
+    notation: {
+      type: 'string',
+      enum: ['auto', 'mermaid', 'plantuml'],
+      description: 'Diagram language. Default auto: detected from the text for parse/review, mermaid for render.',
+    },
+    kind: {
+      type: 'string',
+      enum: ['state', 'activity', 'sequence'],
+      description: 'Diagram kind to render. Default state. sequence is one BFS trace, not the whole machine. PlantUML activity is refused (its structured-flowchart syntax cannot faithfully carry a graph with merges or cycles) — use mermaid for that view.',
+    },
+    roundTrip: {
+      type: 'boolean',
+      description: 'review only: render and re-parse the model to prove the diagram carries it. Default true.',
+    },
+    maxSteps: {
+      type: 'integer',
+      description: 'Cap on the sequence trace length when rendering kind=sequence. Default 60.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Render result (diagram source), parse result (LogicModelV1 + labels), or the modelling review report with findings, round-trip diff and next steps.',
+    },
+    render(_args, value) {
+      const record = value as unknown as Record<string, unknown>
+      // A rendered diagram is source text: print it verbatim so it can be copied
+      // into a file, then the structured result (warnings, notation, kind).
+      if (typeof record.diagram === 'string') {
+        return [
+          { type: 'text' as const, text: record.diagram },
+          { type: 'text' as const, text: JSON.stringify(value, null, 2) },
+        ]
+      }
+      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      if (args.action === 'render') {
+        if (args.model === undefined) return errorResult('action=render needs `model` (a LogicModelV1 object)')
+        const result = renderUml(args.model, (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation, (args.kind ?? 'state') as UmlDiagram, args.maxSteps)
+        return { ok: true, action: 'render', notation: result.notation, kind: result.diagram, diagram: result.primary, warnings: result.warnings } as unknown as JsonValue
+      }
+      if (args.action === 'parse') {
+        if (args.diagram === undefined) return errorResult('action=parse needs `diagram` (Mermaid or PlantUML text)')
+        const result = parseUml(args.diagram, args.notation ?? 'auto')
+        return { ok: true, action: 'parse', notation: result.notation, kind: result.diagram, model: result.model, labels: result.labels, warnings: result.warnings } as unknown as JsonValue
+      }
+      const report = reviewUml({
+        model: args.model,
+        diagram: args.diagram,
+        notation: args.notation ?? 'auto',
+        diagramKind: (args.kind ?? 'state') as UmlDiagram,
+        roundTrip: args.roundTrip,
+        maxSteps: args.maxSteps,
+      })
+      return report as unknown as JsonValue
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error), error instanceof UmlError) as unknown as JsonValue
+    }
+  },
+})
+
+function errorResult(message: string, isUmlError = false): JsonValue {
+  return { ok: false, ...(isUmlError ? { errorCode: 'UML_INPUT' } : {}), error: message } as unknown as JsonValue
+}