dsh-logicprobe 0.7.1 → 0.8.1

package/lib/engine.js

@@ -1721,31 +1721,67 @@ function S8_monotonicVariables(model) {
     }
     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, start, target) {
     if (start.state === target)
         return undefined;
-    const visited = new Set();
-    const queue = [{ 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 = [];
-        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;
+    const color = new Map();
+    const stack = [{ 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 = [];
+            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 = { 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, exploration) {
     const findings = [];

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,7 +60,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>`;
@@ -146,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.',
@@ -160,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',
@@ -186,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,
                     },
                 },
@@ -206,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,
                 };
@@ -224,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)
@@ -232,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) {
@@ -251,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);

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

package/lib/uml-tool.js

@@ -0,0 +1,104 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { renderUml, parseUml, reviewUml, UmlError } 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;
+            // 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', text: record.diagram },
+                    { type: 'text', text: JSON.stringify(value, null, 2) },
+                ];
+            }
+            return [{ type: 'text', 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), (args.kind ?? 'state'), args.maxSteps);
+                return { ok: true, action: 'render', notation: result.notation, kind: result.diagram, diagram: result.primary, warnings: result.warnings };
+            }
+            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 };
+            }
+            const report = reviewUml({
+                model: args.model,
+                diagram: args.diagram,
+                notation: args.notation ?? 'auto',
+                diagramKind: (args.kind ?? 'state'),
+                roundTrip: args.roundTrip,
+                maxSteps: args.maxSteps,
+            });
+            return report;
+        }
+        catch (error) {
+            return errorResult(error instanceof Error ? error.message : String(error), error instanceof UmlError);
+        }
+    },
+});
+function errorResult(message, isUmlError = false) {
+    return { ok: false, ...(isUmlError ? { errorCode: 'UML_INPUT' } : {}), error: message };
+}