dsh-model-everything 0.0.0-stage → 0.1.0

package/lib/uml.js

@@ -0,0 +1,2110 @@
+/**
+ * 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
+ * `dsh-model-everything:` 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 `model_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 model-everything-uml
+ */
+import { REPORT_SCHEMAS, validateModel, modelHash, valueHash, metadataKeysOf, narrativeComplete, narrativeCoverageOf, verdictOfFindings, DEFAULT_HASH_SPEC } from './engine.js';
+import { UmlError, UML_FAMILY_IDS, umlCapability, detectUmlNotation, detectUmlFamily, declaredFamily, readUmlDirectives, directiveLine, MERMAID_RESERVED_NODE_IDS, UML_PLAIN_ID, UML_UNSAFE_LABEL, commentPrefix, DIRECTIVE_NAMESPACE, isUmlNotation, UML_NOTATIONS, umlFamilySpec, } from './uml-syntax.js';
+import { useCaseModule, validateUseCaseModel } from './uml-usecase.js';
+import { structureFamilyModule } from './uml-structure.js';
+import { timingModule, validateTimingModel } from './uml-timing.js';
+import { profileModule, validateProfileModel } from './uml-profile.js';
+import { compositeModule, validateCompositeModel } from './uml-composite.js';
+import { communicationModule, validateCommunicationModel } from './uml-communication.js';
+import { interactionOverviewModule, validateInteractionOverviewModel } from './uml-interaction-overview.js';
+export { UmlError, UML_NOTATIONS } from './uml-syntax.js';
+// Internals a white-box test drives directly, because the tool entry points cannot reach
+// them: the model validator and its refusals, and the segment a parse builds. They are
+// exported for the suite, not for callers - the public surface is renderUml/parseUml/
+// reviewUml and the tools built on them.
+export { validateTimingModel, reviewTimingModel, TIMING_FINDING_CODES, parseTiming, renderTiming } from './uml-timing.js';
+export { validateProfileModel, reviewProfileModel, PROFILE_FINDING_CODES, renderProfile, profileModule } from './uml-profile.js';
+export { validateCompositeModel, reviewCompositeModel, COMPOSITE_FINDING_CODES, renderComposite, parseComposite, compositeModule } from './uml-composite.js';
+export { validateCommunicationModel, reviewCommunicationModel, COMMUNICATION_FINDING_CODES, renderCommunication, parseCommunication, communicationModule, communicationSequenceOrder } from './uml-communication.js';
+export { validateInteractionOverviewModel, reviewInteractionOverviewModel, INTERACTION_OVERVIEW_FINDING_CODES, renderInteractionOverview, parseInteractionOverview, interactionOverviewModule } from './uml-interaction-overview.js';
+export const UML_DIAGRAMS = UML_FAMILY_IDS;
+export const UML_INTENTS = ['present', 'verify', 'fidelity'];
+// Notation syntax lives in the engine now. These aliases keep the machine parser
+// reading the way it always did while the engine owns the rules.
+const UNSAFE_LABEL = UML_UNSAFE_LABEL;
+const RESERVED_NODE_IDS = MERMAID_RESERVED_NODE_IDS;
+const PLAIN_ID = UML_PLAIN_ID;
+// UmlError lives in the syntax engine and is re-exported above, so its class identity
+// is the same for every importer and `instanceof` keeps working.
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function literalText(value) {
+    return typeof value === 'boolean' ? String(value) : String(value);
+}
+/** Canonical guard text. Rendering wraps every composite node in parentheses, and the parser flattens same-operator chains, so render∘parse is the identity. */
+export function guardText(node) {
+    if ('variable' in node)
+        return node.variable + ' ' + node.op + ' ' + literalText(node.value);
+    if ('all' in node)
+        return '(' + node.all.map((guard) => guardText(guard)).join(' && ') + ')';
+    if ('any' in node)
+        return '(' + node.any.map((guard) => guardText(guard)).join(' || ') + ')';
+    return '!(' + guardText(node.not) + ')';
+}
+function updatesText(updates) {
+    return updates.map((update) => {
+        const value = update.value ?? (update.op === 'set' ? 0 : 1);
+        if (update.op === 'set')
+            return update.variable + ' := ' + literalText(value);
+        if (update.op === 'inc')
+            return update.variable + ' := ' + update.variable + ' + ' + literalText(value);
+        return update.variable + ' := ' + update.variable + ' - ' + literalText(value);
+    }).join(', ');
+}
+function transitionText(transition) {
+    let text = transition.event;
+    if (transition.guard !== undefined)
+        text += ' [' + guardText(transition.guard) + ']';
+    if (transition.updates !== undefined && transition.updates.length > 0)
+        text += ' / ' + updatesText(transition.updates);
+    return text;
+}
+function displayText(text) {
+    return text.replace(/[\r\n\t]+/g, ' ').replace(/"/g, '\'').trim();
+}
+function prepareRender(input) {
+    const validation = validateModel(input);
+    if (!validation.ok)
+        throw new UmlError('model invalid: ' + validation.errors.join('; '));
+    const model = validation.model;
+    const warnings = [];
+    const used = new Set();
+    const alias = new Map();
+    const display = new Map();
+    for (const state of model.states) {
+        let candidate = state.id;
+        if (!PLAIN_ID.test(candidate)) {
+            candidate = candidate.replace(/[^A-Za-z0-9_]/g, '_');
+            if (candidate === '' || /^[0-9]/.test(candidate))
+                candidate = 'S_' + candidate;
+            warnings.push('UML_RENDER_ID_SANITIZED: state id "' + state.id + '" is not a plain identifier; the diagram draws it as "' + candidate + '" and pins the original with a ' + DIRECTIVE_NAMESPACE + 'alias directive.');
+        }
+        if (RESERVED_NODE_IDS.has(candidate))
+            warnings.push('UML_RENDER_RESERVED_ID: state alias "' + candidate + '" collides with a diagram keyword; Mermaid renders it, but a hand edit may not.');
+        let unique = candidate;
+        let suffix = 2;
+        while (used.has(unique)) {
+            unique = candidate + '_' + String(suffix);
+            suffix += 1;
+        }
+        if (unique !== candidate)
+            warnings.push('UML_RENDER_ALIAS_COLLISION: state id "' + state.id + '" shares an alias with another state; the diagram uses "' + unique + '".');
+        used.add(unique);
+        alias.set(state.id, unique);
+        const meaning = model.narrative?.states?.[state.id];
+        display.set(state.id, meaning === undefined ? state.id : displayText(state.id + '（' + meaning + '）'));
+    }
+    for (const transition of model.transitions) {
+        if (UNSAFE_LABEL.test(transition.event)) {
+            warnings.push('UML_RENDER_LABEL_UNSAFE: event "' + transition.event + '" contains a character (one of [ ] / or a line break) that the diagram label syntax uses; the rendered diagram cannot be read back verbatim.');
+        }
+    }
+    const terminal = new Set(model.states.filter((state) => state.terminal === true).map((state) => state.id));
+    return { model, alias, display, terminal, warnings };
+}
+function directiveLines(notation, diagram, context) {
+    const prefix = notation === 'mermaid' ? '%%' : "'";
+    const lines = [prefix + DIRECTIVE_NAMESPACE + 'uml v1 notation=' + notation + ' diagram=' + diagram];
+    lines.push(prefix + DIRECTIVE_NAMESPACE + 'init ' + context.model.init);
+    const terminals = context.model.states.filter((state) => state.terminal === true).map((state) => state.id);
+    if (terminals.length > 0)
+        lines.push(prefix + DIRECTIVE_NAMESPACE + 'terminal ' + terminals.join(','));
+    for (const state of context.model.states) {
+        if (context.alias.get(state.id) !== state.id) {
+            lines.push(prefix + DIRECTIVE_NAMESPACE + 'alias ' + String(context.alias.get(state.id)) + ' ' + state.id);
+        }
+    }
+    // Variable kinds are not recoverable from the notation: `armed := 1` reads as an
+    // integer assignment whichever kind the model declared, and a variable no guard
+    // reads and no action writes leaves no trace at all. Pinning them keeps the
+    // round trip exact instead of reporting a fidelity loss that is really a
+    // notation limit.
+    for (const variable of context.model.variables ?? []) {
+        lines.push(prefix + DIRECTIVE_NAMESPACE + 'variable ' + variable.name + ' ' + variable.kind);
+    }
+    return lines;
+}
+function groupedTransitions(model) {
+    const order = [];
+    const groups = new Map();
+    for (const transition of model.transitions) {
+        const list = groups.get(transition.from);
+        if (list === undefined) {
+            groups.set(transition.from, [transition]);
+            order.push(transition.from);
+        }
+        else
+            list.push(transition);
+    }
+    return order.map((from) => ({ from, transitions: groups.get(from) ?? [] }));
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+function renderMermaidState(context) {
+    const lines = directiveLines('mermaid', 'state', context);
+    lines.push('stateDiagram-v2');
+    lines.push('  [*] --> ' + String(context.alias.get(context.model.init)));
+    for (const state of context.model.states) {
+        const alias = String(context.alias.get(state.id));
+        const label = context.display.get(state.id) ?? state.id;
+        // Every state is declared, even when its label equals its alias. A state that
+        // no transition touches (an isolated terminal, a start state with no edge yet)
+        // would otherwise leave no trace in the text at all, and the round-trip check
+        // would have to report a loss the notation never caused.
+        lines.push('  state "' + label + '" as ' + alias);
+    }
+    for (const group of groupedTransitions(context.model)) {
+        for (const transition of group.transitions) {
+            lines.push('  ' + String(context.alias.get(transition.from)) + ' --> ' + String(context.alias.get(transition.to)) + ' : ' + transitionText(transition));
+        }
+    }
+    for (const state of context.model.states) {
+        if (state.terminal === true)
+            lines.push('  ' + String(context.alias.get(state.id)) + ' --> [*]');
+    }
+    return lines.join('\n') + '\n';
+}
+function renderPlantUmlState(context) {
+    const lines = ['@startuml'];
+    lines.push(...directiveLines('plantuml', 'state', context));
+    lines.push('[*] --> ' + String(context.alias.get(context.model.init)));
+    for (const state of context.model.states) {
+        const alias = String(context.alias.get(state.id));
+        const label = context.display.get(state.id) ?? state.id;
+        lines.push('state "' + label + '" as ' + alias);
+    }
+    for (const group of groupedTransitions(context.model)) {
+        for (const transition of group.transitions) {
+            lines.push(String(context.alias.get(transition.from)) + ' --> ' + String(context.alias.get(transition.to)) + ' : ' + transitionText(transition));
+        }
+    }
+    for (const state of context.model.states) {
+        if (state.terminal === true)
+            lines.push(String(context.alias.get(state.id)) + ' --> [*]');
+    }
+    lines.push('@enduml');
+    return lines.join('\n') + '\n';
+}
+function renderMermaidActivity(context) {
+    const lines = directiveLines('mermaid', 'activity', context);
+    lines.push('flowchart TD');
+    for (const state of context.model.states) {
+        const alias = String(context.alias.get(state.id));
+        const text = context.display.get(state.id) ?? state.id;
+        lines.push('  ' + alias + (state.terminal === true ? '(["' + text + '"])' : '["' + text + '"]'));
+    }
+    for (const group of groupedTransitions(context.model)) {
+        for (const transition of group.transitions) {
+            lines.push('  ' + String(context.alias.get(transition.from)) + ' -->|"' + transitionText(transition) + '"| ' + String(context.alias.get(transition.to)));
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * One BFS trace of the machine, written as a sequence diagram. A sequence
+ * diagram is a trace by construction — branches are messages with guards, and
+ * the diagram is explicitly capped so a cyclic machine cannot produce an
+ * unbounded file.
+ */
+function renderSequence(context, notation, maxSteps) {
+    const lines = [];
+    if (notation === 'mermaid') {
+        lines.push(...directiveLines('mermaid', 'sequence', context));
+        lines.push('sequenceDiagram');
+        lines.push('  participant ENV as Environment');
+        lines.push('  participant M as Machine');
+    }
+    else {
+        lines.push('@startuml');
+        lines.push(...directiveLines('plantuml', 'sequence', context));
+        lines.push('participant ENV as Environment');
+        lines.push('participant M as Machine');
+    }
+    const byFrom = new Map();
+    for (const transition of context.model.transitions) {
+        const list = byFrom.get(transition.from);
+        if (list === undefined)
+            byFrom.set(transition.from, [transition]);
+        else
+            list.push(transition);
+    }
+    const seen = new Set([context.model.init]);
+    const queue = [context.model.init];
+    const arrow = notation === 'mermaid' ? 'ENV->>M: ' : 'ENV -> M : ';
+    const note = notation === 'mermaid' ? '  Note over M: ' : 'note over M : ';
+    lines.push((notation === 'mermaid' ? '  ' : '') + 'Note over M: init ' + context.model.init);
+    let steps = 0;
+    let truncated = false;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const transition of byFrom.get(current) ?? []) {
+            if (steps >= maxSteps) {
+                truncated = true;
+                break;
+            }
+            steps += 1;
+            const label = transitionText(transition);
+            lines.push((notation === 'mermaid' ? '  ' : '') + arrow + label);
+            lines.push(note + String(context.alias.get(transition.from)) + ' -> ' + String(context.alias.get(transition.to)));
+            if (!seen.has(transition.to)) {
+                seen.add(transition.to);
+                queue.push(transition.to);
+            }
+        }
+        if (truncated)
+            break;
+    }
+    if (notation === 'plantuml')
+        lines.push('@enduml');
+    return { text: lines.join('\n') + '\n', truncated };
+}
+/** What each action hands back, so a declared intent can be matched against it. */
+const ACTION_PRODUCES = {
+    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 = {
+    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.
+ */
+/**
+ * What this build serves for one (notation, family, action) cell.
+ *
+ * The engine decides what the notation can express. The registry decides what this
+ * build implements. A family the table calls faithful but no module serves yet is
+ * refused here, by name, instead of being handed to the wrong parser.
+ */
+function umlFamilyCapability(notation, family, action, options = {}) {
+    const capability = umlCapability(notation, family, action, options);
+    if (!capability.ok)
+        throw new UmlError(capability.message, capability.errorCode);
+    return capability;
+}
+/** Families served by a module of their own rather than by the machine path. */
+const FAMILY_MODULES = {
+    'use-case': useCaseModule,
+    timing: timingModule,
+    profile: profileModule,
+    'composite-structure': compositeModule,
+    communication: communicationModule,
+    'interaction-overview': interactionOverviewModule,
+    class: structureFamilyModule('class'),
+    object: structureFamilyModule('object'),
+    package: structureFamilyModule('package'),
+    component: structureFamilyModule('component'),
+    deployment: structureFamilyModule('deployment'),
+};
+function familyModule(family) {
+    return FAMILY_MODULES[family];
+}
+/**
+ * Refuse a view the requested notation cannot draw, before any work. The entry check
+ * every caller already used now asks the engine and the registry.
+ */
+export function assertUmlView(notation, diagram) {
+    umlFamilyCapability(notation, diagram, 'render');
+}
+/**
+ * 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, action, view) {
+    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.
+ *
+ * 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, notation = 'mermaid', diagram = 'state', maxSteps = 60, intent) {
+    assertUmlView(notation, diagram);
+    const capability = umlFamilyCapability(notation, diagram, 'render');
+    checkUmlIntent(intent, 'render', { notation, diagram });
+    const module = familyModule(diagram);
+    if (module !== undefined) {
+        const rendered = module.render(input, notation, { maxSteps });
+        const warnings = [...(capability.warning === undefined ? [] : [capability.warning]), ...rendered.warnings];
+        return { notation, diagram, primary: rendered.primary, warnings };
+    }
+    const context = prepareRender(input);
+    const warnings = [...context.warnings];
+    let primary;
+    if (diagram === 'state')
+        primary = notation === 'mermaid' ? renderMermaidState(context) : renderPlantUmlState(context);
+    else if (diagram === 'activity')
+        primary = renderMermaidActivity(context);
+    else {
+        const rendered = renderSequence(context, notation, maxSteps);
+        primary = rendered.text;
+        if (rendered.truncated)
+            warnings.push('UML_RENDER_SEQUENCE_TRUNCATED: the trace was capped at ' + String(maxSteps) + ' steps; a sequence diagram is one trace, not the whole machine — use diagram "state" for the full topology.');
+        warnings.push('UML_RENDER_SEQUENCE_IS_TRACE: a sequence diagram shows one BFS trace; branches appear as separate guarded messages and unreachable branches are absent by construction.');
+    }
+    return { notation, diagram, primary, warnings };
+}
+function tokenizeGuard(text) {
+    const tokens = [];
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        if (/\s/.test(char)) {
+            index += 1;
+            continue;
+        }
+        if (char === '(') {
+            tokens.push({ kind: 'lparen', text: char });
+            index += 1;
+            continue;
+        }
+        if (char === ')') {
+            tokens.push({ kind: 'rparen', text: char });
+            index += 1;
+            continue;
+        }
+        if (char === '&' && text[index + 1] === '&') {
+            tokens.push({ kind: 'and', text: '&&' });
+            index += 2;
+            continue;
+        }
+        if (char === '|' && text[index + 1] === '|') {
+            tokens.push({ kind: 'or', text: '||' });
+            index += 2;
+            continue;
+        }
+        if (char === '!') {
+            if (text[index + 1] === '=') {
+                tokens.push({ kind: 'op', text: '!=' });
+                index += 2;
+                continue;
+            }
+            tokens.push({ kind: 'not', text: '!' });
+            index += 1;
+            continue;
+        }
+        const two = text.slice(index, index + 2);
+        if (two === '==' || two === '<=' || two === '>=') {
+            tokens.push({ kind: 'op', text: two });
+            index += 2;
+            continue;
+        }
+        if (char === '<' || char === '>') {
+            tokens.push({ kind: 'op', text: char });
+            index += 1;
+            continue;
+        }
+        if (char === '=') {
+            tokens.push({ kind: 'op', text: '==' });
+            index += 1;
+            continue;
+        }
+        if (/[0-9]/.test(char) || (char === '-' && /[0-9]/.test(text[index + 1] ?? ''))) {
+            let end = index + 1;
+            while (end < text.length && /[0-9]/.test(text[end]))
+                end += 1;
+            tokens.push({ kind: 'number', text: text.slice(index, end) });
+            index = end;
+            continue;
+        }
+        if (/[A-Za-z_]/.test(char)) {
+            let end = index + 1;
+            while (end < text.length && /[A-Za-z0-9_.]/.test(text[end]))
+                end += 1;
+            const word = text.slice(index, end);
+            index = end;
+            if (word === 'and')
+                tokens.push({ kind: 'and', text: word });
+            else if (word === 'or')
+                tokens.push({ kind: 'or', text: word });
+            else if (word === 'not')
+                tokens.push({ kind: 'not', text: word });
+            else if (word === 'true' || word === 'false')
+                tokens.push({ kind: 'boolean', text: word });
+            else
+                tokens.push({ kind: 'ident', text: word });
+            continue;
+        }
+        throw new UmlError('guard text not understood near "' + text.slice(index) + '"');
+    }
+    return tokens;
+}
+class GuardReader {
+    tokens;
+    source;
+    position = 0;
+    constructor(tokens, source) {
+        this.tokens = tokens;
+        this.source = source;
+    }
+    parse() {
+        const node = this.parseOr();
+        if (this.position !== this.tokens.length)
+            throw new UmlError('trailing tokens in guard "' + this.source + '"');
+        return node;
+    }
+    peek() {
+        return this.tokens[this.position];
+    }
+    parseOr() {
+        const parts = [this.parseAnd()];
+        while (this.peek()?.kind === 'or') {
+            this.position += 1;
+            parts.push(this.parseAnd());
+        }
+        return parts.length === 1 ? parts[0] : { any: parts };
+    }
+    parseAnd() {
+        const parts = [this.parseUnary()];
+        while (this.peek()?.kind === 'and') {
+            this.position += 1;
+            parts.push(this.parseUnary());
+        }
+        return parts.length === 1 ? parts[0] : { all: parts };
+    }
+    parseUnary() {
+        if (this.peek()?.kind === 'not') {
+            this.position += 1;
+            return { not: this.parseUnary() };
+        }
+        return this.parsePrimary();
+    }
+    parsePrimary() {
+        const token = this.peek();
+        if (token?.kind === 'lparen') {
+            this.position += 1;
+            const inner = this.parseOr();
+            if (this.peek()?.kind !== 'rparen')
+                throw new UmlError('unbalanced parentheses in guard "' + this.source + '"');
+            this.position += 1;
+            return inner;
+        }
+        if (token?.kind !== 'ident')
+            throw new UmlError('expected a variable name in guard "' + this.source + '"');
+        this.position += 1;
+        const op = this.peek();
+        if (op?.kind !== 'op')
+            throw new UmlError('expected a comparison operator after "' + token.text + '" in guard "' + this.source + '"');
+        this.position += 1;
+        const value = this.peek();
+        if (value?.kind === 'number') {
+            this.position += 1;
+            return { variable: token.text, op: op.text, value: Number(value.text) };
+        }
+        if (value?.kind === 'boolean') {
+            if (op.text !== '==' && op.text !== '!=')
+                throw new UmlError('boolean variable "' + token.text + '" only supports == / != (guard "' + this.source + '")');
+            this.position += 1;
+            return { variable: token.text, op: op.text, value: value.text === 'true' };
+        }
+        throw new UmlError('expected a literal value for "' + token.text + '" in guard "' + this.source + '"');
+    }
+}
+/** Parse a guard expression such as `(retry < 3 && armed == true)`. */
+export function parseGuardText(text) {
+    return new GuardReader(tokenizeGuard(text), text).parse();
+}
+/** Parse a UML action clause such as `retry := retry + 1, armed := true`. */
+export function parseUpdatesText(text, warnings) {
+    const out = [];
+    for (const raw of text.split(',')) {
+        const clause = raw.trim();
+        if (clause === '')
+            continue;
+        const shim = /^([A-Za-z_][A-Za-z0-9_]*)\s*(\+\+|--)$/.exec(clause);
+        if (shim !== null) {
+            out.push({ variable: shim[1], op: shim[2] === '++' ? 'inc' : 'dec', value: 1 });
+            continue;
+        }
+        const assignment = /^([A-Za-z_][A-Za-z0-9_]*)\s*:?=\s*(.+)$/.exec(clause);
+        if (assignment === null)
+            throw new UmlError('action clause not understood: "' + clause + '" (expected "var := value")');
+        const name = assignment[1];
+        const value = assignment[2].trim();
+        if (value === name) {
+            warnings.push('UML_PARSE_NOOP_UPDATE: action "' + clause + '" assigns the variable to itself; dropped.');
+            continue;
+        }
+        if (/^(true|false)$/.test(value)) {
+            out.push({ variable: name, op: 'set', value: value === 'true' ? 1 : 0 });
+            continue;
+        }
+        if (/^-?[0-9]+$/.test(value)) {
+            out.push({ variable: name, op: 'set', value: Number(value) });
+            continue;
+        }
+        const arithmetic = /^([A-Za-z_][A-Za-z0-9_]*)\s*([+-])\s*([0-9]+)$/.exec(value);
+        if (arithmetic === null)
+            throw new UmlError('action value not understood: "' + value + '" (expected a literal, or "var + n" / "var - n")');
+        if (arithmetic[1] !== name)
+            throw new UmlError('action "' + clause + '" reads a different variable; LogicModelV1 updates touch one variable');
+        out.push({ variable: name, op: arithmetic[2] === '+' ? 'inc' : 'dec', value: Number(arithmetic[3]) });
+    }
+    return out;
+}
+function parseTransitionLabel(label, warnings) {
+    let rest = label.trim();
+    let guard;
+    const bracket = rest.indexOf('[');
+    if (bracket >= 0) {
+        const close = rest.lastIndexOf(']');
+        if (close < bracket)
+            throw new UmlError('unbalanced guard brackets in transition label "' + label + '"');
+        guard = parseGuardText(rest.slice(bracket + 1, close).trim());
+        rest = (rest.slice(0, bracket) + ' ' + rest.slice(close + 1)).trim();
+    }
+    let updates;
+    const slash = rest.indexOf('/');
+    if (slash >= 0) {
+        const actionText = rest.slice(slash + 1).trim();
+        updates = parseUpdatesText(actionText, warnings);
+        if (updates.length === 0)
+            updates = undefined;
+        rest = rest.slice(0, slash).trim();
+    }
+    const event = rest.trim();
+    if (event === '')
+        throw new UmlError('transition label "' + label + '" carries no event name; label the arrow as `event [guard] / actions`');
+    return { event, ...(guard === undefined ? {} : { guard }), ...(updates === undefined ? {} : { updates }) };
+}
+/**
+ * The machine families' view of the engine's directive reader: the same dsh-model-everything:
+ * lines, arranged the way the state parser wants them.
+ */
+function readDirectives(lines, notation) {
+    const read = readUmlDirectives(lines, notation);
+    const directives = { terminals: [], aliases: new Map(), variables: new Map(), declared: read.declared };
+    for (const value of read.values.get('init') ?? [])
+        if (value !== '')
+            directives.init = value;
+    for (const value of read.values.get('terminal') ?? []) {
+        for (const id of value.split(',')) {
+            const trimmed = id.trim();
+            if (trimmed !== '')
+                directives.terminals.push(trimmed);
+        }
+    }
+    for (const value of read.values.get('alias') ?? []) {
+        const split = value.indexOf(' ');
+        if (split > 0)
+            directives.aliases.set(value.slice(0, split).trim(), value.slice(split + 1).trim());
+    }
+    for (const value of read.values.get('variable') ?? []) {
+        const split = value.lastIndexOf(' ');
+        if (split > 0) {
+            const kind = value.slice(split + 1).trim();
+            if (kind === 'integer' || kind === 'boolean')
+                directives.variables.set(value.slice(0, split).trim(), kind);
+        }
+    }
+    // A directive this family does not define must not vanish: it goes back into the
+    // body, where the parser reports it as a line it could not read.
+    const known = new Set(['init', 'terminal', 'alias', 'variable']);
+    const body = [...read.body];
+    for (const key of [...read.values.keys()].sort()) {
+        if (known.has(key))
+            continue;
+        for (const value of read.values.get(key) ?? [])
+            body.push(directiveLine(notation, key + (value === '' ? '' : ' ' + value)));
+    }
+    return { directives, ...(read.declared.diagram === undefined ? {} : { kindHint: read.declared.diagram }), body };
+}
+function rawToModel(raw, directives, warnings) {
+    // Alias directives restore ids the notation cannot spell; they win over the
+    // alias itself, which is the whole reason the renderer writes them.
+    const idOf = (name) => directives.aliases.get(name) ?? name;
+    const names = [];
+    const seenNames = new Set();
+    const addName = (name) => {
+        if (name === undefined || seenNames.has(name))
+            return;
+        seenNames.add(name);
+        names.push(name);
+    };
+    for (const name of raw.states)
+        addName(name);
+    // A state can be known without ever being an edge endpoint: the initial
+    // pseudostate (`[*] --> X`) and the final mark (`Y --> [*]`) both name states a
+    // hand-written diagram never declares, and an isolated state has no edge at all.
+    addName(raw.initialState);
+    for (const name of raw.finalMarks)
+        addName(name);
+    for (const name of raw.terminals)
+        addName(name);
+    for (const edge of raw.edges) {
+        addName(edge.from);
+        addName(edge.to);
+    }
+    const states = [];
+    const seenStates = new Set();
+    for (const name of names) {
+        const id = idOf(name);
+        if (seenStates.has(id))
+            continue;
+        seenStates.add(id);
+        states.push({ id });
+    }
+    const transitions = [];
+    const synthetic = new Set();
+    for (const edge of raw.edges) {
+        const from = idOf(edge.from);
+        const to = idOf(edge.to);
+        const label = edge.label.trim();
+        let event;
+        let guard;
+        let updates;
+        if (label === '') {
+            let candidate = 't_' + from + '_' + to;
+            let suffix = 2;
+            while (synthetic.has(candidate)) {
+                candidate = 't_' + from + '_' + to + '_' + String(suffix);
+                suffix += 1;
+            }
+            synthetic.add(candidate);
+            event = candidate;
+            warnings.push('UML_PARSE_SYNTHETIC_EVENT: arrow ' + from + ' -> ' + to + ' carries no label; it was named "' + candidate + '". Label the arrow as `event [guard] / actions` so the model keeps the real event name.');
+        }
+        else {
+            const parsed = parseTransitionLabel(label, warnings);
+            event = parsed.event;
+            guard = parsed.guard;
+            updates = parsed.updates;
+        }
+        transitions.push({ from, event, to, ...(guard === undefined ? {} : { guard }), ...(updates === undefined ? {} : { updates }) });
+    }
+    // Init: an explicit `[*] --> X` wins; a directive is the fallback the activity
+    // view needs (a flowchart has no initial pseudostate).
+    let init = raw.initialState === undefined ? undefined : idOf(raw.initialState);
+    if (init === undefined && directives.init !== undefined)
+        init = idOf(directives.init);
+    if (raw.initialState !== undefined && directives.init !== undefined && idOf(raw.initialState) !== directives.init) {
+        warnings.push('UML_PARSE_INIT_CONFLICT: the diagram enters ' + idOf(raw.initialState) + ' from its initial pseudostate but declares init ' + directives.init + '; the pseudostate wins.');
+    }
+    if (init === undefined) {
+        const targeted = new Set(transitions.map((transition) => transition.to));
+        const roots = states.map((state) => state.id).filter((id) => !targeted.has(id));
+        if (roots.length === 1) {
+            init = roots[0];
+            warnings.push('UML_PARSE_INIT_INFERRED: no initial state was declared; "' + init + '" is the only state nothing enters, so it is used as init.');
+        }
+        else {
+            throw new UmlError('no initial state: add `[*] --> <state>` (or a `' + DIRECTIVE_NAMESPACE + 'init <state>` directive); found ' + String(roots.length) + ' entry states');
+        }
+    }
+    const terminalNames = new Set(raw.terminals.map((name) => idOf(name)));
+    for (const name of directives.terminals)
+        terminalNames.add(idOf(name));
+    for (const name of raw.finalMarks)
+        terminalNames.add(idOf(name));
+    for (const state of states)
+        if (terminalNames.has(state.id))
+            state.terminal = true;
+    const variables = inferVariables(transitions, directives.variables);
+    const model = {
+        schemaVersion: 1,
+        init,
+        states,
+        transitions,
+        ...(variables.length === 0 ? {} : { variables }),
+    };
+    const validation = validateModel(model);
+    if (!validation.ok)
+        throw new UmlError('the diagram parsed into an invalid model: ' + validation.errors.join('; '));
+    return validation.model;
+}
+/**
+ * Recover the variable list from the diagram. A `dsh-model-everything:variable` directive
+ * wins, because the notation itself cannot tell `armed := 1` on a boolean from an
+ * integer assignment; guards and actions are the fallback for hand-written text.
+ */
+function inferVariables(transitions, declared) {
+    const kinds = new Map(declared);
+    const note = (name, kind) => {
+        if (declared.has(name))
+            return;
+        const current = kinds.get(name);
+        if (current === undefined)
+            kinds.set(name, kind);
+        else if (current !== kind)
+            kinds.set(name, 'integer');
+    };
+    const walk = (guard) => {
+        if (guard === undefined)
+            return;
+        if ('variable' in guard) {
+            note(guard.variable, typeof guard.value === 'boolean' ? 'boolean' : 'integer');
+            return;
+        }
+        if ('all' in guard) {
+            for (const child of guard.all)
+                walk(child);
+            return;
+        }
+        if ('any' in guard) {
+            for (const child of guard.any)
+                walk(child);
+            return;
+        }
+        walk(guard.not);
+    };
+    for (const transition of transitions) {
+        walk(transition.guard);
+        for (const update of transition.updates ?? [])
+            note(update.variable, 'integer');
+    }
+    return [...kinds.entries()].map(([name, kind]) => ({ name, kind, init: kind === 'boolean' ? false : 0 }));
+}
+/**
+ * PlantUML keywords that declare a construct LogicModelV1 has no place for. Their
+ * presence marks the text as a component, package, class, deployment or database
+ * diagram — a different diagram family. A state parser still reads *something* out of
+ * such a file (the arrows look like transitions), which is why the discarded
+ * declarations are collected and reported instead of being ignored.
+ */
+const PLANTUML_OTHER_CONSTRUCT = /^(component|package|class|interface|enum|enumeration|object|actor|usecase|node|artifact|database|rectangle|folder|frame|cloud|storage|collections|queue|stack|agent|boundary|control|entity|deployment|protocol|struct|exception|metaclass|stereotype|circle|hexagon|label|port|portin|portout)\b/i;
+/** The node identifier a declaration introduces, when it has one (`… as ID`, or a bare `component ID`). */
+function declaredIdentifier(text) {
+    const alias = /\bas\s+([A-Za-z_][A-Za-z0-9_]*)\s*;?$/.exec(text);
+    if (alias !== null)
+        return alias[1];
+    const bare = /^[A-Za-z]+\s+([A-Za-z_][A-Za-z0-9_]*)\s*;?$/.exec(text);
+    return bare === null ? undefined : bare[1];
+}
+/**
+ * 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 function parseFindings(parsed) {
+    // A note block is reported in `discardedConstructs` for transparency, but it does not make
+    // the text "not a state diagram": the rest of the file still is one, so only the constructs
+    // that actually replace a state declaration count towards the refusal.
+    const unsupported = parsed.discardedConstructs.filter((entry) => entry.construct !== 'note');
+    if (unsupported.length === 0)
+        return [];
+    const counts = new Map();
+    for (const entry of unsupported)
+        counts.set(entry.construct, (counts.get(entry.construct) ?? 0) + 1);
+    const summary = [...counts.entries()]
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([construct, count]) => construct + ' ×' + String(count))
+        .join(', ');
+    const shown = unsupported.slice(0, 12).map((entry) => 'line ' + String(entry.line) + ': ' + entry.text).join(' | ');
+    return [{
+            code: 'UML_NOT_A_STATE_DIAGRAM',
+            severity: 'error',
+            message: 'the text is not a state or activity diagram: ' + String(unsupported.length) + ' declaration(s) of unsupported construct(s) (' + summary + ') and ' + String(parsed.discardedEdges) + ' arrow(s) between them were read as states and transitions, so the parsed model is not this diagram.',
+            detail: shown + (unsupported.length > 12 ? ' | … ' + String(unsupported.length - 12) + ' more' : ''),
+        }];
+}
+function parseStateDiagram(text, notation) {
+    const lines = text.split(/\r?\n/);
+    const { directives, body } = readDirectives(lines, notation);
+    const raw = { states: [], display: new Map(), edges: [], terminals: [], finalMarks: [], warnings: [], discarded: [], discardedNodes: new Set() };
+    let discardedEdges = 0;
+    const declared = new Set();
+    const declare = (name) => { if (!declared.has(name)) {
+        declared.add(name);
+        raw.states.push(name);
+    } };
+    const skip = notation === 'mermaid'
+        ? /^(stateDiagram|stateDiagram-v2|direction\b|classDef\b|class\b|style\b|linkStyle\b|click\b|hide\b|scale\b|title\b|accTitle\b|accDescr\b|%%\{)/
+        : /^(@startuml|@enduml|scale\b|skinparam\b|title\b|hide\b|left to right direction|top to bottom direction|autonumber|!theme)/;
+    let inNote = false;
+    body.forEach((rawLine, index) => {
+        const line = rawLine.trim();
+        if (line === '' || (line.startsWith('--') && !line.includes('-->')))
+            return;
+        if (skip.test(line))
+            return;
+        const noteStart = /^note\b/i.test(line);
+        const noteEnd = /^end\s*note$/i.test(line);
+        if (notation === 'plantuml' && !inNote && !noteStart && !noteEnd) {
+            const other = PLANTUML_OTHER_CONSTRUCT.exec(line);
+            if (other !== null) {
+                raw.discarded.push({ construct: other[1].toLowerCase(), line: index + 1, text: line });
+                const id = declaredIdentifier(line);
+                if (id !== undefined)
+                    raw.discardedNodes.add(id);
+                return;
+            }
+        }
+        if (noteEnd) {
+            inNote = false;
+            return;
+        }
+        // A multi-line note body is prose, not a statement: skip it silently rather than
+        // reporting one ignored line per line of text.
+        if (inNote)
+            return;
+        if (noteStart && !/:\s*.+$/.test(line)) {
+            // R7: a multi-line note block is prose the notation carries and LogicModelV1 does not.
+            // Its body is still skipped line by line, but the block itself is NOT silent: it is
+            // reported once, like any other unsupported construct, so "the diagram hash changed and
+            // the report said nothing" cannot happen. It stays out of `warnings` (no per-line noise)
+            // and `parseFindings` keeps it out of the "not a state diagram" verdict.
+            raw.discarded.push({ construct: 'note', line: index + 1, text: line });
+            inNote = true;
+            return;
+        }
+        const note = /^note\s+(?:over|right of|left of)\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.+)$/i.exec(line);
+        if (note !== null) {
+            declare(note[1]);
+            const existing = raw.display.get(note[1]);
+            if (existing === undefined)
+                raw.display.set(note[1], note[2].trim());
+            return;
+        }
+        if (noteStart)
+            return;
+        const stateDecl = /^state\s+"([^"]*)"\s+as\s+([A-Za-z_][A-Za-z0-9_]*)$/.exec(line);
+        if (stateDecl !== null) {
+            declare(stateDecl[2]);
+            raw.display.set(stateDecl[2], stateDecl[1]);
+            return;
+        }
+        const bareState = /^state\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{?$/.exec(line);
+        if (bareState !== null) {
+            declare(bareState[1]);
+            return;
+        }
+        const concurrency = /^\}\s*$|^--\s*$/.test(line);
+        if (concurrency) {
+            raw.warnings.push('UML_PARSE_CONCURRENCY_FLATTENED: a concurrency region or composite block was flattened; LogicModelV1 has no region construct (use model_compose_verify for parallel machines).');
+            return;
+        }
+        const composite = /^state\s+(.+)\s*\{$/.exec(line);
+        if (composite !== null) {
+            raw.warnings.push('UML_PARSE_COMPOSITE_FLATTENED: composite state "' + composite[1].trim() + '" was flattened into its members.');
+            return;
+        }
+        const description = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.+)$/.exec(line);
+        if (description !== null) {
+            declare(description[1]);
+            if (!raw.display.has(description[1]))
+                raw.display.set(description[1], description[2].trim());
+            return;
+        }
+        const edge = /^(.+?)\s*-->\s*(.+?)(?:\s*:\s*(.*))?$/.exec(line);
+        if (edge !== null) {
+            const from = edge[1].trim();
+            const to = edge[2].trim();
+            const label = (edge[3] ?? '').trim();
+            if (from === '[*]') {
+                if (raw.initialState !== undefined && raw.initialState !== to) {
+                    raw.warnings.push('UML_PARSE_MULTIPLE_INIT: the diagram enters ' + raw.initialState + ' and ' + to + ' from initial pseudostates; LogicModelV1 has one init, so ' + raw.initialState + ' is kept.');
+                }
+                else {
+                    raw.initialState = to;
+                }
+                return;
+            }
+            if (to === '[*]') {
+                raw.finalMarks.push(from);
+                return;
+            }
+            declare(from);
+            declare(to);
+            if (raw.discardedNodes.has(from) || raw.discardedNodes.has(to))
+                discardedEdges += 1;
+            raw.edges.push({ from, to, label });
+            return;
+        }
+        raw.warnings.push('UML_PARSE_IGNORED_LINE: "' + line + '" is not a state diagram statement; it was ignored.');
+    });
+    const model = rawToModel(raw, directives, raw.warnings);
+    const labels = mapLabels(raw.display, directives);
+    return { notation, diagram: 'state', family: 'state', model, labels, discardedConstructs: raw.discarded, discardedEdges, warnings: raw.warnings };
+}
+function parseActivityDiagram(text, notation) {
+    const lines = text.split(/\r?\n/);
+    const { directives, body } = readDirectives(lines, notation);
+    const raw = { states: [], display: new Map(), edges: [], terminals: [], finalMarks: [], warnings: [], discarded: [], discardedNodes: new Set() };
+    const declared = new Set();
+    const declare = (name) => { if (!declared.has(name)) {
+        declared.add(name);
+        raw.states.push(name);
+    } };
+    const skip = /^(flowchart|graph)\b|^(classDef|class|style|linkStyle|click|direction)\b|^%%\{/;
+    let inSubgraph = false;
+    for (const rawLine of body) {
+        const line = rawLine.trim();
+        if (line === '' || skip.test(line))
+            continue;
+        if (/^subgraph\b/.test(line)) {
+            if (!inSubgraph) {
+                inSubgraph = true;
+                raw.warnings.push('UML_PARSE_SUBGRAPH_FLATTENED: subgraph blocks were flattened; LogicModelV1 has no hierarchy.');
+            }
+            continue;
+        }
+        if (line === 'end') {
+            inSubgraph = false;
+            continue;
+        }
+        const shaped = /^(.*?)\s*-->\s*\|(.*?)\|\s*(.+)$/.exec(line);
+        const bare = shaped === null ? /^(.*?)\s*-->\s*(.+)$/.exec(line) : null;
+        if (shaped !== null || bare !== null) {
+            const match = (shaped ?? bare);
+            const from = stripNode(match[1].trim(), raw, declare);
+            // Flowchart labels live between bars; the state-diagram form `A --> B : label`
+            // is accepted too so a hand-written file that mixes the two still reads.
+            let rawTo = (shaped === null ? match[2] : match[3]).trim();
+            let label = shaped === null ? '' : shaped[2].replace(/^"|"$/g, '').trim();
+            if (shaped === null) {
+                const colon = rawTo.indexOf(':');
+                if (colon >= 0) {
+                    label = rawTo.slice(colon + 1).trim().replace(/^"|"$/g, '');
+                    rawTo = rawTo.slice(0, colon).trim();
+                }
+            }
+            const to = stripNode(rawTo, raw, declare);
+            if (from === undefined || to === undefined)
+                continue;
+            raw.edges.push({ from, to, label });
+            continue;
+        }
+        const node = stripNode(line, raw, declare);
+        if (node === undefined)
+            raw.warnings.push('UML_PARSE_IGNORED_LINE: "' + line + '" is not a flowchart statement; it was ignored.');
+    }
+    const model = rawToModel(raw, directives, raw.warnings);
+    const labels = mapLabels(raw.display, directives);
+    return { notation, diagram: 'activity', family: 'activity', model, labels, discardedConstructs: [], discardedEdges: 0, warnings: raw.warnings };
+}
+/**
+ * Read one node reference (`A`, `A["label"]`, `A(["label"])`) and register the id
+ * plus any display label it carries. Returns the node name, or undefined when the
+ * text is not a node reference at all.
+ */
+function stripNode(text, raw, declare) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return undefined;
+    const match = /^([A-Za-z_][A-Za-z0-9_.-]*)\s*(\(\[|\[\(|\{\{|\[|\(|\(\(|>)?\s*([\s\S]*?)\s*$/.exec(trimmed);
+    if (match === null) {
+        const quoted = /^"([^"]+)"$/.exec(trimmed);
+        if (quoted !== null) {
+            declare(quoted[1]);
+            return quoted[1];
+        }
+        return undefined;
+    }
+    const name = match[1];
+    const shape = match[2] ?? '';
+    const rest = match[3] ?? '';
+    declare(name);
+    const quoted = /"([^"]*)"/.exec(rest);
+    const label = quoted !== null ? quoted[1].trim() : rest.replace(/^[\[\](){}>]+/, '').replace(/[\[\](){}>]+$/, '').trim();
+    if (label !== '' && !raw.display.has(name))
+        raw.display.set(name, label);
+    if (shape === '([' || shape === '((' || rest.startsWith('(['))
+        raw.terminals.push(name);
+    return name;
+}
+function mapLabels(display, directives) {
+    const out = {};
+    for (const [name, label] of display)
+        out[directives.aliases.get(name) ?? name] = label;
+    return out;
+}
+/**
+ * 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 function explainLabels(notation = 'mermaid') {
+    const prefix = commentPrefix(notation);
+    return {
+        notation,
+        directivePrefix: prefix + DIRECTIVE_NAMESPACE,
+        directiveLines: [
+            { example: prefix + DIRECTIVE_NAMESPACE + 'uml v1 notation=' + notation + ' diagram=state', meaning: 'declares the notation and diagram kind the file was rendered for' },
+            { example: prefix + DIRECTIVE_NAMESPACE + 'init ID', meaning: 'pins the initial state (otherwise it is inferred as the only state nothing enters)' },
+            { example: prefix + DIRECTIVE_NAMESPACE + 'terminal ID', meaning: 'marks a terminal state; comma-separate several' },
+            { example: prefix + DIRECTIVE_NAMESPACE + 'alias NOTATION_ID model_id', meaning: 'restores a state id the notation cannot spell verbatim' },
+            { example: prefix + DIRECTIVE_NAMESPACE + 'variable NAME integer', meaning: 'restores a variable and its kind' },
+        ],
+        acceptedLabelForms: [
+            { form: 'bare id', example: 'state "IDLE" as IDLE', note: 'counts as NO meaning: the state stays undocumented (UML014)' },
+            { form: 'ID（meaning）', example: 'state "IDLE（waiting for power）" as IDLE', note: 'the form the renderer writes; full-width parentheses' },
+            { form: 'ID(meaning)', example: 'state "IDLE(waiting for power)" as IDLE', note: 'accepted as well' },
+            { form: 'a description line', example: 'IDLE : waiting for power', note: 'the same meaning written as a state description' },
+            { form: 'a single-line note', example: 'note right of IDLE : waiting for power', note: 'read as the state meaning, not as a comment' },
+            { form: 'any other text', example: 'state "waiting for power" as IDLE', note: 'taken as the meaning verbatim' },
+        ],
+        renderedForm: 'state "ID（meaning）" as ID',
+        ignoredLines: [
+            { pattern: 'a `' + prefix + '` comment line that is not a `dsh-model-everything:` directive', behaviour: 'UML_PARSE_IGNORED_LINE warning: it carries no state-machine statement' },
+            { pattern: 'a `note …` block written over several lines', behaviour: 'its body is skipped line by line (prose, not a statement) and the block itself is reported once in discardedConstructs' },
+            { pattern: 'notation chrome: @startuml/@enduml, stateDiagram-v2, direction, classDef/style/linkStyle/click, scale, skinparam, title, hide, autonumber', behaviour: 'skipped silently' },
+            { pattern: 'anything else the parser cannot read', behaviour: 'UML_PARSE_IGNORED_LINE warning, and the model is built from what it did read' },
+        ],
+        rules: [
+            'Label drift (UML015) compares the meaning inside the label with narrative.states[id]: the wrapper is stripped, the remaining text must match character for character.',
+            'A meaning that differs only in wording is still drift — one of the two is stale, and the review cannot tell which.',
+            'Keep non-directive comments out of the diagram: `dsh-model-everything:` directives are the only comment lines the parser consumes.',
+            'A missing label is not an error: the state renders as its bare id and is reported as undocumented (UML014).',
+        ],
+    };
+}
+/**
+ * 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 function parseUml(text, notation = 'auto') {
+    const resolved = notation === 'auto' ? detectUmlNotation(text) : notation;
+    const hint = declaredFamily(readUmlDirectives(text.split(/\r?\n/), resolved));
+    const detection = detectUmlFamily(text, resolved, hint === undefined ? {} : { hint });
+    const family = detection.family;
+    const capability = umlCapability(resolved, family, 'parse');
+    if (!capability.ok)
+        throw new UmlError(capability.message, capability.errorCode);
+    if (family === 'state' || family === 'activity') {
+        return family === 'state' ? parseStateDiagram(text, resolved) : parseActivityDiagram(text, resolved);
+    }
+    const module = familyModule(family);
+    if (module === undefined) {
+        throw new UmlError('this text is a ' + umlFamilySpec(family).name + ' (' + detection.evidence + '), and this build has no module for it yet: reading it with the state parser would produce a model of a different diagram. Use uml_structure_verify when the question is where the dependencies point, or render the diagram you mean with uml action=render.', 'UML_NOT_A_STATE_DIAGRAM');
+    }
+    const parsed = module.parse(text, resolved);
+    return { notation: resolved, diagram: family, family, model: parsed.model, labels: parsed.labels, discardedConstructs: parsed.discardedConstructs, discardedEdges: parsed.discardedEdges, warnings: parsed.warnings };
+}
+// ---------------------------------------------------------------------------
+// Review
+// ---------------------------------------------------------------------------
+function reachableStates(model) {
+    const adjacency = new Map();
+    for (const transition of model.transitions) {
+        const list = adjacency.get(transition.from);
+        if (list === undefined)
+            adjacency.set(transition.from, [transition.to]);
+        else
+            list.push(transition.to);
+    }
+    const visited = new Set([model.init]);
+    const queue = [model.init];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const next of adjacency.get(current) ?? []) {
+            if (!visited.has(next)) {
+                visited.add(next);
+                queue.push(next);
+            }
+        }
+    }
+    return visited;
+}
+function canonicalTransition(transition) {
+    return transition.from + '|' + transition.event + '|' + transition.to + '|' + (transition.guard === undefined ? '' : guardText(transition.guard)) + '|' + (transition.updates === undefined ? '' : updatesText(transition.updates));
+}
+/** The narrative meaning a diagram label carries, if it carries one beyond the bare id. */
+function documentedMeaning(label, id) {
+    if (label === undefined)
+        return undefined;
+    const trimmed = label.trim();
+    if (trimmed === '' || trimmed === id)
+        return undefined;
+    for (const [open, close] of [['（', '）'], ['(', ')']]) {
+        const prefix = id + open;
+        if (trimmed.startsWith(prefix) && trimmed.endsWith(close))
+            return trimmed.slice(prefix.length, trimmed.length - close.length);
+    }
+    return trimmed;
+}
+function structuralFindings(model, labels, warnings) {
+    const findings = [];
+    const reachable = reachableStates(model);
+    const outgoing = new Map();
+    for (const transition of model.transitions) {
+        const list = outgoing.get(transition.from);
+        if (list === undefined)
+            outgoing.set(transition.from, [transition]);
+        else
+            list.push(transition);
+    }
+    const unreachable = model.states.map((state) => state.id).filter((id) => !reachable.has(id));
+    if (unreachable.length > 0) {
+        findings.push({
+            code: 'UML002_UNREACHABLE_STATE',
+            severity: 'error',
+            message: unreachable.length + ' state(s) cannot be entered from init along any transition, so the diagram draws flow nobody can reach.',
+            states: unreachable,
+            detail: 'Structural reachability (guards ignored). Guard-aware reachability is S1 in model_verify.',
+        });
+    }
+    const deadEnds = model.states.filter((state) => state.terminal !== true && (outgoing.get(state.id) ?? []).length === 0).map((state) => state.id);
+    if (deadEnds.length > 0) {
+        findings.push({
+            code: 'UML003_DEAD_END_STATE',
+            severity: 'error',
+            message: deadEnds.length + ' non-terminal state(s) have no outgoing transition: the flow stops there without a modelled terminal.',
+            states: deadEnds,
+            detail: 'Either the state is terminal (add `X --> [*]`) or the outgoing flow is missing from the model. model_verify S2 reports the same shape at runtime granularity.',
+        });
+    }
+    const groups = new Map();
+    for (const transition of model.transitions) {
+        const key = transition.from + '\u0000' + transition.event;
+        const list = groups.get(key);
+        if (list === undefined)
+            groups.set(key, [transition]);
+        else
+            list.push(transition);
+    }
+    const ambiguous = [];
+    const overlapping = [];
+    const inexhaustive = [];
+    const probablyExhaustive = [];
+    const complementary = [];
+    for (const group of groups.values()) {
+        const unguarded = group.filter((transition) => transition.guard === undefined);
+        const guarded = group.filter((transition) => transition.guard !== undefined);
+        if (unguarded.length > 1) {
+            for (const transition of unguarded)
+                ambiguous.push({ from: transition.from, event: transition.event, to: transition.to });
+        }
+        const seenGuards = new Map();
+        for (const transition of guarded) {
+            const text = guardText(transition.guard);
+            const previous = seenGuards.get(text);
+            if (previous !== undefined)
+                overlapping.push({ from: transition.from, event: transition.event, to: transition.to });
+            else
+                seenGuards.set(text, transition);
+        }
+        if (guarded.length > 0 && unguarded.length === 0) {
+            const row = { from: group[0].from, event: group[0].event, to: group[0].to };
+            // A complementary pair on one variable (`x < 3` / `x >= 3`) is exhaustive for
+            // any valuation, so the structural warning would be a false alarm there. The
+            // pair test is deliberately narrow — it cannot prove exhaustiveness, only
+            // recognise the common shape, which is why the finding stays on the report at
+            // info severity and still routes to S6.
+            const witness = complementaryVariable(guarded.map((transition) => transition.guard));
+            if (witness === undefined)
+                inexhaustive.push(row);
+            else {
+                probablyExhaustive.push(row);
+                complementary.push(witness);
+            }
+        }
+    }
+    if (ambiguous.length > 0) {
+        findings.push({
+            code: 'UML004_AMBIGUOUS_BRANCH',
+            severity: 'error',
+            message: ambiguous.length + ' branch(es) share a (state, event) with no guard at all: the diagram shows two unconditional arrows for one event, which no reader can resolve.',
+            transitions: ambiguous,
+            detail: 'Keep one unguarded branch per (state, event) as the else case, and guard the others. model_verify S4 is the authoritative determinism check.',
+        });
+    }
+    if (overlapping.length > 0) {
+        findings.push({
+            code: 'UML005_OVERLAPPING_GUARD',
+            severity: 'warning',
+            message: overlapping.length + ' transition(s) repeat a guard already used by another branch of the same (state, event).',
+            transitions: overlapping,
+        });
+    }
+    if (inexhaustive.length > 0) {
+        findings.push({
+            code: 'UML006_INEXHAUSTIVE_BRANCH',
+            severity: 'warning',
+            message: inexhaustive.length + ' (state, event) group(s) have only guarded branches and no default: if every guard is false the flow vanishes, and the diagram still implies coverage.',
+            transitions: inexhaustive,
+            detail: 'Add an unguarded else branch, or confirm exhaustiveness with model_verify S6 (which evaluates guards over real valuations).',
+        });
+    }
+    if (probablyExhaustive.length > 0) {
+        findings.push({
+            code: 'UML006_INEXHAUSTIVE_BRANCH',
+            severity: 'info',
+            message: probablyExhaustive.length + ' (state, event) group(s) have guards that look complementary on ' + [...new Set(complementary)].join(', ') + ', so they are probably exhaustive — but no default branch exists and only model_verify S6 can settle it.',
+            transitions: probablyExhaustive,
+        });
+    }
+    const eventsByReachable = new Set();
+    const eventsAnywhere = new Set();
+    for (const transition of model.transitions) {
+        eventsAnywhere.add(transition.event);
+        if (reachable.has(transition.from))
+            eventsByReachable.add(transition.event);
+    }
+    const deadEvents = [...eventsAnywhere].filter((event) => !eventsByReachable.has(event));
+    if (deadEvents.length > 0) {
+        findings.push({
+            code: 'UML007_UNUSED_EVENT',
+            severity: 'warning',
+            message: deadEvents.length + ' event(s) only fire from states nothing can reach, so the diagram shows messages that never arrive.',
+            events: deadEvents,
+        });
+    }
+    const selfLoops = model.transitions.filter((transition) => transition.from === transition.to && transition.guard === undefined
+        && (outgoing.get(transition.from) ?? []).length === 1);
+    if (selfLoops.length > 0) {
+        findings.push({
+            code: 'UML008_SELF_LOOP_NO_EXIT',
+            severity: 'warning',
+            message: selfLoops.length + ' state(s) have a single unguarded self-loop and no exit: the flow can never leave, which the diagram presents as activity.',
+            states: [...new Set(selfLoops.map((transition) => transition.from))],
+            detail: 'model_verify S3 reports absorbing cycles (liveness).',
+        });
+    }
+    const seenTransitions = new Map();
+    for (const transition of model.transitions) {
+        const key = canonicalTransition(transition);
+        seenTransitions.set(key, (seenTransitions.get(key) ?? 0) + 1);
+    }
+    const duplicates = model.transitions.filter((transition) => (seenTransitions.get(canonicalTransition(transition)) ?? 0) > 1);
+    if (duplicates.length > 0) {
+        findings.push({
+            code: 'UML009_DUPLICATE_TRANSITION',
+            severity: 'warning',
+            message: duplicates.length + ' transition(s) duplicate an identical (from, event, guard, actions, to) row; the diagram draws the same arrow twice.',
+            transitions: duplicates.map((transition) => ({ from: transition.from, event: transition.event, to: transition.to })),
+        });
+    }
+    const guardVariables = new Set();
+    for (const transition of model.transitions) {
+        if (transition.guard !== undefined)
+            collectGuardVariables(transition.guard, guardVariables);
+    }
+    const updatedVariables = new Set();
+    for (const transition of model.transitions)
+        for (const update of transition.updates ?? [])
+            updatedVariables.add(update.variable);
+    const unusedVariables = (model.variables ?? []).map((variable) => variable.name).filter((name) => !guardVariables.has(name) && !updatedVariables.has(name));
+    if (unusedVariables.length > 0) {
+        findings.push({
+            code: 'UML010_UNUSED_VARIABLE',
+            severity: 'warning',
+            message: unusedVariables.length + ' variable(s) are never read by a guard and never written: the diagram carries a symbol with no source.',
+            events: unusedVariables,
+        });
+    }
+    const unbounded = (model.variables ?? []).filter((variable) => variable.kind === 'integer' && (variable.min === undefined || variable.max === undefined)).map((variable) => variable.name);
+    if (unbounded.length > 0) {
+        findings.push({
+            code: 'UML011_UNBOUNDED_VARIABLE',
+            severity: 'info',
+            message: unbounded.length + ' integer variable(s) declare no min/max, so no range invariant can be checked and A5 boundary probing has no declared domain.',
+            detail: unbounded.join(', '),
+        });
+    }
+    const terminals = model.states.filter((state) => state.terminal === true).map((state) => state.id);
+    if (terminals.length === 0) {
+        findings.push({
+            code: 'UML012_NO_TERMINAL',
+            severity: 'warning',
+            message: 'no state is terminal: the diagram has no `--> [*]`, so completion, failure and a stuck flow look the same.',
+            detail: 'Mark absorbing states terminal, or state explicitly that the machine is non-terminating.',
+        });
+    }
+    if (model.narrative === undefined) {
+        findings.push({
+            code: 'UML013_NO_NARRATIVE',
+            severity: 'info',
+            message: 'the model carries no narrative block: no state, event or scenario has a natural-language meaning, so a reader must re-derive every symbol from the source.',
+            detail: 'Add narrative.states / narrative.events / narrative.scenarios — a partial narrative is valid and its coverage is reported; write the states first and fill the rest in later.',
+        });
+    }
+    else {
+        // A narrative that covers part of the model is valid: states first, events and
+        // scenarios later is the natural authoring order. The gap is reported as coverage
+        // (and as this info finding), never as a validation failure.
+        const coverage = narrativeCoverageOf(model);
+        if (coverage !== undefined && !narrativeComplete(coverage)) {
+            findings.push({
+                code: 'UML027_NARRATIVE_PARTIAL',
+                severity: 'info',
+                message: 'the narrative covers part of the model: states ' + coverage.states + ', events ' + coverage.events + ', scenarios ' + coverage.scenarios + '. Every uncovered symbol still has to be re-derived from the source.',
+                detail: 'narrativeCoverage carries the same numbers; complete the missing entries when the behaviour settles.',
+                evidence: { narrativeCoverage: coverage },
+            });
+        }
+    }
+    const documented = labels === undefined ? undefined : Object.keys(labels).filter((id) => documentedMeaning(labels[id], id) !== undefined);
+    if (documented !== undefined) {
+        const undocumented = model.states.map((state) => state.id).filter((id) => documentedMeaning(labels?.[id], id) === undefined);
+        if (undocumented.length > 0) {
+            findings.push({
+                code: 'UML014_UNDOCUMENTED_STATE',
+                severity: 'info',
+                message: undocumented.length + ' of ' + String(model.states.length) + ' states carry no meaning in the diagram (they render as their bare id).',
+                states: undocumented,
+                detail: 'Give each state a `state "meaning" as ID` label or `ID : meaning` description so the diagram can be read against the code.',
+            });
+        }
+        if (model.narrative?.states !== undefined) {
+            const drift = [];
+            for (const state of model.states) {
+                const meaning = documentedMeaning(labels?.[state.id], state.id);
+                const declared = model.narrative.states[state.id];
+                if (meaning !== undefined && declared !== undefined && meaning !== declared)
+                    drift.push(state.id + ': diagram "' + meaning + '" vs narrative "' + declared + '"');
+            }
+            if (drift.length > 0) {
+                findings.push({
+                    code: 'UML015_LABEL_DRIFT',
+                    severity: 'warning',
+                    message: drift.length + ' state label(s) disagree with the model narrative: one of the two is stale, and the review cannot tell which.',
+                    detail: drift.join(' | '),
+                });
+            }
+        }
+    }
+    if (warnings.length > 0) {
+        findings.push({
+            code: 'UML016_DIAGRAM_PARSE_NOTES',
+            severity: 'info',
+            message: warnings.length + ' note(s) were produced while rendering or reading the diagram; they mark information the notation could not carry.',
+            detail: warnings.join(' | '),
+        });
+    }
+    return findings;
+}
+function collectGuardVariables(guard, sink) {
+    if ('variable' in guard) {
+        sink.add(guard.variable);
+        return;
+    }
+    if ('all' in guard) {
+        for (const child of guard.all)
+            collectGuardVariables(child, sink);
+        return;
+    }
+    if ('any' in guard) {
+        for (const child of guard.any)
+            collectGuardVariables(child, sink);
+        return;
+    }
+    collectGuardVariables(guard.not, sink);
+}
+/** Positive, conjunctively-reached leaves of a guard tree — the only ones a complementarity witness may use. */
+function positiveLeaves(guard, sink) {
+    if ('variable' in guard) {
+        sink.push(guard);
+        return;
+    }
+    if ('all' in guard) {
+        for (const child of guard.all)
+            positiveLeaves(child, sink);
+        return;
+    }
+    // `any` and `not` subtrees are skipped on purpose: a leaf under a disjunction is
+    // not implied by its branch, and `not (x < 3)` is `x >= 3` only for totally
+    // ordered integers — neither is a sound complementarity witness.
+}
+const COMPLEMENTS = [['<', '>='], ['<=', '>'], ['==', '!=']];
+/**
+ * Name a variable whose guards contain a complementary pair (`x < 3` next to
+ * `x >= 3`), which makes the branch group exhaustive for every valuation. Returns
+ * undefined when no such pair exists — absence is not proof of a gap.
+ */
+function complementaryVariable(guards) {
+    const leaves = [];
+    for (const guard of guards)
+        positiveLeaves(guard, leaves);
+    for (let i = 0; i < leaves.length; i += 1) {
+        for (let j = i + 1; j < leaves.length; j += 1) {
+            const left = leaves[i];
+            const right = leaves[j];
+            if (left.variable !== right.variable)
+                continue;
+            if (left.value !== right.value)
+                continue;
+            for (const [one, other] of COMPLEMENTS) {
+                if ((left.op === one && right.op === other) || (left.op === other && right.op === one))
+                    return left.variable;
+            }
+        }
+    }
+    return undefined;
+}
+/** Narrow a family model to a machine, or say plainly that the review got the wrong one. */
+function asMachineModel(model) {
+    const candidate = model;
+    if (typeof candidate.init === 'string' && Array.isArray(candidate.states) && Array.isArray(candidate.transitions))
+        return candidate;
+    throw new UmlError('this review expected a state machine and the model is a different UML diagram: review the family model on its own, or model the machine as a state or activity diagram.', 'UML_INPUT');
+}
+/**
+ * Compare two family models by structure: the fidelity measure for a family whose
+ * model is not a machine. Every path that differs is named, so a mismatch reads as
+ * the element that changed rather than as a wall of JSON.
+ */
+function diffJsonModels(left, right, path = '') {
+    const diffs = [];
+    const at = (name) => (path === '' ? name : path + '.' + name);
+    if (Array.isArray(left) && Array.isArray(right)) {
+        const length = Math.max(left.length, right.length);
+        for (let index = 0; index < length; index += 1) {
+            if (index >= left.length) {
+                diffs.push(at('[' + String(index) + ']') + ' invented by the diagram');
+                continue;
+            }
+            if (index >= right.length) {
+                diffs.push(at('[' + String(index) + ']') + ' missing after parse');
+                continue;
+            }
+            diffs.push(...diffJsonModels(left[index], right[index], path + '[' + String(index) + ']'));
+        }
+        return diffs;
+    }
+    if (left !== null && right !== null && typeof left === 'object' && typeof right === 'object') {
+        const leftRecord = left;
+        const rightRecord = right;
+        for (const key of [...new Set([...Object.keys(leftRecord), ...Object.keys(rightRecord)])].sort()) {
+            if (!(key in rightRecord)) {
+                diffs.push(at(key) + ' missing after parse');
+                continue;
+            }
+            if (!(key in leftRecord)) {
+                diffs.push(at(key) + ' invented by the diagram');
+                continue;
+            }
+            diffs.push(...diffJsonModels(leftRecord[key], rightRecord[key], at(key)));
+        }
+        return diffs;
+    }
+    if (JSON.stringify(left) !== JSON.stringify(right))
+        diffs.push((path === '' ? '(root)' : path) + ': ' + JSON.stringify(left) + ' vs ' + JSON.stringify(right));
+    return diffs;
+}
+function compiledModel(input) {
+    const validation = validateModel(input);
+    if (!validation.ok)
+        throw new UmlError('model invalid: ' + validation.errors.join('; '));
+    return validation.model;
+}
+function roundTripOf(model, notation, diagram, maxSteps) {
+    const rendered = renderUml(model, notation, diagram, maxSteps);
+    const parsed = parseUml(rendered.primary, notation);
+    const parsedModel = asMachineModel(parsed.model);
+    const diffs = diffModels(model, parsedModel);
+    return {
+        report: {
+            notation,
+            diagram,
+            ok: diffs.length === 0,
+            hashSpec: DEFAULT_HASH_SPEC,
+            modelHash: modelHash(model),
+            parsedHash: modelHash(parsedModel),
+            diffs,
+            warnings: [...rendered.warnings, ...parsed.warnings],
+        },
+        primary: rendered.primary,
+        parsed,
+    };
+}
+/** Compare two machines by structure — the fidelity measure behind the round-trip check. */
+export function diffModels(left, right) {
+    const diffs = [];
+    if (left.init !== right.init)
+        diffs.push('init: ' + left.init + ' vs ' + right.init);
+    const leftStates = left.states.map((state) => state.id);
+    const rightStates = right.states.map((state) => state.id);
+    for (const id of leftStates)
+        if (!rightStates.includes(id))
+            diffs.push('state missing after parse: ' + id);
+    for (const id of rightStates)
+        if (!leftStates.includes(id))
+            diffs.push('state invented by the diagram: ' + id);
+    const leftTerminal = left.states.filter((state) => state.terminal === true).map((state) => state.id).sort();
+    const rightTerminal = right.states.filter((state) => state.terminal === true).map((state) => state.id).sort();
+    if (leftTerminal.join(',') !== rightTerminal.join(','))
+        diffs.push('terminal states: [' + leftTerminal.join(', ') + '] vs [' + rightTerminal.join(', ') + ']');
+    const leftTransitions = left.transitions.map(canonicalTransition).sort();
+    const rightTransitions = right.transitions.map(canonicalTransition).sort();
+    const leftCount = new Map();
+    for (const key of leftTransitions)
+        leftCount.set(key, (leftCount.get(key) ?? 0) + 1);
+    const rightCount = new Map();
+    for (const key of rightTransitions)
+        rightCount.set(key, (rightCount.get(key) ?? 0) + 1);
+    for (const [key, count] of leftCount) {
+        const other = rightCount.get(key) ?? 0;
+        if (other < count)
+            diffs.push('transition lost in the diagram (' + String(count - other) + 'x): ' + key.replace(/\|/g, ' '));
+    }
+    for (const [key, count] of rightCount) {
+        const other = leftCount.get(key) ?? 0;
+        if (other < count)
+            diffs.push('transition invented by the diagram (' + String(count - other) + 'x): ' + key.replace(/\|/g, ' '));
+    }
+    const leftVariables = (left.variables ?? []).map((variable) => variable.name + ':' + variable.kind).sort();
+    const rightVariables = (right.variables ?? []).map((variable) => variable.name + ':' + variable.kind).sort();
+    for (const name of leftVariables)
+        if (!rightVariables.includes(name))
+            diffs.push('variable missing after parse: ' + name);
+    for (const name of rightVariables)
+        if (!leftVariables.includes(name))
+            diffs.push('variable invented by the diagram: ' + name);
+    return diffs;
+}
+/**
+ * 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.
+ */
+/**
+ * The notation the caller asked for, or a refusal naming it.
+ *
+ * `auto` is the one value that means "decide for me". Anything else must be a notation this engine
+ * reads or writes, because the review's answer depends on it: coercing `'graphviz'` into Mermaid and
+ * reporting a Mermaid review answers a question the caller did not ask.
+ */
+function requireNotation(value) {
+    if (value === undefined || value === 'auto')
+        return 'auto';
+    if (isUmlNotation(value))
+        return value;
+    throw new UmlError('notation must be auto, ' + UML_NOTATIONS.join(' or ') + ', got ' + JSON.stringify(value) + '.', 'UML_INPUT');
+}
+export function reviewUml(options) {
+    requireNotation(options.notation);
+    const warnings = [];
+    const findings = [];
+    const hasModel = options.model !== undefined;
+    const hasDiagram = typeof options.diagram === 'string' && options.diagram.trim() !== '';
+    if (!hasModel && !hasDiagram)
+        throw new UmlError('review needs `model`, `diagram`, or both');
+    // A family with a module of its own is reviewed by that module. Detection happens
+    // first: handing a use case diagram to the machine path is the defect this fixes.
+    if (hasDiagram) {
+        let detected;
+        try {
+            const text = options.diagram;
+            const resolved = options.notation === undefined || options.notation === 'auto' ? detectUmlNotation(text) : options.notation;
+            const hint = declaredFamily(readUmlDirectives(text.split(/\r?\n/), resolved));
+            detected = { family: detectUmlFamily(text, resolved, hint === undefined ? {} : { hint }).family, notation: resolved };
+        }
+        catch {
+            // Detection failed: the machine path reports that as UML001_DIAGRAM_UNREADABLE,
+            // with the refusal message, and never as a pass. Only detection may fail here -
+            // a review that throws must surface, not fall through to the wrong parser.
+            detected = undefined;
+        }
+        if (detected !== undefined) {
+            const module = familyModule(detected.family);
+            if (module !== undefined) {
+                return reviewFamilyUml({
+                    family: detected.family, module, notation: detected.notation, diagram: options.diagram,
+                    model: options.model, roundTrip: options.roundTrip !== false, metadataKeys: metadataKeysOf(options.model),
+                    intent: options.intent, canParse: umlFamilySpec(detected.family).parseable, parsedNotation: detected.notation,
+                });
+            }
+        }
+    }
+    else if (options.diagramKind !== undefined) {
+        const module = familyModule(options.diagramKind);
+        if (module !== undefined) {
+            const notation = options.notation === undefined || options.notation === 'auto' ? 'plantuml' : options.notation;
+            return reviewFamilyUml({
+                family: options.diagramKind, module, notation, model: options.model,
+                roundTrip: options.roundTrip !== false, metadataKeys: metadataKeysOf(options.model), intent: options.intent,
+                canParse: umlFamilySpec(options.diagramKind).parseable,
+            });
+        }
+    }
+    let notation = options.notation === undefined || options.notation === 'auto' ? 'mermaid' : options.notation;
+    const kind = options.diagramKind ?? 'state';
+    checkUmlIntent(options.intent, 'review', { notation, diagram: kind });
+    let model;
+    let labels;
+    let parsed;
+    let primary;
+    let roundTrip = null;
+    const metadataKeys = metadataKeysOf(hasModel ? options.model : undefined);
+    const metadata = metadataKeys.length === 0 ? {} : { metadataKeys };
+    let discardedConstructs = [];
+    let discardedEdges = 0;
+    if (hasDiagram) {
+        try {
+            parsed = parseUml(options.diagram, options.notation ?? 'auto');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const unreadable = { code: 'UML001_DIAGRAM_UNREADABLE', severity: 'error', message, detail: 'The diagram could not be read as a Mermaid/PlantUML state or activity diagram.' };
+            return {
+                // `ok: true`, because this IS a review: it ran, it examined the text, and it reported that the text
+                // cannot be read. `ok: false` is for a refusal - no report at all - and a reader keying on it was told
+                // "nothing happened" about the one answer that says exactly what is wrong. Every other family sets
+                // `ok: true` for a failing review; this was the only report that did not.
+                ok: true,
+                ran: true,
+                ...verdictOfFindings([unreadable]),
+                schema: REPORT_SCHEMAS.umlReview,
+                source: hasModel ? 'model+diagram' : 'diagram',
+                summary: { errors: 1, warnings: 0, info: 0, states: 0, events: 0, transitions: 0, terminalStates: 0, reachableStates: 0, documentedStates: 0 },
+                findings: [unreadable],
+                roundTrip: null,
+                ...metadata,
+                hashes: { hashSpec: DEFAULT_HASH_SPEC },
+                warnings,
+                nextSteps: ['Fix the diagram syntax (or render one from a model with uml action=render) and review again.'],
+            };
+        }
+        notation = parsed.notation;
+        labels = parsed.labels;
+        warnings.push(...parsed.warnings);
+        // A diagram from another family parses into something; that something must never
+        // be read as a model of this file, so the parse defects are review findings here too.
+        findings.push(...parseFindings(parsed));
+        if (parsed.discardedConstructs.length > 0) {
+            discardedConstructs = parsed.discardedConstructs;
+            discardedEdges = parsed.discardedEdges;
+        }
+        if (hasModel) {
+            model = compiledModel(options.model);
+            const parsedMachine = asMachineModel(parsed.model);
+            const diffs = diffModels(model, parsedMachine);
+            roundTrip = {
+                notation: parsed.notation,
+                diagram: parsed.diagram,
+                ok: diffs.length === 0,
+                hashSpec: DEFAULT_HASH_SPEC,
+                modelHash: modelHash(model),
+                parsedHash: modelHash(parsedMachine),
+                diffs,
+                warnings: [...parsed.warnings],
+            };
+            if (diffs.length > 0) {
+                findings.push({
+                    code: 'UML017_ROUND_TRIP_MISMATCH',
+                    severity: 'error',
+                    message: 'the diagram does not carry the model it is presented with: ' + String(diffs.length) + ' structural difference(s).',
+                    detail: diffs.slice(0, 12).join(' | ') + (diffs.length > 12 ? ' | … ' + String(diffs.length - 12) + ' more' : ''),
+                });
+            }
+            if (diffs.length === 0 && labels !== undefined && model.narrative === undefined) {
+                warnings.push('UML_REVIEW_DIAGRAM_LABELS_IGNORED_BY_MODEL: the diagram carries state labels but the model has no narrative block, so the labels live only in the diagram.');
+            }
+        }
+        else {
+            model = asMachineModel(parsed.model);
+            findings.push({
+                code: 'UML018_FIDELITY_UNCHECKED',
+                severity: 'info',
+                message: 'only a diagram was supplied, so the review reads the diagram as the model: nothing here proves the diagram matches the code it claims to describe.',
+                detail: 'Compare the parsed model against the code (each state/event/guard needs a source citation), or pass the machine alongside the diagram to check the two against each other.',
+            });
+        }
+    }
+    else {
+        model = compiledModel(options.model);
+        // A sequence view is a trace, so parsing it back would drop every branch the
+        // walk never took: the fidelity check cannot apply to it, and pretending it did
+        // would either fail spuriously or hide the difference. Render it anyway (the
+        // caller asked for that view) and say the check does not apply.
+        if (kind === 'sequence') {
+            try {
+                const rendered = renderUml(model, notation, kind, options.maxSteps ?? 60);
+                primary = rendered.primary;
+                warnings.push(...rendered.warnings);
+            }
+            catch (error) {
+                warnings.push('UML_REVIEW_RENDER_SKIPPED: ' + (error instanceof Error ? error.message : String(error)));
+            }
+            findings.push({
+                code: 'UML019_ROUND_TRIP_SKIPPED',
+                severity: 'warning',
+                message: 'a sequence view is one trace, not a restatement of the machine, so the render/parse fidelity check does not apply to it; render diagram "state" or "activity" to have the diagram checked against the model.',
+            });
+        }
+        else if (options.roundTrip !== false) {
+            try {
+                const rendered = roundTripOf(model, notation, kind, options.maxSteps ?? 60);
+                primary = rendered.primary;
+                roundTrip = rendered.report;
+                warnings.push(...rendered.report.warnings);
+                if (!rendered.report.ok) {
+                    findings.push({
+                        code: 'UML017_ROUND_TRIP_MISMATCH',
+                        severity: 'error',
+                        message: 'the rendered diagram does not read back as the model: ' + String(rendered.report.diffs.length) + ' structural difference(s).',
+                        detail: rendered.report.diffs.slice(0, 12).join(' | '),
+                    });
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                warnings.push('UML_REVIEW_ROUND_TRIP_SKIPPED: ' + message);
+                findings.push({
+                    code: 'UML019_ROUND_TRIP_SKIPPED',
+                    severity: 'warning',
+                    message: 'the fidelity check could not run for ' + notation + '/' + kind + ': ' + message,
+                });
+            }
+        }
+        else {
+            findings.push({
+                code: 'UML019_ROUND_TRIP_SKIPPED',
+                severity: 'warning',
+                message: 'the fidelity check was switched off (roundTrip=false); nothing here proves the diagram carries the model.',
+            });
+        }
+    }
+    findings.push(...structuralFindings(model, labels, warnings));
+    const errors = findings.filter((finding) => finding.severity === 'error').length;
+    const warningCount = findings.filter((finding) => finding.severity === 'warning').length;
+    const info = findings.filter((finding) => finding.severity === 'info').length;
+    const reachable = reachableStates(model);
+    const documentedStates = labels === undefined
+        ? (model.narrative?.states === undefined ? 0 : Object.keys(model.narrative.states).length)
+        : Object.keys(labels).filter((id) => documentedMeaning(labels?.[id], id) !== undefined).length;
+    const events = new Set(model.transitions.map((transition) => transition.event));
+    const narrativeCoverage = narrativeCoverageOf(model);
+    const nextSteps = [];
+    if (errors > 0)
+        nextSteps.push('Resolve the error findings first — a diagram that cannot be read (or that disagrees with its model) will mislead every later review.');
+    if (findings.some((finding) => finding.code === 'UML_NOT_A_STATE_DIAGRAM'))
+        nextSteps.push('This text is not a state or activity diagram: keep it as its own view and model the machine as a state/activity diagram before reviewing it.');
+    nextSteps.push('Run model_verify on this model for the behavioural checks (S1-S8 structural, A1-A14 adversarial); the review above covers modelling, not behaviour.');
+    if (model.narrative === undefined)
+        nextSteps.push('Add narrative.states/events/scenarios so the diagram is readable against the code.');
+    if (findings.some((finding) => finding.code === 'UML011_UNBOUNDED_VARIABLE'))
+        nextSteps.push('Declare min/max (or boundaryChecks) before relying on A5 boundary probes.');
+    return {
+        ok: true,
+        ran: true,
+        ...verdictOfFindings(findings),
+        schema: REPORT_SCHEMAS.umlReview,
+        source: hasModel && hasDiagram ? 'model+diagram' : (hasDiagram ? 'diagram' : 'model'),
+        summary: {
+            errors,
+            warnings: warningCount,
+            info,
+            states: model.states.length,
+            events: events.size,
+            transitions: model.transitions.length,
+            terminalStates: model.states.filter((state) => state.terminal === true).length,
+            reachableStates: reachable.size,
+            documentedStates,
+        },
+        findings,
+        roundTrip,
+        ...(labels === undefined ? {} : { labels }),
+        ...(hasDiagram ? { model } : {}),
+        ...(primary === undefined ? {} : { primary }),
+        ...metadata,
+        ...(narrativeCoverage === undefined ? {} : { narrativeCoverage }),
+        hashes: {
+            hashSpec: DEFAULT_HASH_SPEC,
+            ...(roundTrip === null ? {} : { modelHash: roundTrip.modelHash, parsedHash: roundTrip.parsedHash }),
+        },
+        ...(discardedConstructs.length === 0 ? {} : { discardedConstructs, discardedEdges }),
+        warnings,
+        nextSteps,
+    };
+}
+/** Element counts for a family model, so the report says how big the diagram is. */
+function summarizeFamilyModel(model) {
+    if (model === null || typeof model !== 'object')
+        return undefined;
+    const record = model;
+    const summary = {};
+    if (Array.isArray(record.actors))
+        summary.actors = record.actors.length;
+    if (Array.isArray(record.useCases))
+        summary.useCases = record.useCases.length;
+    if (Array.isArray(record.relations))
+        summary.relations = record.relations.length;
+    if (Array.isArray(record.nodes))
+        summary.nodes = record.nodes.length;
+    if (Array.isArray(record.edges))
+        summary.edges = record.edges.length;
+    return Object.keys(summary).length === 0 ? undefined : summary;
+}
+/**
+ * Review a UML diagram whose model is not a machine.
+ *
+ * The contract is the machine review's: read `verdict`, never `ok`. What differs is
+ * what can be checked. A use case diagram has actors and use cases, not states and
+ * events, so the family module reports its own defects, and fidelity is proven the
+ * same way: render the model, read it back, and name every path that changed.
+ */
+function reviewFamilyUml(request) {
+    checkUmlIntent(request.intent, 'review', { notation: request.notation, diagram: request.family });
+    // A review of a model does not need a parse, so it is not refused for the notation
+    // being unable to read the family back; `uml_review` on a model of an approximate
+    // family is a review of the part that exists.
+    const capability = umlFamilyCapability(request.notation, request.family, 'review', { requireParse: false });
+    const spec = umlFamilySpec(request.family);
+    const findings = [];
+    const warnings = [];
+    if (capability.warning !== undefined)
+        warnings.push(capability.warning);
+    let labels;
+    let parsed;
+    let primary;
+    let roundTrip = null;
+    if (request.diagram !== undefined && request.canParse) {
+        parsed = request.module.parse(request.diagram, request.notation);
+        labels = parsed.labels;
+        warnings.push(...parsed.warnings);
+        if (parsed.discardedConstructs.length > 0) {
+            const summary = parsed.discardedConstructs.map((entry) => entry.construct).join(', ');
+            findings.push({
+                code: 'UML016_DIAGRAM_PARSE_NOTES',
+                severity: 'warning',
+                message: 'the diagram carries ' + String(parsed.discardedConstructs.length) + ' declaration(s) this family cannot represent (' + summary + '); they are not part of the model.',
+                detail: parsed.discardedConstructs.slice(0, 12).map((entry) => 'line ' + String(entry.line) + ': ' + entry.text).join(' | '),
+            });
+        }
+    }
+    else if (request.diagram !== undefined) {
+        // The notation draws this family and cannot read it back. Saying so is the review's
+        // job: parsing anyway would be the fabrication the capability table exists to stop,
+        // and throwing would leave the caller without the report the tool promised.
+        findings.push({
+            code: 'UML018_FIDELITY_UNCHECKED',
+            severity: 'info',
+            message: 'a ' + spec.name + ' is drawn by ' + request.notation + ' and cannot be read back out of it, so this text was not read and nothing here is checked against it.',
+            detail: umlFamilySpec(request.family).parseRefusal ?? 'Keep the drawing and the model in one commit, and re-render with uml_render whenever the model changes.',
+        });
+    }
+    const supplied = request.model;
+    // The canonical shape of what was supplied, when the family says it has one. Fidelity is a
+    // comparison between a model and what a diagram drawn from that model reads back as - and
+    // that is the normalized shape, not the raw input, because a parser necessarily fills in
+    // what the notation always draws.
+    let canonical = supplied;
+    if (supplied !== undefined && request.module.normalize !== undefined) {
+        try {
+            const normalized = request.module.normalize(supplied);
+            if (normalized !== undefined)
+                canonical = normalized;
+        }
+        catch {
+            // Not a model of this family: the render below reports that, in its own words.
+        }
+    }
+    let renderedForSupplied;
+    if (supplied !== undefined) {
+        try {
+            // A review that has no parsed diagram has no notation from the text to trust, so it
+            // renders in the one notation the capability table says can draw this family. Asking
+            // for the caller's default instead would refuse a family whose view exists - and
+            // report it as a model that belongs to another family.
+            const renderNotation = request.parsedNotation ?? request.module.notation ?? request.notation;
+            renderedForSupplied = request.module.render(supplied, renderNotation, { maxSteps: 60 });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            findings.push({
+                code: 'UML041_MODEL_FAMILY_MISMATCH',
+                severity: 'error',
+                message: 'the model supplied is not a ' + spec.name + ', so it cannot be compared with this diagram: ' + message,
+                detail: 'Review the model with the family it belongs to, or pass a ' + spec.name + ' model alongside this diagram.',
+            });
+        }
+    }
+    if (renderedForSupplied !== undefined) {
+        const rendered = renderedForSupplied;
+        primary = rendered.primary;
+        warnings.push(...rendered.warnings);
+        if (!request.canParse) {
+            // The diagram was drawn from the model, and the notation cannot read it back, so
+            // there is no fidelity check to report - only that there is none.
+            findings.push({
+                code: 'UML018_FIDELITY_UNCHECKED',
+                severity: 'info',
+                message: 'the diagram was drawn from the model, but a ' + spec.name + ' cannot be read back out of ' + request.notation + ', so nothing here proves the drawing still says what the model says.',
+                detail: 'Keep the drawing and the model in one commit, and re-render with uml_render whenever the model changes.',
+            });
+        }
+        else {
+            const reparsed = request.module.parse(rendered.primary, request.notation);
+            const diffs = diffJsonModels(canonical, reparsed.model);
+            roundTrip = {
+                notation: request.notation,
+                diagram: request.family,
+                ok: diffs.length === 0,
+                hashSpec: DEFAULT_HASH_SPEC,
+                modelHash: valueHash(canonical),
+                parsedHash: valueHash(reparsed.model),
+                diffs,
+                warnings: [...rendered.warnings, ...reparsed.warnings],
+            };
+            if (diffs.length > 0) {
+                findings.push({
+                    code: 'UML017_ROUND_TRIP_MISMATCH',
+                    severity: 'error',
+                    message: 'the rendered diagram does not read back as the model: ' + String(diffs.length) + ' structural difference(s).',
+                    detail: diffs.slice(0, 12).join(' | '),
+                });
+            }
+            if (parsed !== undefined) {
+                const againstDiagram = diffJsonModels(canonical, parsed.model);
+                if (againstDiagram.length > 0) {
+                    findings.push({
+                        code: 'UML017_ROUND_TRIP_MISMATCH',
+                        severity: 'error',
+                        message: 'the diagram does not carry the model it is presented with: ' + String(againstDiagram.length) + ' structural difference(s).',
+                        detail: againstDiagram.slice(0, 12).join(' | '),
+                    });
+                }
+            }
+            if (labels === undefined)
+                labels = reparsed.labels;
+        }
+    }
+    else if (parsed !== undefined && supplied === undefined) {
+        findings.push({
+            code: 'UML018_FIDELITY_UNCHECKED',
+            severity: 'info',
+            message: 'only a diagram was supplied, so the review reads the diagram as the model: nothing here proves it matches the system it describes.',
+            detail: 'Compare every element against the code or the requirements (each one needs a citation), or pass the family model alongside the diagram to check the two against each other.',
+        });
+    }
+    // A model of another family is reported above and never handed to the family review:
+    // its checks read fields this model does not have.
+    //
+    // What is handed over is the CANONICAL model, not the raw `supplied` one. They differ whenever a
+    // family validates into a richer shape than the caller wrote - the composite validator records
+    // the connector endpoints no declaration introduced, and `UML059` reads exactly that field. A
+    // review given the raw model reports nothing for a dangling endpoint: a pass for a model whose
+    // defect is only visible in the shape the family itself produces.
+    const reviewable = supplied !== undefined && renderedForSupplied === undefined ? parsed?.model : (canonical ?? parsed?.model);
+    if (reviewable !== undefined)
+        findings.push(...(request.module.review?.(reviewable, labels ?? {}, request.notation) ?? []));
+    const model = supplied ?? parsed?.model;
+    const errors = findings.filter((finding) => finding.severity === 'error').length;
+    const warningCount = findings.filter((finding) => finding.severity === 'warning').length;
+    const info = findings.filter((finding) => finding.severity === 'info').length;
+    const familySummary = summarizeFamilyModel(model);
+    const nextSteps = [];
+    if (errors > 0)
+        nextSteps.push('Resolve the error findings first: a diagram that disagrees with itself misleads every later reader.');
+    if (spec.group === 'structure')
+        nextSteps.push('When the question is where the dependencies point, run uml_structure_verify on the same text: it audits the graph against a dependency matrix.');
+    if (spec.machine)
+        nextSteps.push('Run model_verify on this model for the behavioural checks (S1-S8 structural, A1-A14 adversarial).');
+    else
+        nextSteps.push('A ' + spec.name + ' describes structure or intent, not behaviour: model the flow as a state or activity diagram and let model_verify check that one.');
+    nextSteps.push('A diagram is not evidence: cite the code or the requirement behind each element before presenting it as checked.');
+    const metadata = request.metadataKeys.length === 0 ? {} : { metadataKeys: request.metadataKeys };
+    return {
+        ok: true,
+        ran: true,
+        ...verdictOfFindings(findings),
+        schema: REPORT_SCHEMAS.umlReview,
+        source: request.diagram === undefined ? 'model' : (supplied === undefined ? 'diagram' : 'model+diagram'),
+        family: request.family,
+        summary: { errors, warnings: warningCount, info, states: 0, events: 0, transitions: 0, terminalStates: 0, reachableStates: 0, documentedStates: 0 },
+        ...(familySummary === undefined ? {} : { familySummary }),
+        findings,
+        roundTrip,
+        ...(labels === undefined ? {} : { labels }),
+        ...(model === undefined ? {} : { model: model }),
+        ...(primary === undefined ? {} : { primary }),
+        ...metadata,
+        hashes: {
+            hashSpec: DEFAULT_HASH_SPEC,
+            ...(roundTrip === null ? {} : { modelHash: roundTrip.modelHash, parsedHash: roundTrip.parsedHash }),
+        },
+        warnings,
+        nextSteps,
+    };
+}