dsh-logicprobe 0.7.0 → 0.8.0

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/client.js

@@ -0,0 +1,212 @@
+/**
+ * logicprobe — browser half: the gate-injection switch on the dsh Web client's
+ * Plugins page.
+ *
+ * The Plugins page (`@deepseek-ai/dsh-client-ui-plugin-manager`) owns the
+ * sidebar **Plugins** entry and declares the slots a bundle's own configuration
+ * registers into. This module contributes one `plugins.bundle.config` entry,
+ * keyed by this package's npm name, so the switch renders on logicprobe's own
+ * page between its description and its rows.
+ *
+ * Why the switch writes through `configForms` rather than reaching for the
+ * profile file: dsh's settings service exposes only the Config fields declared
+ * `.volatile()`, and it rejects a write to any other path. `enabled` is such a
+ * field (see `src/index.ts`), so flipping the switch is an ordinary
+ * revision-fenced settings write that the running Host picks up in place — the
+ * injection there re-reads the reference on every model step.
+ *
+ * Shape: this is a prebuilt module-system bundle, not a source module. It calls
+ * `window.__ModuleLoader__.load({ id, factory })` with this package's resolved
+ * npm name, and `factory` returns the cordis plugin face. Only the client
+ * baseline is requested (`react` and
+ * `@deepseek-ai/dsh-client-ui-primitives`); every other capability arrives
+ * through cordis `inject`. `scripts/build-client.mjs` publishes this file
+ * verbatim as `lib/client.js`.
+ *
+ * @module dsh-logicprobe/client
+ */
+
+window.__ModuleLoader__.load({
+  id: 'dsh-logicprobe',
+  factory: (require) => {
+    const React = require('react')
+    const { Button, Switch } = require('@deepseek-ai/dsh-client-ui-primitives')
+
+    /** Settings namespace: the Loader entry id this bundle's patch declares. */
+    const NS = 'logicprobe'
+    /** `plugins.bundle.config` key: the bundle's npm package name. */
+    const PACKAGE = 'dsh-logicprobe'
+    /** This page's dictionary namespace. */
+    const LOCALE_NS = 'logicprobe.plugins'
+    /** The Config field the switch writes inside the namespace's section. */
+    const FIELD = 'enabled'
+
+    /** English copy. */
+    const en = {
+      title: 'Gate injection',
+      label: 'Inject the gate text',
+      hint: 'Folds the claim-verification doctrine into the first model step of every session. Turning it off leaves the skills and the verification tools registered — only the injected text is dropped.',
+      overridden: 'Overridden',
+      reset: 'Reset to default',
+      readOnly: 'This deployment stores settings read-only.',
+      unavailable: 'This plugin is not loaded, so it cannot be configured right now.',
+      saveFailed: 'The deployment did not accept that value; the switch shows what is stored.',
+    }
+    /** Simplified Chinese copy. */
+    const zh = {
+      title: 'Gate 注入',
+      label: '注入 gate 文本',
+      hint: '把 claim 核查铁律折进每个会话的第一个模型步。关掉后 skills 与验证工具仍然注册，只是不再注入那段提示文本。',
+      overridden: '已覆盖',
+      reset: '恢复默认',
+      readOnly: '本部署的设置为只读。',
+      unavailable: '该插件当前未加载，暂时无法配置。',
+      saveFailed: '本部署没有接受这个值，开关显示的是已存下的状态。',
+    }
+
+    /** Required cordis services. */
+    const inject = ['slots', 'locale', 'configForms']
+
+    const GROUP = { display: 'flex', flexDirection: 'column', gap: '8px' }
+    const TITLE = { margin: 0, fontSize: '14px', fontWeight: '500', lineHeight: '22px' }
+    const ROW = { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '16px' }
+    const LABEL = { fontSize: '13px', lineHeight: '20px' }
+    const NOTE = { margin: 0, fontSize: '12px', lineHeight: '18px', color: 'var(--dsw-alias-label-tertiary)' }
+    const FAILED = { margin: 0, fontSize: '12px', lineHeight: '18px', color: 'var(--dsw-alias-state-error-primary)' }
+
+    /**
+     * Whether a settings-layer value carries this field, which is what marks it
+     * overridden: an override equal to the default is still an override.
+     * @param layer - the raw user layer the form snapshot carries.
+     * @returns whether the layer holds the field.
+     */
+    function carries(layer) {
+      return layer !== null && typeof layer === 'object' && Object.prototype.hasOwnProperty.call(layer, FIELD)
+    }
+
+    /**
+     * Render the gate-injection switch, or the note saying why it cannot render.
+     * @param props - the page's `t` seat, the bound form snapshot hook, and the write actions.
+     * @returns the body of this bundle's configuration section.
+     */
+    function InjectionCard(props) {
+      const t = props.t
+      const state = props.useInjectionForm((snapshot) => snapshot)
+      const [pending, setPending] = React.useState(false)
+      const [failed, setFailed] = React.useState(false)
+
+      /** Run one settings write and report a refusal or a transport failure. */
+      const write = (run) => {
+        setPending(true)
+        setFailed(false)
+        Promise.resolve(run()).then(
+          (accepted) => {
+            setPending(false)
+            setFailed(accepted === false)
+          },
+          () => {
+            setPending(false)
+            setFailed(true)
+          },
+        )
+      }
+
+      if (state.status !== 'ready') {
+        return React.createElement('p', { style: NOTE }, t('unavailable'))
+      }
+
+      const section = state.value !== null && typeof state.value === 'object' ? state.value : {}
+      // The schema default is `true`; only an explicit false means off.
+      const checked = section[FIELD] !== false
+      const overridden = carries(state.user)
+      const locked = state.writable !== true || pending
+
+      const children = [
+        React.createElement('h4', { key: 'title', style: TITLE }, t('title')),
+        React.createElement('div', { key: 'row', style: ROW }, [
+          React.createElement('span', { key: 'label', style: LABEL }, t('label')),
+          React.createElement(Switch, {
+            key: 'switch',
+            checked,
+            disabled: locked,
+            label: t('label'),
+            onChange: (next) => write(() => props.setEnabled(next)),
+          }),
+        ]),
+        React.createElement('p', { key: 'hint', style: NOTE }, state.writable === true ? t('hint') : t('readOnly')),
+      ]
+
+      if (overridden) {
+        children.push(
+          React.createElement('div', { key: 'overridden', style: ROW }, [
+            React.createElement('span', { key: 'badge', style: NOTE }, t('overridden')),
+            React.createElement(
+              Button,
+              {
+                key: 'reset',
+                variant: 'outline',
+                size: 'sm',
+                disabled: locked,
+                onClick: () => write(() => props.resetEnabled()),
+              },
+              t('reset'),
+            ),
+          ]),
+        )
+      }
+
+      if (failed) {
+        children.push(React.createElement('p', { key: 'failed', style: FAILED, role: 'alert' }, t('saveFailed')))
+      }
+
+      return React.createElement('div', { style: GROUP }, children)
+    }
+
+    /**
+     * Mount the switch while the Host serves logicprobe's settings namespace.
+     * @param ctx - the browser plugin context.
+     */
+    function apply(ctx) {
+      ctx.effect(() => ctx.locale.register(LOCALE_NS, { zh, en }), 'dsh-logicprobe: dictionaries')
+      // `whileServed` is the registration barrier that keeps this page alive only
+      // while the Host serves the namespace. Hosts predating it (measured: dsh
+      // 0.1.5-rc.3 and 0.1.6-alpha.2) have no live settings field to offer at all,
+      // so there is nothing to register — and calling it there would throw during
+      // this plugin's own activation, which the Web boot audit then reports as a
+      // failed client entry. Degrade to no page instead.
+      if (typeof ctx.configForms.whileServed !== 'function') return
+      // The page renders the section only for a bundle whose package name is in
+      // its configuration ledger, and the ledger follows this registration. The
+      // registration in turn waits for the namespace to be served, so a profile
+      // whose logicprobe row is switched off shows no trace of the switch.
+      ctx.effect(
+        () =>
+          ctx.configForms.whileServed([NS], () => {
+            const form = ctx.configForms.get(NS)
+            const source = {
+              getSnapshot: () => form.getSnapshot(),
+              subscribe: (listener) => form.subscribe(listener),
+            }
+            return ctx.slots.inject('plugins.bundle.config', () =>
+              ctx.slots.register(
+                {
+                  name: 'plugins.bundle.config',
+                  key: PACKAGE,
+                  locale: LOCALE_NS,
+                  inject: () => ({
+                    hooks: { injectionForm: source },
+                    setEnabled: (next) => form.set(FIELD, next),
+                    resetEnabled: () => form.unset(FIELD),
+                  }),
+                },
+                InjectionCard,
+              ),
+            )
+          }),
+        'dsh-logicprobe: gate-injection switch',
+      )
+    }
+
+    return { inject, apply }
+  },
+})

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/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

