dsh-logicprobe 1.2.0 → 1.3.0

package/README.en-US.md

@@ -80,12 +80,12 @@ Any key starting with `_` — at any level: `_source`, `_verified`, `_extraction
 
 `logicprobe_uml` draws a LogicModelV1 as UML. It also reads a hand-drawn UML diagram back into a model, reviews the modelling itself, and prints the label and comment conventions the parser accepts. It has four actions:
 
-- **render**: model to diagram. Mermaid covers state, activity flowchart and sequence views. PlantUML covers state and sequence. Any construct the notation cannot express becomes a warning instead of a silent drop. PlantUML activity is refused, because that syntax cannot carry a graph with merges or cycles faithfully.
+- **render**: model to diagram. Mermaid covers state, activity flowchart and sequence views. PlantUML covers state and sequence. Any construct the notation cannot express becomes a warning instead of a silent drop. PlantUML activity is refused, because that syntax cannot carry a graph with merges or cycles faithfully. The view follows the question, not the machine, so no tool picks it for you: declare the purpose with `intent` (`present` / `verify` / `fidelity`) and a pairing that cannot serve it is refused before any work (`UML_INTENT_UNSERVABLE`, `UML_VIEW_UNREPRESENTABLE`, `UML_INTENT_MISMATCH`). Omit `intent` and nothing changes.
 - **parse**: diagram to model. It reads Mermaid and PlantUML state or activity diagrams, so a hand-drawn diagram can go straight into `logicprobe_verify`. Two inputs are refused because they cannot become a machine: a sequence diagram (a trace cannot reconstruct a machine), and any other Mermaid family (`classDiagram`, `erDiagram`, `gantt`, `mindmap`, …), which comes back as `errorCode: "UML_NOT_A_STATE_DIAGRAM"` naming the family.
 - **review**: audits the modelling. It reports structural defects and documentation gaps. The structural defects are unreachable states, dead ends, ambiguous branches, self-loops with no exit, and duplicate transitions. The documentation gaps are a missing narrative, unbounded variables, states a reader cannot map back to code, and label drift between diagram and narrative. It also runs the fidelity check: it parses the diagram back into a model and reports every structural difference.
 - **explain-labels**: prints the label spellings and ignored-line rules the parser applies (`directiveLines`, `acceptedLabelForms`, `renderedForm`, `ignoredLines`, `rules`), with no diagram needed. Reach for it when a hand-drawn diagram and a rendered one disagree; the CLI mirror is `uml-review --explain-labels`.
 
-**A structure diagram is the dangerous case, because it parses.** A PlantUML component, package, class or deployment diagram declares no diagram kind, so the parser meets its keywords line by line. The arrows look like transitions, so `parse` returns a by-product model — now together with an error finding `UML_NOT_A_STATE_DIAGRAM`, `discardedConstructs` (every declaration it could not represent, with line and text), `discardedEdges` (the arrows misread as transitions) and `verdict: "fail"`. Read that as: **this file has no model and this diagram was not reviewed.** Do not feed the by-product to `logicprobe_verify` and call the result an architecture review. Structural checks over a real dependency graph (allowed-edge matrices, cycles, isolated nodes) do not exist yet; the codes `UML020`+ are reserved for them.
+**A structure diagram is the dangerous case, because it parses.** A PlantUML component, package, class or deployment diagram declares no diagram kind, so the parser meets its keywords line by line. The arrows look like transitions, so `parse` returns a by-product model — now together with an error finding `UML_NOT_A_STATE_DIAGRAM`, `discardedConstructs` (every declaration it could not represent, with line and text), `discardedEdges` (the arrows misread as transitions) and `verdict: "fail"`. Read that as: **this file has no model and this diagram was not reviewed.** Do not feed the by-product to `logicprobe_verify` and call the result an architecture review. Structural checks over a real dependency graph (allowed-edge matrices, cycles, isolated nodes) belong to `logicprobe_structure_verify`, under Architecture and Dependency Review below.
 
 Fidelity is the core of the feature. Generated diagrams carry `logicprobe:` comment directives for the initial state, the terminal states, aliases and variable kinds. Mermaid and PlantUML ignore those lines; the parser reads them. That is what makes the diagram-versus-model comparison exact.
 

package/README.md

@@ -78,12 +78,12 @@ logicprobe 核验声称与实物是否一致。事实类对着源码查。行为
 
 `logicprobe_uml` 把一份 LogicModelV1 画成 UML，也可以把手绘的 UML 读回模型，还可以审查建模本身，或打印解析器接受的标签与注释口径。它有 4 个动作：
 
-- **render**：模型 → 图。Mermaid 支持状态图、活动流程图、时序图；PlantUML 支持状态图与时序图。notation 表达不了的构造会变成 warning，不会被悄悄丢掉。PlantUML 活动图直接拒绝，因为它的语法无法忠实承载带合流或环的图。
+- **render**：模型 → 图。Mermaid 支持状态图、活动流程图、时序图；PlantUML 支持状态图与时序图。notation 表达不了的构造会变成 warning，不会被悄悄丢掉。PlantUML 活动图直接拒绝，因为它的语法无法忠实承载带合流或环的图。视图由问题决定、不由模型决定，所以工具不替你选：用 `intent`（`present`/`verify`/`fidelity`）声明产物用途，服务不了的组合在开工之前就拒（`UML_INTENT_UNSERVABLE`、`UML_VIEW_UNREPRESENTABLE`、`UML_INTENT_MISMATCH`）；不给 `intent` 则行为与从前完全一致。
 - **parse**：图 → 模型。支持 Mermaid 与 PlantUML 的状态图、活动图，因此手绘的图也能送进 `logicprobe_verify` 验证。两类输入会被拒绝，因为它们无法变成状态机：时序图（迹无法重建机），以及**其它 Mermaid 图族**（`classDiagram`、`erDiagram`、`gantt`、`mindmap`…），返回 `errorCode: "UML_NOT_A_STATE_DIAGRAM"` 并点名该图族。
 - **review**：审查建模。它报告两类问题。结构缺陷包括不可达状态、死端、歧义分支、无出口自环、重复迁移。文档缺口包括缺 narrative、变量无界、状态无可读标注、图与 narrative 标签漂移。它还会做保真度检查：把图重新解析回模型，任何结构性差异都报出来。
 - **explain-labels**：打印解析器接受的标签写法与忽略行口径（`directiveLines`、`acceptedLabelForms`、`renderedForm`、`ignoredLines`、`rules`），不需要给图。手绘图与渲染图对不齐时先看它；命令行对应 `uml-review --explain-labels`。
 
-**结构图是最危险的一类，因为它「能解析」。** PlantUML 的组件图 / 包图 / 类图 / 部署图不声明图类型，解析器会逐行碰上它的关键字。箭头看起来就是迁移，于是 `parse` 会返回一个副产品模型——但现在同时给出 error 级发现 `UML_NOT_A_STATE_DIAGRAM`、`discardedConstructs`（每条无法表达的声明及其行号与原文）、`discardedEdges`（被误读成迁移的箭头数），以及 `verdict: "fail"`。意思是：**这份文件没有被建模，这张图没有被审查。** 不要把那个副产品喂给 `logicprobe_verify` 当作架构审查结论。针对真正依赖图的结构检查（允许依赖矩阵、环、孤立节点）尚未实现，编号 `UML020`+ 已为其保留。
+**结构图是最危险的一类，因为它「能解析」。** PlantUML 的组件图 / 包图 / 类图 / 部署图不声明图类型，解析器会逐行碰上它的关键字。箭头看起来就是迁移，于是 `parse` 会返回一个副产品模型——但现在同时给出 error 级发现 `UML_NOT_A_STATE_DIAGRAM`、`discardedConstructs`（每条无法表达的声明及其行号与原文）、`discardedEdges`（被误读成迁移的箭头数），以及 `verdict: "fail"`。意思是：**这份文件没有被建模，这张图没有被审查。** 不要把那个副产品喂给 `logicprobe_verify` 当作架构审查结论。真正的依赖图检查（允许依赖矩阵、环、孤立节点）由 `logicprobe_structure_verify` 承担，见下方「架构与依赖审查」。
 
 保真度是这套功能的核心。生成的图带有 `logicprobe:` 注释指令（init、终态、别名、变量类型），Mermaid 与 PlantUML 会忽略它们，而解析器会读取它们。因此「图 ↔ 模型」的比较是精确的。
 

package/lib/types/uml.d.ts

@@ -1,256 +1,293 @@
-/**
- * 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 HashSpec, type NarrativeCoverage, type ReportSchema, type Verdict } from './engine.js';
-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>;
-    /**
-     * Declarations found in the text that LogicModelV1 cannot represent. A non-empty
-     * list means the parsed model is NOT this diagram: the text belongs to another
-     * diagram family (component, package, class, deployment, …), so whatever came
-     * out is a by-product of reading keywords the parser does not own.
-     */
-    discardedConstructs: DiscardedConstruct[];
-    /**
-     * Arrows whose endpoints were declared by a discarded construct. They survive
-     * parsing as state transitions, which is exactly why they are counted out loud.
-     */
-    discardedEdges: number;
-    warnings: string[];
-}
-/** One declaration the parser could not represent, with the source line that carried it. */
-export interface DiscardedConstruct {
-    /** The construct keyword, lower-cased (`component`, `package`, `classDiagram`). */
-    construct: string;
-    /** 1-based line number in the diagram source. */
-    line: number;
-    /** The source line, trimmed. */
-    text: 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;
-    /** Machine-readable context for the finding (ids, coverage, rule matches), same shape as the engine's findings. */
-    evidence?: Record<string, unknown>;
-}
-export interface UmlRoundTripReport {
-    notation: UmlNotation;
-    diagram: UmlDiagram;
-    ok: boolean;
-    /** Which published hash specification the two hashes follow (see references/hash-spec.md). */
-    hashSpec: HashSpec;
-    modelHash: string;
-    parsedHash: string;
-    diffs: string[];
-    warnings: string[];
-}
-export interface UmlReviewReport {
-    /** The review ran and produced this report. It does NOT mean the modelling passed — read `verdict`. */
-    ok: boolean;
-    ran: boolean;
-    verdict: Verdict;
-    verdictReason: string;
-    /** The versioned report contract this result follows. */
-    schema: ReportSchema;
-    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;
-    /** Paths of the `_`-prefixed metadata keys found in the supplied model, when it carried any. */
-    metadataKeys?: string[];
-    /** How much of the model the narrative documents; absent when there is no narrative. */
-    narrativeCoverage?: NarrativeCoverage;
-    /** Hashes of what was reviewed, in one place. */
-    hashes: {
-        hashSpec: HashSpec;
-        modelHash?: string;
-        parsedHash?: string;
-    };
-    /** Declarations the parser could not represent; a non-empty list fails the review. */
-    discardedConstructs?: DiscardedConstruct[];
-    /** Arrows whose endpoints came from a discarded construct. */
-    discardedEdges?: number;
-    warnings: string[];
-    nextSteps: string[];
-}
-/**
- * A UML front-end refusal. `code` lets the tool report *why* it refused instead of
- * collapsing every refusal into a generic input error.
- */
-export declare class UmlError extends Error {
-    readonly code: string;
-    constructor(message: string, code?: string);
-}
-/** 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[];
-/**
- * Findings a parse result carries on its own. A diagram from another family parses
- * into something; without this finding that something is presented as a model of the
- * file, which is a false guarantee of exactly the kind this plugin exists to prevent.
- */
-export declare function parseFindings(parsed: UmlParseResult): UmlFinding[];
-/** One accepted way of writing a state's meaning into a diagram label. */
-export interface LabelForm {
-    form: string;
-    example: string;
-    note: string;
-}
-export interface LabelExplanation {
-    notation: UmlNotation;
-    /** The comment prefix a `logicprobe:` directive uses in this notation. */
-    directivePrefix: string;
-    directiveLines: Array<{
-        example: string;
-        meaning: string;
-    }>;
-    /** Accepted label spellings, in the order `documentedMeaning` accepts them. */
-    acceptedLabelForms: LabelForm[];
-    /** What the renderer itself writes, so a hand-edited diagram can match it. */
-    renderedForm: string;
-    ignoredLines: Array<{
-        pattern: string;
-        behaviour: string;
-    }>;
-    rules: string[];
-}
-/**
- * What the front end expects of labels and comments, so "why does my hand-drawn diagram
- * report label drift or ignored lines?" has a printed answer instead of a guess.
- * `tests/uml/run.mjs` feeds every claim here back through the parser, so this text cannot
- * drift away from the behaviour it describes.
- */
-export declare function explainLabels(notation?: UmlNotation): LabelExplanation;
-/**
- * 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;
+/**
+ * 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 HashSpec, type NarrativeCoverage, type ReportSchema, type Verdict } from './engine.js';
+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[];
+/**
+ * What the caller is going to do with the artifact, declared up front.
+ *
+ * The view follows the question, not the machine, so the tool cannot pick it. What it
+ * can do is refuse a pairing that cannot serve the question — before the work, not as
+ * a finding after it.
+ */
+export type UmlIntent = 'present' | 'verify' | 'fidelity';
+export declare const UML_INTENTS: readonly UmlIntent[];
+/** The tool actions, for the entry check. `labels` is `action=explain-labels`. */
+export type UmlIntentAction = 'render' | 'parse' | 'review' | 'labels';
+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>;
+    /**
+     * Declarations found in the text that LogicModelV1 cannot represent. A non-empty
+     * list means the parsed model is NOT this diagram: the text belongs to another
+     * diagram family (component, package, class, deployment, …), so whatever came
+     * out is a by-product of reading keywords the parser does not own.
+     */
+    discardedConstructs: DiscardedConstruct[];
+    /**
+     * Arrows whose endpoints were declared by a discarded construct. They survive
+     * parsing as state transitions, which is exactly why they are counted out loud.
+     */
+    discardedEdges: number;
+    warnings: string[];
+}
+/** One declaration the parser could not represent, with the source line that carried it. */
+export interface DiscardedConstruct {
+    /** The construct keyword, lower-cased (`component`, `package`, `classDiagram`). */
+    construct: string;
+    /** 1-based line number in the diagram source. */
+    line: number;
+    /** The source line, trimmed. */
+    text: 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;
+    /** Machine-readable context for the finding (ids, coverage, rule matches), same shape as the engine's findings. */
+    evidence?: Record<string, unknown>;
+}
+export interface UmlRoundTripReport {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+    ok: boolean;
+    /** Which published hash specification the two hashes follow (see references/hash-spec.md). */
+    hashSpec: HashSpec;
+    modelHash: string;
+    parsedHash: string;
+    diffs: string[];
+    warnings: string[];
+}
+export interface UmlReviewReport {
+    /** The review ran and produced this report. It does NOT mean the modelling passed — read `verdict`. */
+    ok: boolean;
+    ran: boolean;
+    verdict: Verdict;
+    verdictReason: string;
+    /** The versioned report contract this result follows. */
+    schema: ReportSchema;
+    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;
+    /** Paths of the `_`-prefixed metadata keys found in the supplied model, when it carried any. */
+    metadataKeys?: string[];
+    /** How much of the model the narrative documents; absent when there is no narrative. */
+    narrativeCoverage?: NarrativeCoverage;
+    /** Hashes of what was reviewed, in one place. */
+    hashes: {
+        hashSpec: HashSpec;
+        modelHash?: string;
+        parsedHash?: string;
+    };
+    /** Declarations the parser could not represent; a non-empty list fails the review. */
+    discardedConstructs?: DiscardedConstruct[];
+    /** Arrows whose endpoints came from a discarded construct. */
+    discardedEdges?: number;
+    warnings: string[];
+    nextSteps: string[];
+}
+/**
+ * A UML front-end refusal. `code` lets the tool report *why* it refused instead of
+ * collapsing every refusal into a generic input error.
+ */
+export declare class UmlError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/** 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;
+/**
+ * The `(notation, view)` cells this module can draw.
+ *
+ * PlantUML activity is the cell that does not exist: 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.
+ */
+export declare function assertUmlView(notation: UmlNotation, diagram: UmlDiagram): void;
+/**
+ * Refuse, before any work, a request whose declared purpose the view cannot serve.
+ *
+ * Without an intent this changes nothing: the review still reports `UML019` when the
+ * fidelity check does not apply to the view it was given. With one, an impossible
+ * pairing is an error carrying a code, instead of a report about the wrong artifact —
+ * which is the failure this check exists to prevent.
+ *
+ * @param intent - the declared purpose, or `undefined` to leave the behaviour unchanged.
+ * @param action - which action is about to run.
+ * @param view - the requested `(notation, diagram)`, for the actions that have one.
+ */
+export declare function checkUmlIntent(intent: UmlIntent | undefined, action: UmlIntentAction, view?: {
+    notation: UmlNotation;
+    diagram: UmlDiagram;
+}): void;
+/**
+ * Render a LogicModelV1 as UML.
+ *
+ * Mermaid covers all three views; PlantUML covers state and sequence (see
+ * `assertUmlView` for why activity is refused).
+ *
+ * @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.
+ * @param intent - what the diagram is for; a view that cannot serve it is refused first.
+ */
+export declare function renderUml(input: unknown, notation?: UmlNotation, diagram?: UmlDiagram, maxSteps?: number, intent?: UmlIntent): 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[];
+/**
+ * Findings a parse result carries on its own. A diagram from another family parses
+ * into something; without this finding that something is presented as a model of the
+ * file, which is a false guarantee of exactly the kind this plugin exists to prevent.
+ */
+export declare function parseFindings(parsed: UmlParseResult): UmlFinding[];
+/** One accepted way of writing a state's meaning into a diagram label. */
+export interface LabelForm {
+    form: string;
+    example: string;
+    note: string;
+}
+export interface LabelExplanation {
+    notation: UmlNotation;
+    /** The comment prefix a `logicprobe:` directive uses in this notation. */
+    directivePrefix: string;
+    directiveLines: Array<{
+        example: string;
+        meaning: string;
+    }>;
+    /** Accepted label spellings, in the order `documentedMeaning` accepts them. */
+    acceptedLabelForms: LabelForm[];
+    /** What the renderer itself writes, so a hand-edited diagram can match it. */
+    renderedForm: string;
+    ignoredLines: Array<{
+        pattern: string;
+        behaviour: string;
+    }>;
+    rules: string[];
+}
+/**
+ * What the front end expects of labels and comments, so "why does my hand-drawn diagram
+ * report label drift or ignored lines?" has a printed answer instead of a guess.
+ * `tests/uml/run.mjs` feeds every claim here back through the parser, so this text cannot
+ * drift away from the behaviour it describes.
+ */
+export declare function explainLabels(notation?: UmlNotation): LabelExplanation;
+/**
+ * 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;
+    /** What the review is for; a view that cannot serve it is refused before any work. */
+    intent?: UmlIntent;
+}
+/**
+ * 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;