dsh-logicprobe 0.7.0 → 0.8.0

package/lib/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/lib/index.js

@@ -33,6 +33,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';
 export const name = 'logicprobe';
 // Skills are contributed through the registry service, which dsh-base always
@@ -59,15 +60,47 @@ 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>`;
+/**
+ * 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(field) {
+    const probe = field;
+    return typeof probe.volatile === 'function' ? probe.volatile() : field;
+}
 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) {
+    const value = config.enabled;
+    return typeof value === 'boolean' ? value : value.get();
+}
 function gateMessage(text) {
     return createUserMessage({
         content: [{ type: 'text', text }],
@@ -114,6 +147,7 @@ function modeContextText(config, session) {
     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.',
@@ -128,7 +162,7 @@ function modeContextText(config, session) {
  * 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, isToolRegistered, isDataToolRegistered, isConcurrencyToolRegistered, isComposeToolRegistered, isExportToolRegistered) {
+function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcurrencyToolRegistered, isComposeToolRegistered, isExportToolRegistered, isUmlToolRegistered) {
     return {
         manifest: {
             id: 'logicprobe',
@@ -154,10 +188,11 @@ function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcu
                             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,
                     },
                 },
@@ -166,7 +201,7 @@ function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcu
         query: async (method) => {
             if (method === 'status') {
                 return {
-                    enabled: config.enabled,
+                    enabled: injectionEnabled(config),
                     gateContentLength: config.gateContent.length,
                     interaction: config.interaction,
                     toolRegistered: isToolRegistered(),
@@ -174,6 +209,7 @@ function inspectProvider(config, isToolRegistered, isDataToolRegistered, isConcu
                     concurrencyToolRegistered: isConcurrencyToolRegistered(),
                     composeToolRegistered: isComposeToolRegistered(),
                     exportToolRegistered: isExportToolRegistered(),
+                    umlToolRegistered: isUmlToolRegistered(),
                     engineSchemaVersion: ENGINE_SCHEMA_VERSION,
                     dataEngineSchemaVersion: DATA_ENGINE_SCHEMA_VERSION,
                 };
@@ -192,6 +228,7 @@ export function apply(ctx, config) {
     let concurrencyToolRegistered = false;
     let composeToolRegistered = false;
     let exportToolRegistered = false;
+    let umlToolRegistered = false;
     let modeContextRegistered = false;
     const registerProvider = () => {
         if (providerRegistered)
@@ -200,7 +237,7 @@ export function apply(ctx, config) {
         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) {
@@ -219,11 +256,13 @@ export function apply(ctx, config) {
             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);
@@ -272,8 +311,12 @@ export function apply(ctx, config) {
             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 ->
@@ -290,6 +333,8 @@ export function apply(ctx, config) {
         if (decision.kind === 'reject')
             return decision;
         registerIntegrations();
+        if (!injectionEnabled(config))
+            return decision;
         if (gateInHistory(agent.session))
             return decision;
         return {

package/lib/json-value.js

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+export {};

package/lib/types/index.d.ts

@@ -24,7 +24,7 @@
  *
  * @module logicprobe-dsh
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { ContextFormed } from '@deepseek-ai/dsh-llm';
 declare module '@deepseek-ai/dsh-llm' {
@@ -38,17 +38,23 @@ export declare const name = "logicprobe";
 export declare const inject: string[];
 export type InteractionMode = 'ask' | 'auto' | 'follow-approval';
 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 declare const Config: z<Schemastery.ObjectS<{
-    enabled: z<boolean, boolean>;
-    gateContent: z<string, string>;
-    interaction: z<"ask" | "auto" | "follow-approval", "ask" | "auto" | "follow-approval">;
-}>, Schemastery.ObjectT<{
-    enabled: z<boolean, boolean>;
-    gateContent: z<string, string>;
-    interaction: z<"ask" | "auto" | "follow-approval", "ask" | "auto" | "follow-approval">;
-}>>;
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "defined">;
+    gateContent: z<string, string, "defined">;
+    interaction: z<"ask" | "auto" | "follow-approval", "ask" | "auto" | "follow-approval", "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "defined">;
+    gateContent: z<string, string, "defined">;
+    interaction: z<"ask" | "auto" | "follow-approval", "ask" | "auto" | "follow-approval", "defined">;
+}>>, "plain">;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/types/json-value.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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/lib/types/uml-tool.d.ts

@@ -0,0 +1,14 @@
+export declare 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 declare const logicProbeUmlTool: import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/uml.d.ts

@@ -0,0 +1,167 @@
+/**
+ * UML front end for LogicModelV1 — model a code flow as a UML diagram, then
+ * review the modelling itself.
+ *
+ * Two halves, one data flow:
+ *
+ *   1. `renderUml` turns a validated LogicModelV1 into Mermaid or PlantUML text
+ *      (state machine, activity/flow, or sequence trace). The diagram is a
+ *      *view*: it never invents structure the model does not have, and anything
+ *      the notation cannot express is reported as a warning instead of being
+ *      dropped silently.
+ *   2. `parseUml` reads that text back into a LogicModelV1, and `reviewUml`
+ *      compares the two. That comparison is the point of the feature: a UML
+ *      diagram of a code flow is itself a model, and a model can be wrong —
+ *      ambiguous branches, dead ends, flows nobody can enter, symbols the
+ *      source never names. A diagram that does not round-trip to the model it
+ *      was drawn from is mis-modelled, and the review says so.
+ *
+ * Why the round trip is the fidelity check: rendering and parsing are inverse
+ * only if every construct survives the notation. The generated text carries
+ * `logicprobe:` directives (ignored by Mermaid/PlantUML renderers) that pin the
+ * initial state, the terminal states and any state id the notation cannot spell
+ * verbatim, so an exact comparison is possible rather than a fuzzy one.
+ *
+ * The review deliberately does NOT replace `logicprobe_verify`: it checks the
+ * modelling (structure the diagram claims, documentation coverage, notation
+ * fidelity), while S1-S8/A1-A14 check the machine's behaviour (guard
+ * exhaustiveness under real valuations, invariant paths, deadlock/liveness in
+ * the runtime state space). Findings name the engine check to run next.
+ *
+ * @module logicprobe-uml
+ */
+import type { GuardNode, LogicModelV1, UpdateSpec } from './engine.js';
+export type UmlNotation = 'mermaid' | 'plantuml';
+export type UmlDiagram = 'state' | 'activity' | 'sequence';
+export declare const UML_NOTATIONS: readonly UmlNotation[];
+export declare const UML_DIAGRAMS: readonly UmlDiagram[];
+export interface UmlRenderResult {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    /** The diagram source; hand this to the user or a renderer as-is. */
+    primary: string;
+    warnings: string[];
+}
+export interface UmlParseResult {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    model: LogicModelV1;
+    /**
+     * Display labels found in the diagram, keyed by state id. They are how a
+     * reader learns what a symbol means; a missing entry is an undocumented
+     * symbol, which the review reports.
+     */
+    labels: Record<string, string>;
+    warnings: string[];
+}
+export interface UmlFinding {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    states?: string[];
+    events?: string[];
+    transitions?: Array<{
+        from: string;
+        event: string;
+        to: string;
+    }>;
+    detail?: string;
+}
+export interface UmlRoundTripReport {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    ok: boolean;
+    modelHash: string;
+    parsedHash: string;
+    diffs: string[];
+    warnings: string[];
+}
+export interface UmlReviewReport {
+    ok: boolean;
+    source: 'model' | 'diagram' | 'model+diagram';
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+        states: number;
+        events: number;
+        transitions: number;
+        terminalStates: number;
+        reachableStates: number;
+        documentedStates: number;
+    };
+    findings: UmlFinding[];
+    roundTrip: UmlRoundTripReport | null;
+    /** Diagram display labels, when a diagram took part in the review. */
+    labels?: Record<string, string>;
+    /** Model parsed from the diagram, when a diagram was given (feed it to `logicprobe_verify`). */
+    model?: LogicModelV1;
+    /** Diagram rendered from the model, when only a model was given. */
+    primary?: string;
+    warnings: string[];
+    nextSteps: string[];
+}
+export declare class UmlError extends Error {
+}
+/** Canonical guard text. Rendering wraps every composite node in parentheses, and the parser flattens same-operator chains, so render∘parse is the identity. */
+export declare function guardText(node: GuardNode): string;
+/**
+ * Render a LogicModelV1 as UML.
+ *
+ * PlantUML has no faithful activity view here: its activity syntax is a
+ * structured flowchart language, so a graph with merges or cycles needs a
+ * while/if reconstruction this module does not perform. Refusing is the honest
+ * outcome — quietly emitting a state diagram under an "activity" request would
+ * mislabel the model. Mermaid covers all three views.
+ *
+ * @param input - candidate LogicModelV1.
+ * @param notation - `mermaid` (default) or `plantuml`.
+ * @param diagram - `state` (default), `activity`, or `sequence`.
+ * @param maxSteps - cap on the sequence trace length.
+ */
+export declare function renderUml(input: unknown, notation?: UmlNotation, diagram?: UmlDiagram, maxSteps?: number): UmlRenderResult;
+/** Parse a guard expression such as `(retry < 3 && armed == true)`. */
+export declare function parseGuardText(text: string): GuardNode;
+/** Parse a UML action clause such as `retry := retry + 1, armed := true`. */
+export declare function parseUpdatesText(text: string, warnings: string[]): UpdateSpec[];
+/**
+ * Parse a Mermaid or PlantUML diagram back into a LogicModelV1.
+ *
+ * State and activity diagrams carry the whole machine, so they parse into a
+ * complete model. Sequence diagrams do not: a trace shows the paths that were
+ * walked, not the branches that were not, so parsing one would silently prune
+ * the machine. That case is refused rather than approximated.
+ *
+ * @param text - diagram source.
+ * @param notation - `auto` (default) detects Mermaid vs PlantUML from the text.
+ */
+export declare function parseUml(text: string, notation?: UmlNotation | 'auto'): UmlParseResult;
+/** Compare two machines by structure — the fidelity measure behind the round-trip check. */
+export declare function diffModels(left: LogicModelV1, right: LogicModelV1): string[];
+export interface UmlReviewOptions {
+    /** LogicModelV1 to review. Provide it, `diagram`, or both. */
+    model?: unknown;
+    /** Diagram text: reviewed on its own, or compared against `model` when both are given. */
+    diagram?: string;
+    notation?: UmlNotation | 'auto';
+    diagramKind?: UmlDiagram;
+    /** Render-and-reparse fidelity check (default true; only meaningful with a model). */
+    roundTrip?: boolean;
+    /** Cap on the sequence trace used for the fidelity check. */
+    maxSteps?: number;
+}
+/**
+ * Review a UML model of a code flow.
+ *
+ * Three inputs are possible and each answers a different question:
+ *
+ * - `model` only — "is this machine well-modelled?" The review checks the
+ *   structure the diagram would draw, then renders and re-parses it to prove the
+ *   diagram carries the machine faithfully (round trip).
+ * - `diagram` only — "what does this diagram actually say?" The diagram is parsed
+ *   into a model, and that model is reviewed; nothing can be said about fidelity
+ *   to a machine the caller did not provide.
+ * - both — "does this diagram match this model?" Any structural difference is a
+ *   modelling defect and is reported both as round-trip diffs and as a finding.
+ */
+export declare function reviewUml(options: UmlReviewOptions): UmlReviewReport;