@@ -26,7 +26,7 @@
  */
 
 import { fileURLToPath } from 'node:url'
-import type { Context } from '@deepseek-ai/cordis'
+import type { Context, Volatile } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContextFormed } from '@deepseek-ai/dsh-llm'
@@ -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,23 +86,68 @@ 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>`
 
+/** A schemastery field that may or may not carry `.volatile()`. */
+interface LiveField {
+  volatile?: () => unknown
+}
+
+/**
+ * Declare a field as live where this host's schemastery can — `.volatile()`
+ * arrived in 3.18.3 — and leave it an ordinary field where it cannot.
+ *
+ * The fallback is load-bearing, not defensive padding. `Config` below is built
+ * while this module is still being evaluated, so an unconditional `.volatile()`
+ * on a host shipping schemastery 3.18.2 (measured: dsh 0.1.5-rc.2 and
+ * 0.1.5-rc.3) throws during import; the loader entry then fails and takes the
+ * WHOLE plugin tree — and the host's boot — down with it. Degrading costs only
+ * the Plugins-page switch, because the settings service projects nothing but
+ * fields under a `.volatile()` node; skills, tools and the gate injection are
+ * untouched. The returned schema keeps the plain field's static type; the
+ * `Config` interface below carries the union the host actually hands over.
+ */
+function live<T>(field: T): T {
+  const probe = field as T & LiveField
+  return typeof probe.volatile === 'function' ? (probe.volatile() as T) : field
+}
+
 export interface Config {
-  enabled: boolean
+  /**
+   * The injection switch the Web client's Plugins page edits live: a `Volatile`
+   * reference on a host whose schemastery supports one, an ordinary boolean on a
+   * host that predates `.volatile()`. Read it through {@link injectionEnabled},
+   * which accepts both shapes.
+   */
+  enabled: Volatile<boolean> | boolean
   gateContent: string
   interaction: InteractionMode
 }
 
 export const Config = z.object({
-  enabled: z.boolean().default(true),
+  // Live so the Web Plugins page can flip the gate injection inside a running
+  // session: dsh's settings service projects ONLY fields under a `.volatile()`
+  // node and rejects writes to every other path. The price is that the injection
+  // reads the reference per step instead of deciding once at mount, which is also
+  // what lets a toggle take effect without remounting the row.
+  enabled: live(z.boolean().default(true)),
   gateContent: z.string().default(DEFAULT_GATE_CONTENT),
   interaction: z.union(['ask', 'auto', 'follow-approval']).default('follow-approval'),
 })
 
+/**
+ * Read the injection switch as a boolean, whichever shape this host produced.
+ * @param config - the resolved plugin configuration.
+ * @returns whether the gate may be injected.
+ */
+function injectionEnabled(config: Config): boolean {
+  const value = config.enabled
+  return typeof value === 'boolean' ? value : value.get()
+}
+
 function gateMessage(text: string): UserMessage {
   return createUserMessage({
     content: [{ type: 'text', text }],
@@ -166,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.',
@@ -189,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',
@@ -215,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,
           },
         },
@@ -227,7 +275,7 @@ function inspectProvider(config: Config, isToolRegistered: () => boolean, isData
     query: async (method) => {
       if (method === 'status') {
         return {
-          enabled: config.enabled,
+          enabled: injectionEnabled(config),
           gateContentLength: config.gateContent.length,
           interaction: config.interaction,
           toolRegistered: isToolRegistered(),
@@ -235,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,
         }
@@ -254,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)
@@ -276,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)
     }
@@ -324,7 +376,12 @@ export function apply(ctx: Context, config: Config): void {
       customSkillDirs: [SKILLS_DIR],
     })
   })
-  if (!config.enabled) return
+  // Injection listens unconditionally, including while the switch is off: the
+  // switch is volatile, so `apply` runs once and the value behind it can turn on
+  // later from the Web Plugins page. Returning early on a false value here would
+  // freeze that decision for the lifetime of the mount, and turning the switch
+  // back on could never take effect without a profile restart.
+  //
   // Inject the gate once per session on the FIRST model step that runs,
   // instead of at session-start: session-start injection lands in the agent's
   // inbox, which a blank-session preset switch (agentPreset.select ->
@@ -340,6 +397,7 @@ export function apply(ctx: Context, config: Config): void {
     const decision = await next()
     if (decision.kind === 'reject') return decision
     registerIntegrations()
+    if (!injectionEnabled(config)) return decision
     if (gateInHistory(agent.session)) return decision
     return {
       kind: 'enter',

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'