dsh-logicprobe 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-logicprobe",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Verifies claims about designs and code. Facts go against the source. Behaviour goes through an executable model: state machines, protocols, composition, data models, migrations. Structure diagrams are read as dependency graphs, at one level or several. Two reports can be compared for regression. Exports UPPAAL, TLA+, PRISM and SPIN input. Ships a native DeepSeek Harness bundle that injects the verification gate into the first model step.",
   "type": "module",
   "main": "lib/index.js",

package/skills/logicprobe/SKILL.md

@@ -203,6 +203,25 @@ Turn the verdict into an answer, never into a summary of `ok`:
 
 Exit codes: `0` for `pass` / `pass_with_findings`, `2` for `fail`, a refusal, or an unreadable input. In DSH the native tools return the report as data — read `verdict`, and treat `errorCode`/`error` as the refusal path.
 
+### Writing the Answer: Name the Finding, Not Its Code
+
+`S2_NO_TRANSITIONS`, `UML019`, `DA2` are values of `findings[].code`, not names. A reader
+who has not memorized the schema learns nothing from one, and cannot tell whether their
+machine is sound or stuck.
+
+- **Say what it means**, in the user's language and in the terms of their own code:
+  「启动超时后 ERROR 没有任何出口迁移，机器会停在那里」, not 「S2 命中」. The finding's
+  `message` is written for the report; the sentence for the user is written from it.
+- **Keep the identifier where the identifier is the subject**: a report field quoted
+  verbatim, a baseline diff, a test name, or a question about the check itself.
+- **Name the property, not the checking.** "This path locks without unlocking" beats
+  "A4 failed". A check's name earns its place when the reader asked about the checking.
+- **Carry the verdict in words.** "Not verified" or "verified, within the scope of this
+  model" — never a bare pass, and never a warning presented without its label.
+
+A reader who cannot tell what failed will either trust a report they cannot read, or
+ignore one they should act on.
+
 ### Slice Acceptance: Baseline Diffs
 
 The acceptance criterion for a refactoring slice is usually "no **new** findings", not

package/skills/logicprobe-concurrency/SKILL.md

@@ -42,3 +42,4 @@ The full routing table, including hard-real-time, hybrid-control and execution-c
 3. **One counterexample is enough to refute.** If a race is suspected, the deliverable is the interleaving that breaks it plus the harness that demonstrates it (TSan/Helgrind output), not an argument.
 4. **Sequential targets are out of scope.** If nothing runs concurrently, say so and stop.
 5. **The scanner is dsh-only.** `logicprobe_concurrency_scan` has no mirror subcommand. Without it, mine the text by hand against the keyword table above and route each claim the same way.
+6. **Name the claim and its routing in words.** 「QoS 1 只投递一次」plus the tool that decides it, never a bare check name. A reader who has not memorized this skill's tables learns nothing from an enumeration. The full rule is under "Writing the Answer" in the `logicprobe` skill.

package/skills/logicprobe-datamodel/SKILL.md

@@ -92,6 +92,11 @@ The **DataModelV1 shape** is in [`references/data-model-schema.md`](references/d
 | DD3 | Delta summary | Warning |
 | DD4 | Breaking change regression | Error/Warning |
 
+Every `#` in these tables is a report field, not a name. Write what the check found for the
+reader (「回滚与备份不对称」), in their language; keep the id for a report field quoted
+verbatim, a baseline diff or a test name. The full rule is under "Writing the Answer" in the
+`logicprobe` skill.
+
 ## Extraction Rule
 
 Before writing any verification code, output a data-model table:

package/skills/logicprobe-structure/SKILL.md

@@ -91,5 +91,6 @@ This tool audits the **diagram**; an include or dependency scan audits the **cod
 2. **Quote the rule id for every judged edge.** "Not allowed" without the rule is an opinion; `matchedRules` makes it a finding.
 3. **Run the numbers, never the impression.** An isolated node and a back edge are exactly what a reader misses by eye; that is why the check exists.
 4. **Report the diagram-code difference, not just the diagram.** A structure review that never touches the source is a review of a drawing.
+5. **Report the rule id with its meaning, never the id alone.** Rule 2 keeps the id on every judged edge, so the finding is defensible; the sentence the reader gets says what the edge violated (「HAL 反向依赖了上层」), in their language. The full rule is under "Writing the Answer" in the `logicprobe` skill.
 
 The full matrix schema, a worked example and the reconciliation worksheet are in [`references/structure-review-guide.md`](references/structure-review-guide.md).

package/skills/logicprobe-uml/SKILL.md

@@ -32,6 +32,8 @@ code flow → model (citation per element) → logicprobe_uml action=render →
 - **review** — it answers one of three questions. Give it a model: is the machine well-modelled? Give it a diagram: what does the diagram say? Give it both: does the diagram match the model?
 - **explain-labels** — the parser's own account of labels and comments: the accepted spellings, the form the renderer writes, and which lines it ignores. No diagram needed. It answers "why does my hand-drawn diagram report drift or ignored lines?" without reading the source.
 
+The view follows the question, not the machine, and no tool picks it for you. Declare the question with `intent` (`present` / `verify` / `fidelity`) and a view that cannot serve it is refused before any work, with a code that names why. The ordered procedure, the intent-by-action table and those codes are under [Choosing the view](references/uml-modeling-guide.md#choosing-the-view).
+
 A host without the tools runs the same four actions through the repository engine. The engine is deliberately single-source — do not copy it into this skill.
 
 ## A Structure Diagram Is the Dangerous Case, Because It Parses
@@ -53,5 +55,6 @@ Structural defects: unreachable states, dead ends, ambiguous or non-exhaustive b
 3. **Check the verdict before the picture.** `ok: true` with `verdict: "fail"` means the review failed; a diagram whose review failed is not something to show as if it were checked.
 4. **The review never replaces verification.** It covers the modelling. S1-S8 and A1-A14 cover the behaviour, and each finding names the check that settles it — hand those over to the `logicprobe` skill.
 5. **Keep the narrative with the model.** Write `narrative.states`, `narrative.events` and `narrative.scenarios`. Then the diagram stays readable against the code, and label drift shows up as a finding instead of as a stale picture.
+6. **Name a finding for the reader, not by its code.** `UML017_ROUND_TRIP_MISMATCH` is a report field; the sentence the reader gets says what disagreed (「图里少了 ERROR→COOLDOWN 这条迁移」), in their language. Keep the code for a report field quoted verbatim, a diff or a test name. The full rule is under "Writing the Answer" in the `logicprobe` skill.
 
 The full checklist (codes `UML001` to `UML019` plus `UML_NOT_A_STATE_DIAGRAM`), the directive format generated diagrams carry, a worked example, and the limits of each view are in [`references/uml-modeling-guide.md`](references/uml-modeling-guide.md).

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

@@ -4,7 +4,17 @@ This guide covers two jobs: drawing a code flow as UML, and reviewing that drawi
 
 One rule runs through the whole guide. **A diagram is a model, and a model can be wrong.** A tidy flow chart is not evidence about the code. Worse, a diagram that disagrees with the model it came from will mislead every reader who trusts it.
 
-## When to use this
+## Choosing the view
+
+The view follows the question, not the machine. Decide in this order.
+
+**1. Is the question about where dependencies point?** Architecture, layering, module
+structure, "may this call that" — that question belongs to the `logicprobe-structure`
+skill, which reads the same component, package, class or deployment text as a dependency
+graph. The state front end refuses that text by name
+(`UML_NOT_A_STATE_DIAGRAM`) instead of reviewing it.
+
+**2. Otherwise fix the boundary first, then pick the view by the reader's question.**
 
 | Situation | View that answers it |
 |---|---|
@@ -14,7 +24,65 @@ One rule runs through the whole guide. **A diagram is a model, and a model can b
 | "Somebody gave me a diagram. Is it right?" | Any view. Feed it to the review and compare it against the code. |
 | "This diagram and this model disagree." | Feed both to the review. The round-trip check names every difference. |
 
-Do not use this guide for a behavioural claim about a specific machine. That is the job of `logicprobe_verify` (S1-S8 and A1-A14). The review here covers the modelling, not the behaviour. Every finding it produces names the engine check that settles the behavioural half.
+**3. Check the choice against the next step.** A view that cannot feed the check you are
+about to run is the wrong view, however readable it looks.
+
+| Next step | Views that can feed it |
+|---|---|
+| `logicprobe_verify` (S1-S8 and A1-A14) | State or activity: `parse` reads either into a LogicModelV1 |
+| `logicprobe_uml action=review` with a model, for the fidelity check | State or activity: only those round-trip |
+| `logicprobe_uml action=review` with a model alone | Any view. With `kind: "sequence"` the trace is rendered and the fidelity check is reported inapplicable (`UML019`) |
+| A human reading a protocol exchange | Sequence, which is the honest view there |
+
+**4. Say that out loud, and the tool refuses a pairing that cannot serve it.** `intent`
+declares what the artifact is for. The check runs before any work, so an impossible
+pairing is a refusal with a code rather than a report about the wrong artifact.
+
+| Intent | What it means | Actions that serve it | View it needs |
+|---|---|---|---|
+| `present` | a human is going to read the diagram | render, review | any view the notation can draw |
+| `verify` | it must be parseable into a LogicModelV1 for the engine | render, parse, review | state or activity: a trace cannot be parsed back |
+| `fidelity` | the point is the render-and-reparse proof | review | state or activity: only those round-trip |
+
+| `errorCode` | What happened |
+|---|---|
+| `UML_INTENT_UNSERVABLE` | The view exists but cannot serve the intent — a sequence view for `verify` or `fidelity`. |
+| `UML_VIEW_UNREPRESENTABLE` | The `(notation, view)` cell does not exist — PlantUML activity. |
+| `UML_INTENT_MISMATCH` | The intent names something this action does not do — `fidelity` on render (render proves nothing), `present` or `fidelity` on parse (parse returns a model). |
+
+Omitting `intent` changes nothing: a sequence view still renders, and a review of one
+still reports `UML019`. The intent is an opt-in statement of purpose, and nothing infers
+it. The CLI mirror takes the same values: `--intent present|verify|fidelity` on
+`uml-render`, `uml-parse` and `uml-review`.
+
+When the question is still unclear, model the state machine. It is the safe default, and
+the other views render from the same model afterwards.
+
+### Nothing picks the view for you
+
+`render` takes `kind` from the caller and defaults to `state`; it never guesses. A guess
+between state and activity would be a presentation decision, and the machine cannot make
+it: the same guarded branch is a state machine to one reader and an error path to another.
+`parse` does detect the notation and the diagram family from the text, and it refuses the
+families it cannot model, by name.
+
+Mechanically decidable, and nothing else:
+
+- the notation and the family the text declares — a Mermaid header (`stateDiagram`,
+  `flowchart`, `sequenceDiagram`, or a known other-family header) or a PlantUML body
+  keyword;
+- whether the requested notation-and-kind combination exists at all (PlantUML has no
+  activity view here);
+- whether a view can carry the fidelity check (a sequence cannot).
+
+Everything else is a fact about the question, not about the artifact. A model can tell you
+its shape — its state count, its guarded branches, its cycles — and its shape does not
+choose the view.
+
+Do not use this guide for a behavioural claim about a specific machine. That is the job of
+`logicprobe_verify` (S1-S8 and A1-A14). The review here covers the modelling, not the
+behaviour. Every finding it produces names the engine check that settles the behavioural
+half.
 
 ## The three views
 

package/src/uml-tool.ts

@@ -2,7 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { createHash } from 'node:crypto'
 import type { JsonValue } from './json-value.js'
 import { REPORT_SCHEMAS, DEFAULT_HASH_SPEC, modelHash, refusalVerdict, verdictOf, verdictOfFindings, type VerdictSummary } from './engine.js'
-import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, UmlError, type UmlDiagram, type UmlFinding, type UmlNotation, type UmlParseResult } from './uml.js'
+import { renderUml, parseUml, parseFindings, reviewUml, explainLabels, checkUmlIntent, UmlError, type UmlDiagram, type UmlFinding, type UmlIntent, type UmlNotation, type UmlParseResult } from './uml.js'
 import { renderReportText } from './report-view.js'
 
 export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
@@ -22,7 +22,7 @@ export const LOGICPROBE_UML_TOOL_NAME = 'logicprobe_uml'
 export const logicProbeUmlTool = defineTool({
   name: LOGICPROBE_UML_TOOL_NAME,
   description:
-    'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. action="explain-labels" prints the label and comment conventions the parser accepts, without needing a diagram. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Read `verdict`, not `ok`: error findings mean a failed review.',
+    'Model a code flow as UML, and audit the modelling. action="render" turns a LogicModelV1 into diagram source: mermaid (state, activity, sequence) or plantuml (state, sequence). action="parse" reads Mermaid or PlantUML state or activity text back into a LogicModelV1, so a hand-drawn diagram can be verified. A sequence diagram is refused: a trace cannot reconstruct a machine. So is any other diagram family (class, ER, gantt, mindmap). That refusal carries errorCode "UML_NOT_A_STATE_DIAGRAM". A PlantUML component, package or deployment diagram declares no kind, so the parser detects those constructs itself. It returns a by-product model and reports the error UML_NOT_A_STATE_DIAGRAM, with `discardedConstructs` and `discardedEdges`. Never treat that model as a model of the file. action="review" audits the modelling: structural defects (UML002-UML009), documentation gaps (UML010-UML015), and a fidelity check that re-parses the rendered diagram (UML017). Give it a model, a diagram, or both. action="explain-labels" prints the label and comment conventions the parser accepts, without needing a diagram. Rendering never invents structure. A construct the notation cannot express becomes a warning. For dependency questions on a component or class diagram, use `logicprobe_structure_verify` instead. Declare `intent` (present, verify, fidelity) to say what the artifact is for: a view that cannot serve it is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes. Read `verdict`, not `ok`: error findings mean a failed review.',
   parameters: {
     action: {
       type: 'string',
@@ -48,6 +48,11 @@ export const logicProbeUmlTool = defineTool({
       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.',
     },
+    intent: {
+      type: 'string',
+      enum: ['present', 'verify', 'fidelity'],
+      description: 'What the artifact is for, declared up front: present = a human will read the diagram (any view), verify = it must be parseable into a LogicModelV1 for the engine (state or activity), fidelity = the point is the render-and-reparse proof (review only, state or activity). A view that cannot serve the intent is refused before any work, with errorCode UML_INTENT_UNSERVABLE, UML_VIEW_UNREPRESENTABLE or UML_INTENT_MISMATCH. Omit it and nothing changes: a sequence view is still rendered, and review still reports UML019.',
+    },
     roundTrip: {
       type: 'boolean',
       description: 'review only: render and re-parse the model to prove the diagram carries it. Default true.',
@@ -79,11 +84,12 @@ export const logicProbeUmlTool = defineTool({
     try {
       if (args.action === 'render') {
         if (args.model === undefined) return errorResult('action=render needs `model` (a LogicModelV1 object)')
-        const result = renderUml(args.model, (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation, (args.kind ?? 'state') as UmlDiagram, args.maxSteps)
+        const result = renderUml(args.model, (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation, (args.kind ?? 'state') as UmlDiagram, args.maxSteps, args.intent as UmlIntent | undefined)
         return { ok: true, ran: true, ...verdictOf(0, result.warnings.length), schema: REPORT_SCHEMAS.umlRender, action: 'render', notation: result.notation, kind: result.diagram, diagram: result.primary, hashes: { diagram: createHash('sha256').update(result.primary).digest('hex') }, warnings: result.warnings } as unknown as JsonValue
       }
       if (args.action === 'parse') {
         if (args.diagram === undefined) return errorResult('action=parse needs `diagram` (Mermaid or PlantUML text)')
+        checkUmlIntent(args.intent as UmlIntent | undefined, 'parse')
         const result = parseUml(args.diagram, args.notation ?? 'auto')
         // A diagram from another family still parses into *something*. `parseFindings`
         // says so, and the verdict is what stops that something from being trusted:
@@ -109,6 +115,7 @@ export const logicProbeUmlTool = defineTool({
       // R9: the label contract was documented in the library and in `explainLabels()`, but no
       // tool exposed it, so it was reachable only by reading the source or the docs.
       if (args.action === 'explain-labels') {
+        checkUmlIntent(args.intent as UmlIntent | undefined, 'labels')
         const notation = (args.notation === undefined || args.notation === 'auto' ? 'mermaid' : args.notation) as UmlNotation
         return {
           ok: true,
@@ -126,6 +133,7 @@ export const logicProbeUmlTool = defineTool({
         diagramKind: (args.kind ?? 'state') as UmlDiagram,
         roundTrip: args.roundTrip,
         maxSteps: args.maxSteps,
+        intent: args.intent as UmlIntent | undefined,
       })
       return report as unknown as JsonValue
     } catch (error) {

package/src/uml.ts

@@ -42,6 +42,20 @@ export const UML_NOTATIONS: readonly UmlNotation[] = ['mermaid', 'plantuml']
 
 export const UML_DIAGRAMS: readonly UmlDiagram[] = ['state', 'activity', 'sequence']
 
+/**
+ * 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 const UML_INTENTS: readonly UmlIntent[] = ['present', 'verify', 'fidelity']
+
+/** The tool actions, for the entry check. `labels` is `action=explain-labels`. */
+export type UmlIntentAction = 'render' | 'parse' | 'review' | 'labels'
+
 /** Marker every generated diagram carries; renderers ignore it, the parser uses it. */
 const DIRECTIVE_NAMESPACE = 'logicprobe:'
 
@@ -401,26 +415,92 @@ function renderSequence(context: RenderContext, notation: UmlNotation, maxSteps:
   return { text: lines.join('\n') + '\n', truncated }
 }
 
+/** What each action hands back, so a declared intent can be matched against it. */
+const ACTION_PRODUCES: Record<UmlIntentAction, string> = {
+  render: 'a diagram',
+  parse: 'a LogicModelV1 read out of a diagram',
+  review: 'an audit of the modelling',
+  labels: 'the label and comment conventions the parser accepts',
+}
+
+/**
+ * The intents each action can serve.
+ *
+ * `fidelity` is a review job: render produces a diagram, and a diagram nothing has
+ * compared back to its model proves nothing about it.
+ */
+const ACTION_INTENTS: Record<UmlIntentAction, readonly UmlIntent[]> = {
+  render: ['present', 'verify'],
+  parse: ['verify'],
+  review: ['present', 'verify', 'fidelity'],
+  labels: [],
+}
+
+/**
+ * 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 function assertUmlView(notation: UmlNotation, diagram: UmlDiagram): void {
+  if (!UML_NOTATIONS.includes(notation)) throw new UmlError('unknown notation "' + String(notation) + '"; expected ' + UML_NOTATIONS.join(' | '))
+  if (!UML_DIAGRAMS.includes(diagram)) throw new UmlError('unknown diagram "' + String(diagram) + '"; expected ' + UML_DIAGRAMS.join(' | '))
+  if (notation === 'plantuml' && diagram === 'activity') {
+    throw new UmlError('plantuml has no faithful activity view here (its activity syntax is a structured flowchart language; a graph with merges or cycles needs a while/if reconstruction logicprobe does not perform) — use notation "mermaid" for the activity view, or diagram "state"', 'UML_VIEW_UNREPRESENTABLE')
+  }
+}
+
+/**
+ * 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 function checkUmlIntent(intent: UmlIntent | undefined, action: UmlIntentAction, view?: { notation: UmlNotation; diagram: UmlDiagram }): void {
+  if (intent === undefined) return
+  if (!UML_INTENTS.includes(intent)) throw new UmlError('unknown intent "' + String(intent) + '"; expected ' + UML_INTENTS.join(' | '))
+  const served = ACTION_INTENTS[action]
+  if (!served.includes(intent)) {
+    throw new UmlError(
+      'intent "' + intent + '" cannot be served by action=' + action + ', which returns ' + ACTION_PRODUCES[action] + '; it serves ' +
+      (served.length === 0 ? 'no intent — leave `intent` off' : served.join(' | ')),
+      'UML_INTENT_MISMATCH')
+  }
+  if (view === undefined) return
+  assertUmlView(view.notation, view.diagram)
+  if (intent === 'present' || view.diagram !== 'sequence') return
+  throw new UmlError(
+    'intent "' + intent + '" needs a machine, and a sequence view is one BFS trace: ' +
+    (intent === 'fidelity'
+      ? 'the render/parse fidelity check does not apply to a trace, so nothing would be proven. Review kind "state" or "activity" to have the diagram checked against the model, and render the trace separately with intent "present".'
+      : '`parse` refuses a trace because it cannot reconstruct a machine, so the diagram cannot feed verification. Model the machine as a state or activity diagram, and render the trace separately with intent "present".'),
+    'UML_INTENT_UNSERVABLE')
+}
+
 /**
  * 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.
+ * 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 function renderUml(input: unknown, notation: UmlNotation = 'mermaid', diagram: UmlDiagram = 'state', maxSteps = 60): UmlRenderResult {
-  if (!UML_NOTATIONS.includes(notation)) throw new UmlError('unknown notation "' + String(notation) + '"; expected ' + UML_NOTATIONS.join(' | '))
-  if (!UML_DIAGRAMS.includes(diagram)) throw new UmlError('unknown diagram "' + String(diagram) + '"; expected ' + UML_DIAGRAMS.join(' | '))
-  if (notation === 'plantuml' && diagram === 'activity') {
-    throw new UmlError('plantuml has no faithful activity view here (its activity syntax is a structured flowchart language; a graph with merges or cycles needs a while/if reconstruction logicprobe does not perform) — use notation "mermaid" for the activity view, or diagram "state"')
-  }
+export function renderUml(input: unknown, notation: UmlNotation = 'mermaid', diagram: UmlDiagram = 'state', maxSteps = 60, intent?: UmlIntent): UmlRenderResult {
+  assertUmlView(notation, diagram)
+  checkUmlIntent(intent, 'render', { notation, diagram })
   const context = prepareRender(input)
   const warnings = [...context.warnings]
   let primary: string
@@ -1524,6 +1604,8 @@ export interface UmlReviewOptions {
   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
 }
 
 /**
@@ -1549,6 +1631,7 @@ export function reviewUml(options: UmlReviewOptions): UmlReviewReport {
 
   let notation: UmlNotation = options.notation === undefined || options.notation === 'auto' ? 'mermaid' : options.notation
   const kind: UmlDiagram = options.diagramKind ?? 'state'
+  checkUmlIntent(options.intent, 'review', { notation, diagram: kind })
   let model: LogicModelV1 | undefined
   let labels: Record<string, string> | undefined
   let parsed: UmlParseResult | undefined