@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/_pkgs/affine-block-surface/extensions/validation.d.ts

@@ -0,0 +1,2129 @@
+import type { AuditFinding } from '../../affine-shared/services/index.js';
+import { Bound } from '../../global/gfx/index.js';
+import type { RoleDefs, RoleId, SurfaceBlockModel, ValidationException } from '../../std/gfx/index.js';
+import { GfxPrimitiveElementModel, InteractivityExtension } from '../../std/gfx/index.js';
+import type { ExtensionType } from '../../store/index.js';
+import type { FrameworkBackgroundDef } from '../framework-background/def.js';
+import type { CanvasRenderer } from '../renderer/canvas-renderer.js';
+import { Overlay } from '../renderer/overlay.js';
+import type { RoughCanvas } from '../utils/rough/canvas.js';
+import { type QualityNudge } from './map-quality.js';
+import { ViolationTimeline } from './violation-timeline.js';
+/**
+ * Minimal validation engine (PF5, wave 1).
+ *
+ * A framework declares its rules as DATA and registers them; the engine walks
+ * the surface and produces VIOLATION OBJECTS. It renders no text, decides no
+ * wording and knows no concrete framework — it only knows roles (PF1) and
+ * geometry.
+ *
+ * Structural twin of `./spotlight.ts`: a generic mechanism living with the
+ * surface, opted into by a framework through a DI identifier.
+ *
+ * ## Gating (PF4 reversed flag contract)
+ *
+ * The engine registers **no rule of its own**. Rules are registered by the
+ * flag-gated `…ViewExtension` of their framework (validation is tooling, not
+ * content — see `docs/adr/0009`), so a disabled framework contributes no rule
+ * and {@link ValidationManager} short-circuits before touching a single
+ * element. Flag off costs exactly one empty-map check.
+ */
+/**
+ * How severely a violation is meant to bite. The engine only carries the value
+ * through to the violation; acting on it is the host's decision.
+ *
+ * - `blocking-overridable` — the host may block, and must let the user override.
+ * - `warning` — surfaced, never blocking. The sketch always wins.
+ * - `audit` — collected for reporting, invisible to the drawing user.
+ */
+export type ViolationSeverity = 'blocking-overridable' | 'warning' | 'audit';
+/**
+ * What a PROFILE can say about a rule: one of the three severities, or `'off'`
+ * — the rule is not evaluated at all, and costs nothing.
+ */
+export type ProfileSeverity = ViolationSeverity | 'off';
+/**
+ * Rule families. One family = one evaluation function ({@link RULE_FAMILIES}).
+ * Adding one is adding an entry here and a function below, never a change to
+ * the shape of a rule.
+ *
+ * - `element-in-background` — the subject must sit inside the framework's frame.
+ * - `orientation-against-axis` — a DIRECTIONAL subject (an arrow, an edge) must
+ *   not run against the declared sense of one of the frame's axes.
+ * - `attachment` — the subject must STRADDLE one of the frame's zone
+ *   transitions, and optionally be posed ON a carrier element.
+ * - `no-overlap` — declared pairs of roles must not collide. The first family
+ *   that is not element-local: it evaluates PAIRS.
+ * - `tone-convention` — the subject must be drawn in one of the tones the
+ *   frame's own palette declares for it. On-demand only, in practice.
+ * - `majority-fact` — a remark about the MAP, raised when a declared fact holds
+ *   for a majority of the subjects. Silent while nothing carries the fact.
+ * - `relative-order-along-axis` — the two elements a TYPED EDGE links must sit
+ *   in the order that edge states, along one axis of the frame. The first
+ *   family whose subject is a RELATION rather than an element or a proximity.
+ * - `relation-endpoints` — WHAT a typed edge is allowed to run between, and how
+ *   many times. The grammar of a framework's relations, read off the roles at
+ *   the two ends rather than off the geometry: the same relation between the
+ *   same two artefacts is right or wrong wherever they happen to be drawn.
+ * - `element-in-zone` — the subject must sit inside (or outside) named ZONES of
+ *   the frame it is on. `element-in-background` asks whether an artefact is on
+ *   the map at all; this one asks whether it is in the right REGION of it.
+ * - `edge-degree` — how many typed edges of one role may arrive at, and leave,
+ *   one node. The first family whose subject is a node but whose evidence is
+ *   its RELATIONS: nothing about where it is drawn takes part.
+ * - `role-count` — how many subjects of one role one INSTANCE of the frame must
+ *   carry. Existence and uniqueness, counted per frame and reported ON it.
+ * - `edge-locality` — a typed edge must stay inside one instance of the frame,
+ *   or must cross between two. Where `relation-endpoints` asks what a relation
+ *   runs between, this asks which FRAMES its two ends belong to.
+ * - `reachability` — every subject must be reachable from a declared root by
+ *   following typed edges. The first family that builds a graph rather than
+ *   walking elements, and the only one that is not local to one element or one
+ *   relation.
+ * - `label-presence` — the subject must be NAMED. The first family that reads
+ *   an element's words rather than its geometry, its role or its relations.
+ * - `view-admissibility` — which roles a frame ADMITS, read off a level the
+ *   frame itself declares. The first family whose question is asked of the
+ *   VIEW rather than of the artefact: every other one starts from a subject and
+ *   looks around it, this one starts from the sheet and asks what has been
+ *   drawn on it.
+ */
+export type RuleFamily = 'element-in-background' | 'orientation-against-axis' | 'attachment' | 'no-overlap' | 'relative-order-along-axis' | 'relation-endpoints' | 'element-in-zone' | 'tone-convention' | 'majority-fact' | 'edge-degree' | 'role-count' | 'edge-locality' | 'reachability' | 'label-presence' | 'view-admissibility';
+/**
+ * WHEN a rule is evaluated (PF5.14).
+ *
+ * - `realtime` — the default, and what every rule was before this existed:
+ *   evaluated on the debounced path while the user draws, inside the 16 ms
+ *   budget.
+ * - `on-demand` — evaluated ONLY when the user asks for a check-up, and never
+ *   during a gesture. {@link evaluateRules} skips these before touching a
+ *   single element, so a framework can ship a control that would not fit the
+ *   frame — or that is simply not urgent — without spending a microsecond of
+ *   the drawing budget on it.
+ *
+ * The split is a property of the RULE, not of the caller: a rule that must not
+ * interrupt says so once, in its own declaration, and no evaluation path has to
+ * remember. That is what makes "zero real-time cost" provable at the bench
+ * rather than promised in a comment.
+ */
+export type ValidationMoment = 'realtime' | 'on-demand';
+/** `orientation-against-axis` configuration. */
+export interface AgainstAxisDef {
+    /** Id of the axis in the rule's {@link ValidationRule.background}. */
+    axis: string;
+    /**
+     * Dead zone, in degrees, around the perpendicular. A subject at exactly 90°
+     * to the axis runs neither with it nor against it, and a rule that indicted
+     * it would be indicting a drawing hand rather than a mistake — so the verdict
+     * only falls beyond `90 + toleranceDeg` away from the axis' forward sense.
+     */
+    toleranceDeg: number;
+}
+/**
+ * What a finding SAYS: an i18n key, plus the framework's own wording for a host
+ * that ships no catalogue for it, for the message and for the remediation hint.
+ *
+ * Split out of {@link ValidationRule} because a rule can have more than one way
+ * of failing, and a family that knows WHICH one failed must be able to say so.
+ * A single message covering two distinct mistakes is a message that describes
+ * neither: "not on a dependency at a phase transition" — the wording Wardley's
+ * W2 shipped with, before the PO reduced that rule to one condition — left the
+ * user to guess which half they had got wrong, on a symbol eight units wide.
+ */
+export interface RuleMessage {
+    /** i18n key of the message; resolved by the host. The engine holds no prose. */
+    messageKey: string;
+    /**
+     * The FRAMEWORK's own wording, used when the host ships no catalogue for the
+     * key — exactly the `labelKey` + `fallback` pair a {@link ValidationProfile}
+     * and a background label already carry. The framework owns the word; the
+     * library still never invents one.
+     */
+    messageFallback?: string;
+    /** i18n key of an optional remediation hint. */
+    suggestionKey?: string;
+    /** The framework's own wording for {@link suggestionKey}. */
+    suggestionFallback?: string;
+}
+/** `attachment` configuration. */
+export interface AttachmentDef {
+    /**
+     * OPTIONAL: the role of an element the subject must also be posed ON.
+     *
+     * It has to be an **edge** role: "posed on" is measured as a distance to a
+     * PATH, and a node has none. A rule naming a node role here matches nothing
+     * and warns once rather than failing silently — a rule that never fires and
+     * never says why is the worst thing declarative data can do.
+     *
+     * Absent means the subject is judged on {@link boundaryAxis} alone, which is
+     * the shape Wardley's W2 took the day the PO spelled the rule out: a bar
+     * straddling a phase divider is right whether or not a dependency happens to
+     * run under it (recette of 02/08/2026).
+     */
+    carrierRole?: RoleId;
+    /**
+     * How far, in model units, the subject may sit from its carrier. Read only
+     * when a {@link carrierRole} is declared, and absent means "on the path" —
+     * a boundary-only rule declares neither.
+     */
+    tolerance?: number;
+    /**
+     * The subject must STRADDLE one of the frame's declared transitions, measured
+     * across this axis. Absent means the position along the axis is not judged at
+     * all.
+     *
+     * ## "Straddling", as geometry
+     *
+     * The subject's own EXTENT along the axis must intersect the transition BAND
+     * — the frontier widened by the frame's declared
+     * {@link FrameworkBackgroundDef.transitionBandWidth}. One interval overlap,
+     * and it says both halves of what the practitioner means at once:
+     *
+     * - a subject WIDE enough to cover the frontier is superimposed on it, and is
+     *   accepted whatever the band says — the line genuinely passes through it;
+     * - a subject too thin to cover anything (an inertia bar is eight units wide)
+     *   is accepted while it is within the band, which is the frame's own
+     *   declared tolerance for "on this frontier" and, on a Wardley map, Wardley's
+     *   zone of punctuated equilibrium.
+     *
+     * Measured on the extent and never on the centre: "superimposed on the line"
+     * is a statement about the subject's ink, not about a point inside it. The
+     * band is a ratio of the plot, so the verdict holds when the map is resized.
+     * A rule asking for a boundary against a frame that declares no band warns
+     * once and drops the requirement rather than indicting every subject on the
+     * board.
+     */
+    boundaryAxis?: string;
+    /**
+     * The words for the boundary half, when a rule that ALSO declares a
+     * {@link carrierRole} wants to say something other than its own message —
+     * two requirements the user has two different ways of fixing are two
+     * sentences. A boundary-only rule needs none: its own message is the only
+     * thing it can be saying.
+     */
+    offBoundary?: RuleMessage;
+}
+/**
+ * One `no-overlap` combination: two roles that must not collide. Order carries
+ * no meaning — `[label, node]` and `[node, label]` are the same requirement.
+ *
+ * Which GEOMETRY each side is measured with is not declared here: it follows
+ * the role's own `kind` in {@link ValidationRule.roles}. An `edge` role is
+ * measured along its PATH, because the bounding box of a diagonal link covers
+ * half the map and would indict every label anywhere near it; a `text` role by
+ * the ink of its text, because a text box is created at a width that says
+ * nothing about what it reads; a `node` role by its bounds.
+ */
+export type OverlapPair = readonly [RoleId, RoleId];
+/**
+ * `tone-convention` configuration (PF13.8 / Q5).
+ *
+ * A framework's colour code is a CONVENTION, not a decoration: on a Wardley map
+ * the landscape is drawn in greys, red is reserved for what is changing and
+ * green for benefits. A component someone coloured red for emphasis is saying
+ * something the author did not mean.
+ *
+ * ## Why palette ENTRIES and not colours
+ *
+ * The sanctioned colours are named against the frame's own declared palette
+ * ({@link BackgroundChromeDef.palette}) — the same `@name` indirection every
+ * background label and wash already uses. A rule therefore never restates a hex
+ * the background already owns, and a host restyling the frame restyles the
+ * convention with it, in one place.
+ *
+ * ## Why TONES and not exact colours
+ *
+ * The convention is about tones, so the comparison is too: an element is judged
+ * on the tone family its colour falls into ({@link toneOf}), never on matching
+ * a palette entry byte for byte. Otherwise every legitimate shade of grey the
+ * shape toolbar can produce would be a finding, which is a rule nobody would
+ * keep switched on for five minutes.
+ *
+ * A colour the engine cannot classify — a CSS variable it has no theme to
+ * resolve, a gradient, `transparent` — yields SILENCE. Guessing would mean
+ * indicting a user over a colour nobody in this process can actually see.
+ */
+export interface ToneConventionDef {
+    /**
+     * Names of the entries, in the rule's {@link ValidationRule.background}
+     * palette, whose tones the subject may be drawn in. A rule naming entries
+     * that resolve to no classifiable tone at all warns once and evaluates
+     * nothing, rather than indicting every element on the board.
+     */
+    palette: readonly string[];
+}
+/**
+ * `majority-fact` configuration (PF13.8 / Q6).
+ *
+ * "Most of what you have mapped is an activity — the phase names for activities
+ * would read better." A remark about the MAP, raised from a count over its
+ * elements, and deliberately never imposed.
+ *
+ * ## The gate, and why it is silence rather than a warning
+ *
+ * The fact is read off a declared element prop that may not exist yet — Wardley's
+ * `nature` is the type-3 classification, and nothing writes it today. A family
+ * that guessed would produce a remark about a majority it computed over an empty
+ * population, i.e. a sentence with no evidence behind it. So a surface where NO
+ * subject carries the fact raises nothing at all, silently: the rule is shipped,
+ * inert, and starts working by itself the day the fact lands. Nothing to
+ * remember, nothing to switch on.
+ */
+export interface MajorityDef {
+    /**
+     * The element prop carrying the fact, read duck-typed: the engine must not
+     * import a framework's model to count something declared by data.
+     */
+    fact: string;
+    /** The value that must hold for a majority of the subjects. */
+    value: string;
+}
+/**
+ * `relative-order-along-axis` configuration — the family of `docs/adr/0010`'s
+ * W4, "a provider component may not be positioned higher than its consumer".
+ *
+ * The rule reads a RELATION: given a typed edge, it compares the two elements
+ * that edge links along one axis of the frame, in the order the edge states.
+ * That order comes from the persisted `source → target` pair and from nowhere
+ * else — deriving it from the geometry would make the rule compare the layout
+ * against itself, so it could never fire (ADR 0010 § 4a).
+ */
+export interface RelativeOrderDef {
+    /**
+     * The EDGE role whose orientation is read. An element matching it (or
+     * specialising it) with both ends bound is one subject of the rule; every
+     * other edge on the board is none of its business — a Wardley change arrow is
+     * oriented too, and says nothing about who depends on whom.
+     */
+    edgeRole: RoleId;
+    /** Id of the axis in the rule's {@link ValidationRule.background}. */
+    axis: string;
+    /**
+     * Which end the edge states should be FURTHER ALONG the axis' forward sense
+     * (the direction of increasing value: up for a vertical axis, right for a
+     * horizontal one).
+     *
+     * `'source-ahead'` for `wardley:dependency`: the source is the consumer, so
+     * it sits higher on the visibility axis and the target is what it rests on.
+     * Needs descend from source to target; value flows back up.
+     */
+    expect: 'source-ahead' | 'target-ahead';
+    /**
+     * Slack before the verdict falls, as a RATIO of the frame's extent along that
+     * axis — never a number of model units.
+     *
+     * Same lesson the transition band learned on the PO recette of 01/08/2026: an
+     * absolute tolerance is four times as strict on a map four times as big, and
+     * nothing on screen explains why. Two components drawn level are not a
+     * mistake — an architect lines up a chain before spreading it out — so the
+     * rule only speaks when one is genuinely below the other.
+     *
+     * Absent means zero: any inversion at all, however small, is reported.
+     */
+    toleranceRatio?: number;
+}
+/**
+ * One sanctioned sentence of a framework's relation grammar: `source` _edge_
+ * `target`, all three named by ROLE.
+ *
+ * Read exactly the way `docs/adr/0010` says an edge is read — the source is the
+ * subject of the verb, the target its object — so a triplet is a sentence a
+ * practitioner would say out loud: an actor issues a command, a command lands on
+ * an aggregate, an aggregate raises an event. Each side matches by
+ * {@link roleIsA}, so a triplet written on a parent role covers every
+ * specialisation of it for free.
+ */
+export interface EndpointTriplet {
+    source: RoleId;
+    edge: RoleId;
+    target: RoleId;
+}
+/**
+ * `relation-endpoints` configuration — the grammar of a framework's relations.
+ *
+ * Where `relative-order-along-axis` asks whether the two ends of a relation are
+ * in the right PLACE, this family asks whether they are the right THINGS. It
+ * reads the persisted `source → target` pair and the roles the two ends carry,
+ * and nothing else: no coordinate takes part, so the verdict survives every
+ * layout of the same document.
+ *
+ * ## Four ways of failing, four sentences
+ *
+ * A relation can be wrong in ways the user fixes with four different gestures —
+ * re-point an end, delete a loop, delete a copy, choose between two patterns —
+ * so each mode carries its own {@link RuleMessage} and falls back to the rule's
+ * own words when a framework declares none. Same precedent as
+ * {@link AttachmentDef.offBoundary}, for the same reason: one sentence covering
+ * four mistakes describes none of them.
+ */
+export interface RelationEndpointsDef {
+    /**
+     * The EDGE role whose ends are read. An element matching it (or specialising
+     * it) is one subject of the rule; every other edge on the board is none of
+     * its business — a free connector somebody drew to point at something is not
+     * a claim about the model.
+     */
+    edgeRole: RoleId;
+    /**
+     * The sanctioned sentences. Absent means the shape of the relation is not
+     * judged at all, which is what a rule that only forbids loops or duplicates
+     * declares.
+     *
+     * ## The alphabet, and why an unknown end is SILENCE
+     *
+     * The roles cited by the triplets — every `source` and every `target` — form
+     * the alphabet this rule speaks. An edge with an end OUTSIDE that alphabet is
+     * not evaluated at all: not the matrix, not the loop, not the duplicate.
+     *
+     * A hard requirement, and the one that makes the family shippable. A flow
+     * drawn onto an Event Storming hotspot, or onto a plain rectangle somebody
+     * dropped on the board to think with, is a DRAFT — the user is saying "there
+     * is something here", and a tool that answered "that arc is forbidden" would
+     * be indicting the act of sketching. The frameworks' own grammars are written
+     * on a handful of artefacts each; everything else on the canvas has to stay
+     * outside the conversation (PRD principle 8).
+     */
+    allowed?: readonly EndpointTriplet[];
+    /**
+     * Pairs of edge roles that may not BOTH be drawn between the same two
+     * elements. The node pair is unordered — two contexts related twice are
+     * related twice whichever end each relation starts from — and so is the role
+     * pair: `[acl, conformist]` and `[conformist, acl]` are one requirement.
+     *
+     * The Context Mapping case: a downstream context protecting itself with an
+     * anti-corruption layer is not simultaneously conforming to its upstream. Both
+     * relations are legitimate on their own; together they are a contradiction,
+     * and only the pair can say so.
+     */
+    exclusivePairs?: readonly (readonly [RoleId, RoleId])[];
+    /**
+     * Whether an edge whose two ends are the SAME element is a finding.
+     *
+     * Absent, a self-loop is silence — total silence, even when the matrix says
+     * nothing about it. A loop is either a deliberate notation (a process that
+     * feeds itself) or a hand that dropped the second end on the first, and a
+     * framework that has not decided which has not asked to be told about it.
+     */
+    forbidSelfLoop?: boolean;
+    /** Whether the SAME relation drawn twice between the same ordered pair is a finding. */
+    forbidDuplicate?: boolean;
+    /** Words for an edge whose sentence is not in {@link allowed}. */
+    offMatrix?: RuleMessage;
+    /** Words for an edge that loops back onto its own source. */
+    selfLoop?: RuleMessage;
+    /** Words for the second copy of a relation that already exists. */
+    duplicate?: RuleMessage;
+    /** Words for two relations of {@link exclusivePairs} drawn between one pair. */
+    exclusive?: RuleMessage;
+    /**
+     * Words for a NEUTRAL connector drawn between two artefacts of this rule's
+     * own vocabulary — and, by being present at all, the request to look for one.
+     * Absent, a role-less link is invisible to this family, which is what every
+     * rule written before this field means.
+     *
+     * ## The gap this closes
+     *
+     * A framework's edge tool stamps a role. Quick-connect and auto-complete do
+     * not: releasing the canvas' own link gesture between two artefacts produces a
+     * connector carrying NO role, so it says nothing to any of the four verdicts
+     * above — the grammar reads it as absent, and the user reads it as drawn. A
+     * process whose steps are joined by such links looks connected and validates
+     * as if nobody had joined anything.
+     *
+     * ## Why BOTH ends must be artefacts this grammar could have related
+     *
+     * The same proportionality that makes {@link allowed}'s alphabet a hard
+     * requirement, applied one level up. A plain connector from an artefact to a
+     * sticky note, to a legend glyph, to a shape somebody dropped on the board, is
+     * an annotation and none of the framework's business — pointing at things is
+     * what a whiteboard is for. A plain connector between two artefacts this
+     * rule's own sentences run between is the only case where the user can be
+     * presumed to have meant a typed relation and reached for the wrong gesture.
+     *
+     * "Could have related" is read off {@link allowed}'s own ALPHABET when the
+     * rule declares a matrix: the roles its triplets name as a source or a target,
+     * matched with {@link roleIsA} so a specialisation counts. That is the
+     * tightest honest reading, and it excludes — with nothing for an author to
+     * remember — every role a framework declares for something that is not an
+     * endpoint of anything: the background role, a legend glyph, a lane. Presuming
+     * somebody meant to draw a typed relation onto a POOL is exactly the
+     * over-firing this test exists to prevent.
+     *
+     * A rule declaring NO matrix has no alphabet to read, so it falls back to
+     * membership in its own {@link ValidationRule.roles} — never to a prefix match
+     * on the `framework:` half of the role id. The namespace is a naming
+     * CONVENTION (`role.ts` says so, and types the id as a bare string); the
+     * vocabulary is DATA the framework hands the engine. Reading the data cannot
+     * be wrong about a framework that spells its own prefix differently, and it
+     * keeps this file free of string surgery on ids it does not own.
+     *
+     * `roles` stays purely the dictionary the inheritance walk reads either way.
+     * It is never overloaded into a filter, so an author never has to shrink the
+     * vocabulary a rule's other clauses depend on in order to change what this
+     * one flags.
+     */
+    flagNeutral?: RuleMessage;
+}
+/**
+ * `edge-degree` configuration — the CARDINALITY of a framework's relations, read
+ * at a node.
+ *
+ * "A start event has no incoming sequence flow"; "a task has at least one".
+ * Where {@link RelationEndpointsDef} judges one relation against the roles at
+ * its ends, this judges one NODE against how many relations reach it — the other
+ * half of a relation grammar, and the half no per-edge rule can express, because
+ * the mistake is a COUNT and nothing is wrong with any single link.
+ *
+ * ## Read off the persisted ends, never off the geometry
+ *
+ * Same reading as `docs/adr/0010`: an edge's `source` is the subject of its
+ * verb and its `target` the object, so "incoming" and "outgoing" are properties
+ * of the document and not of which way somebody dragged. Nothing here consults a
+ * coordinate, so the verdict survives every layout of the same process.
+ */
+export interface EdgeDegreeDef {
+    /**
+     * The EDGE role being counted. An element matching it (or specialising it)
+     * counts; every other link on the board is none of this rule's business — a
+     * message flow arriving at a task says nothing about how many sequence flows
+     * do.
+     */
+    edgeRole: RoleId;
+    /** Fewest edges of that role that may ARRIVE at the subject. */
+    minIn?: number;
+    /** Most edges of that role that may ARRIVE at the subject. */
+    maxIn?: number;
+    /** Fewest edges of that role that may LEAVE the subject. */
+    minOut?: number;
+    /** Most edges of that role that may LEAVE the subject. */
+    maxOut?: number;
+    /**
+     * A DISJUNCTIVE floor: the subject must reach this count on at least ONE
+     * side. The finding falls only when BOTH the incoming and the outgoing count
+     * are short of it.
+     *
+     * ## Why a fifth bound rather than two of the four
+     *
+     * The four above are conjunctive — declare `minIn` and `minOut` together and
+     * the subject has to satisfy both — and there is a whole class of normative
+     * shape that says the opposite: an artefact must do one thing OR the other,
+     * and doing either is enough. A branching artefact that neither splits nor
+     * merges is the canonical one: it takes one thing in, puts one thing out and
+     * decides nothing, which is a node somebody drew and then never gave a job.
+     * `minIn: 2` would indict every split, `minOut: 2` every merge; the
+     * requirement is genuinely "at least one of the two", and no conjunction of
+     * per-direction bounds expresses it.
+     *
+     * ## Composition
+     *
+     * Orthogonal to the four, and evaluated after them: a rule may cap one side
+     * with `maxIn` and still ask for two on either side, and each bound keeps its
+     * own sentence. Absent — the case for every rule written before it existed —
+     * nothing is asked and nothing is counted.
+     */
+    eitherMin?: number;
+    /**
+     * A FORBIDDEN ZONE: the shape of degree a subject may not have, declared as
+     * the bounds it must NOT all satisfy at once.
+     *
+     * The inverse polarity of every bound above. `minIn`/`maxIn`/`minOut`/`maxOut`
+     * here read exactly as they do there — `minIn: 2` means "two or more arrive" —
+     * but the rule fires when the node matches ALL of the ones supplied, instead of
+     * when it misses one.
+     *
+     * ## Why the inverse cannot be written with the bounds
+     *
+     * Two shapes want it, and neither is expressible as a floor or a ceiling:
+     *
+     * - an artefact that MERGES and SPLITS at once — `{ minIn: 2, minOut: 2 }`.
+     *   Both halves are individually fine and their conjunction is ambiguous, so
+     *   the rule is about the pair and about nothing else;
+     * - an artefact that does NEITHER — `{ maxIn: 1, maxOut: 1 }`. A ceiling on
+     *   each side alone forbids the legitimate split and the legitimate merge; only
+     *   their conjunction describes the artefact that decides nothing.
+     *
+     * The second one is the same requirement {@link eitherMin} states from the
+     * other side, and a framework may write it either way — `eitherMin: 2` and
+     * `forbidPattern: { maxIn: 1, maxOut: 1 }` are the same set of nodes. Both are
+     * offered because a rule reads best when its data says what its sentence says,
+     * and the two sentences a notation actually writes are "a gateway must branch"
+     * and "a gateway that does nothing is superfluous".
+     *
+     * ## A pattern of ONE bound is legal, and always redundant
+     *
+     * `{ minIn: 2 }` fires on `in >= 2`, which is what `maxIn: 1` already says, and
+     * `{ maxIn: 1 }` alone is `minIn: 2`. Coherent under the rule above and left
+     * legal rather than warned about — the conjunction of one is still a
+     * conjunction, and a framework mid-edit should not be shouted at. But a
+     * one-bound pattern is never the reason to reach for this field: write the
+     * plain inverse bound, which carries a per-direction sentence naming the side
+     * the user has to act on.
+     *
+     * ## Words, and the empty pattern
+     *
+     * The pattern carries its OWN message rather than a slot beside the others: a
+     * forbidden zone is not a bound that failed, and its sentence never reads like
+     * one. `RuleMessage` is intersected rather than optional, so the type system
+     * requires that sentence — this is the one bound with no `?? rule` fallback,
+     * because it is the one that can never borrow the rule's own words honestly.
+     *
+     * A pattern supplying no bound at all is satisfied by every node, which would
+     * indict the whole board — it warns once and is not evaluated.
+     */
+    forbidPattern?: RuleMessage & {
+        minIn?: number;
+        maxIn?: number;
+        minOut?: number;
+        maxOut?: number;
+    };
+    /**
+     * Words for each bound, when a rule declaring more than one wants to say
+     * something other than its own message.
+     *
+     * The {@link AttachmentDef.offBoundary} precedent, for the same reason: "a
+     * start event begins the process" covers both "something points at it" and
+     * "nothing leaves it", and the two are fixed by opposite gestures. A rule
+     * declaring a single bound needs none — its own message is the only thing it
+     * can be saying.
+     */
+    tooFewIn?: RuleMessage;
+    /** Words for {@link maxIn}. */
+    tooManyIn?: RuleMessage;
+    /** Words for {@link minOut}. */
+    tooFewOut?: RuleMessage;
+    /** Words for {@link maxOut}. */
+    tooManyOut?: RuleMessage;
+    /**
+     * Words for {@link eitherMin} — the one bound whose sentence is genuinely
+     * about NEITHER side, and therefore the one a per-direction message could
+     * never carry.
+     */
+    neither?: RuleMessage;
+}
+/**
+ * `role-count` configuration — existence and uniqueness, counted per INSTANCE of
+ * the frame.
+ *
+ * "A pool holds exactly one start event." The subject of the finding is not any
+ * one element — no start event is wrong, there are simply none or three — so the
+ * finding is raised ON THE FRAME, exactly like {@link MajorityDef}'s remark
+ * about a map. That is what puts the bracket on the pool, and what makes the
+ * `map` exemption scope reach it: `raise` stamps the frame as the finding's own
+ * {@link Violation.backgroundId}, so an arbitration made on one pool covers that
+ * pool and no other on the board.
+ */
+export interface RoleCountDef {
+    /**
+     * The role being counted, matched by {@link roleIsA} — a rule counting
+     * `bpmn:start-event` counts its message and timer variants too, which is the
+     * only reading under which "one start event" stays one requirement as the
+     * vocabulary grows.
+     */
+    subject: RoleId;
+    /**
+     * Count only the elements whose role IS {@link subject}, without descending
+     * into its specialisations.
+     *
+     * The default — `roleIsA`, the reading every other role test in this engine
+     * uses — is right whenever the requirement is about the FAMILY: "one
+     * beginning" means one beginning of any kind, and a vocabulary that grows a
+     * new variant inherits the rule for free.
+     *
+     * It is wrong when the requirement is about the PLAIN member of a family, as
+     * distinct from its qualified siblings: "at most one UNQUALIFIED beginning per
+     * frame" is a statement about the artefact that carries no qualifier, and
+     * several qualified ones beside it are exactly what the notation is for. Under
+     * the descending reading that rule cannot be written at all — every variant
+     * would count towards a bound meant for the plain one alone.
+     *
+     * Applies to the SUBJECT only. {@link ifPresent} keeps descending, and
+     * deliberately: a guard asks "is there one of these at all", which is a
+     * question about the family whatever the bound beside it counts. A framework
+     * needing the exact reading on both sides has not turned up yet, and inventing
+     * a second flag for it would be data nobody can read.
+     */
+    exact?: boolean;
+    /** Fewest subjects one instance of the frame must carry. */
+    min?: number;
+    /** Most subjects one instance of the frame may carry. */
+    max?: number;
+    /**
+     * A GUARD: the bounds apply to a frame only while that frame also holds at
+     * least one element whose role is (or specialises) this one. A frame holding
+     * none is not judged at all — not "judged and found compliant", not walked.
+     *
+     * ## Why a notation needs this, and why it is not `min` with a different face
+     *
+     * Whole families of artefact are OPTIONAL on their own and NORMATIVE in
+     * pairs. A sketch may legitimately show neither a beginning nor an end; what
+     * it may not show is one without the other, because a reader who sees where
+     * the work finishes will look for where it starts, and finding nothing is a
+     * question the drawing cannot answer.
+     *
+     * An unconditional `min: 1` would state the wrong thing twice over: it would
+     * indict the perfectly legitimate sketch that declares neither, and it would
+     * be doing so in the name of a requirement the notation does not make. The
+     * PAIRING is the requirement, and a pairing is exactly a bound plus a guard.
+     *
+     * Two rules, mirrored, then say the whole of it — "if there is an end there
+     * must be a start", "if there is a start there must be an end" — and each is
+     * one line of data. That is the shape this field is for.
+     *
+     * ## Same attribution as the subject
+     *
+     * The guard element must be IN the frame, on the same containment-only
+     * reading {@link evaluateRoleCount} uses for the subjects it counts: an
+     * artefact floating beside a pool no more arms a requirement about that pool
+     * than it satisfies one. Absent, the bounds apply to every instance, which is
+     * what every rule written before this field means.
+     */
+    ifPresent?: RoleId;
+    /** Words for {@link min} — see {@link EdgeDegreeDef.tooFewIn}. */
+    tooFew?: RuleMessage;
+    /** Words for {@link max}. */
+    tooMany?: RuleMessage;
+}
+/**
+ * `edge-locality` configuration — a relation constrained relative to the frame
+ * instances its two ends sit on.
+ *
+ * The canonical pair a swimlane notation is built on, and both halves of it are
+ * one declaration away from each other: a sequence flow stays inside one pool
+ * (`same-background`), a message flow only exists BETWEEN pools
+ * (`cross-background`). Neither is expressible by {@link RelationEndpointsDef}:
+ * the two ends carry exactly the same roles in the legal case and the illegal
+ * one, and the only thing that differs is which frame each of them is drawn on.
+ */
+export interface EdgeLocalityDef {
+    /** The EDGE role being constrained, matched by {@link roleIsA}. */
+    edgeRole: RoleId;
+    /**
+     * `'same-background'` — the two ends must belong to ONE instance, and two
+     * different ones are the finding; `'cross-background'` — the two ends must
+     * belong to different instances, and one instance is the finding.
+     */
+    mode: 'same-background' | 'cross-background';
+}
+/**
+ * `reachability` configuration — every subject must be reachable from a declared
+ * ROOT by following typed edges.
+ *
+ * The orphan question, and the first one in this engine that no amount of
+ * looking at an element or at a relation can answer: a task with a perfectly
+ * good sequence flow on either side is still unreachable if the chain it belongs
+ * to never starts anywhere. Only the graph knows.
+ */
+export interface ReachabilityDef {
+    /**
+     * Where the traversal STARTS. Every element whose role is (or specialises)
+     * this one is a root, and a board carrying none silences the rule whole — see
+     * {@link evaluateReachability}, and {@link implicitRoots} for the second kind
+     * of root a notation with an optional start marker needs.
+     */
+    rootRole: RoleId;
+    /** The role whose elements must be reachable. */
+    subjectRole: RoleId;
+    /** The edge role that is FOLLOWED, source → target, and only that way. */
+    edgeRole: RoleId;
+    /**
+     * Also treat every SUBJECT that nothing points at as a root — in-degree zero
+     * along {@link edgeRole}.
+     *
+     * ## What this changes, and what it is for
+     *
+     * A notation where the explicit start marker is OPTIONAL has a second, silent
+     * way of saying "the work begins here": draw the artefact and point nothing at
+     * it. Two branches of a process running side by side, only one of them given a
+     * start marker, are both perfectly well-formed — and a traversal that only
+     * left from the marker would report the whole of the second branch as
+     * unreachable, which is a wall of brackets over a drawing that is right.
+     *
+     * ## What is left, exactly
+     *
+     * A subject fires when it has an incoming counted edge — so it is not an
+     * implicit root — and no root ever reaches it. Two shapes satisfy that, and
+     * the second one is easy to forget:
+     *
+     * 1. a RING entered from nowhere: artefacts pointing round at each other, each
+     *    with an incoming edge and none of them reachable from outside. The real
+     *    defect, and the one this reading exists to keep visible — work that can
+     *    never begin;
+     * 2. a subject fed ONLY by an edge the walk can never leave from: one whose
+     *    `source` is a dangling id, or an element whose role is neither
+     *    {@link rootRole} nor {@link subjectRole}. The edge disqualifies the
+     *    subject as an implicit root, and its source is never enqueued, so nothing
+     *    reaches it.
+     *
+     * The second shape is a BROKEN or FOREIGN edge, which is
+     * `relation-endpoints`' subject rather than this family's, and this family
+     * reports the consequence rather than the cause. It behaves identically with
+     * the flag off — it is inherited, not introduced here — so a framework that
+     * finds the report confusing wants a `relation-endpoints` rule beside this
+     * one, not a change to this flag.
+     *
+     * ## The zero-root gate still holds
+     *
+     * "No root on the board" becomes "no root of EITHER kind", and it is still
+     * total silence. In practice a board with any subject at all has an implicit
+     * root unless every subject is pointed at, so the gate stops being the thing
+     * that saves a blank sketch and becomes the thing that saves a board where the
+     * question genuinely does not arise.
+     *
+     * Absent or `false` is the original reading: only the declared role starts a
+     * traversal, and a board carrying no such element says nothing at all.
+     */
+    implicitRoots?: boolean;
+}
+/**
+ * `label-presence` configuration — the first brick of the PRD's *étiquetage*
+ * family, and the first family in this engine that reads an element's WORDS.
+ *
+ * "This step has no name." Every other family asks about geometry, roles or
+ * relations; this one asks whether the artefact says what it is. An unnamed box
+ * in the middle of a diagram is the one defect a reader cannot work around —
+ * they can infer a missing arrow from the layout, and they can infer nothing at
+ * all from an empty rectangle.
+ *
+ * ## Where the words come from
+ *
+ * The element's own `text`, read duck-typed exactly as {@link textInkBound}
+ * already reads it — the one property every artefact-bearing element model
+ * carries (a `Y.Text` on a shape, a connector label, a free text) and the only
+ * one the engine can read without importing a model. See {@link elementLabel}
+ * for what counts as empty.
+ *
+ * A framework whose artefacts are named by a SEPARATE element beside them — a
+ * text element sitting next to a node, the way a Wardley label does — is not
+ * asking this question, and this family cannot answer it: it reads the subject's
+ * own words and nothing else. That is a different family (a proximity between
+ * two roles), not a flag on this one.
+ */
+export interface LabelPresenceDef {
+    /**
+     * The subject must carry a label. Written as a literal rather than a boolean
+     * because it is a DISCRIMINANT and not a switch: `present: false` would mean
+     * "this artefact must stay unnamed", which no notation asks for. The field
+     * exists so the questions this family grows next — a maximum length, a
+     * pattern, a name that must match the zone it sits in — arrive as siblings
+     * beside it rather than as a second family.
+     */
+    present: true;
+}
+/**
+ * `view-admissibility` configuration — WHICH ROLES the frame admits, given the
+ * level the frame itself declares.
+ *
+ * The engine names no framework and no level. It is handed the PROP the frame
+ * writes its level in, and a table keyed by the VALUES that prop can take: the
+ * same idiom `backgroundLabelText` and `backgroundInVariant` already use to read
+ * a declared prop off an instance, promoted to a rule so a verdict can turn on
+ * it. C4 is the first consumer — `levelProp: 'level'`, keyed by
+ * `context` / `container` / `component` — and nothing here knows that.
+ *
+ * ## Why the table is FORBIDDEN and not ADMITTED
+ *
+ * Because the honest default for a view is permissive. A C4 context diagram
+ * legitimately shows the people and the neighbouring systems around the one it
+ * is about; a container diagram legitimately shows the persons, the systems and
+ * the system boundary it zooms into. An allow-list would have to enumerate
+ * every one of those, and would indict every artefact the framework's author
+ * forgot — including the free rectangles, the notes and the legend glyphs a
+ * whiteboard is made of. A deny-list says only what the notation actually
+ * refuses, and everything it does not name is left alone (PRD principle 8).
+ *
+ * A level the table has no entry for — or whose entry is empty — is a level the
+ * rule has nothing to say about, and it evaluates NOTHING there. That is what
+ * lets a framework declare the two levels that forbid something and stay silent
+ * on the one that forbids nothing, rather than shipping a rule that can never
+ * fire.
+ */
+export interface ViewAdmissibilityDef {
+    /**
+     * The prop the FRAME writes its level in, on the instance itself — `'level'`
+     * for a C4 board.
+     *
+     * A prop name and not a declared axis, a zone or a variant, because the level
+     * of a view is none of those: it is a fact the author states about the sheet,
+     * and the engine's job is to read it back where the framework says it is
+     * written. A frame whose prop holds nothing, or holds something that is not a
+     * non-empty string, has stated no level and is not judged.
+     */
+    levelProp: string;
+    /**
+     * Per level VALUE, the roles that view does not admit — matched by
+     * {@link roleIsA}, so naming a parent role covers its specialisations (C4's
+     * `c4:container` reaches `c4:database`, `c4:boundary` reaches both of its
+     * children).
+     *
+     * Own keys only when it is read: the table is an object literal shipped by a
+     * framework, so a frame whose level happened to say `'constructor'` must not
+     * resolve to something off the prototype.
+     */
+    forbidden: Readonly<Record<string, readonly RoleId[]>>;
+}
+/**
+ * `element-in-zone` configuration — the artefact is on the map, but is it in the
+ * right REGION of it?
+ *
+ * `element-in-background` frames a subject against the whole card; this frames
+ * it against the named zones the declaration already carries — the four
+ * quadrants of a Core Domain Chart, the phases of a Wardley map — so a rule can
+ * say "an outsourced subdomain has no business in the Core quadrant" without a
+ * single coordinate being restated anywhere.
+ *
+ * The zone rectangles come from the DECLARATION (ratios of the plot) resolved
+ * against the bounds of the instance the subject actually sits on, so the
+ * verdict survives the map being moved and resized, exactly like every other
+ * geometry in this engine.
+ */
+export interface ElementInZoneDef {
+    /**
+     * The zones this rule is about, by their id in
+     * {@link FrameworkBackgroundDef.zones}. An id the frame does not declare is a
+     * typo in the data: the rule warns once and evaluates NOTHING rather than
+     * quietly measuring against the zones it happened to recognise — a smaller
+     * union is a different rule, and nobody would see the difference.
+     */
+    zoneIds: readonly string[];
+    /**
+     * `'inside'` — the subject belongs in one of those zones and is indicted
+     * anywhere else on the map; `'outside'` — the zones are forbidden ground.
+     */
+    expect: 'inside' | 'outside';
+    /**
+     * WHAT of the subject is measured. `'center'` (the default) reads the centre
+     * of its bounds — where the eye puts the artefact, and the only honest answer
+     * for something bigger than a cell. `'extent'` reads the whole box: `inside`
+     * then asks for full containment in ONE cited zone and `outside` for no shared
+     * area at all.
+     *
+     * Containment is tested zone by zone rather than against their union: a
+     * subject straddling two adjacent cited zones is precisely the ambiguous case
+     * a strict rule wants to hear about, and a union test would swallow it.
+     */
+    measure?: 'center' | 'extent';
+}
+/**
+ * WHERE a rule's authority comes from.
+ *
+ * - `standard` — the rule restates a normative sentence of a published
+ *   specification. The tool is reporting a conformance defect.
+ * - `recommendation` — a SHOULD of the specification, or an industry linter's
+ *   rule (bpmnlint, and its equivalents elsewhere). Widely agreed practice; not
+ *   a conformance defect.
+ * - `labre-convention` — a house style of this editor, and nothing else. No
+ *   norm speaks of it, and the rule must never let a user believe one does.
+ * - `organization` — a level of requirement an ORGANISATION adds on top, which
+ *   the PRD names as future org profiles. Reserved: nothing declares it today.
+ */
+export type ProvenanceSource = 'standard' | 'recommendation' | 'labre-convention' | 'organization';
+/**
+ * Where a rule's authority comes from, as DATA rather than as prose buried in
+ * its message.
+ *
+ * A Labre convention presented as a norm violation is the one thing an
+ * architecture review will not forgive, and until now the distinction lived
+ * only in each rule's wording and in the comment above it — invisible to the
+ * UI, unqueryable by a host, unassertable by a test. Promoting it to a field is
+ * the same move the platform already made for severity and for moment: a rule
+ * says once, in its own declaration, what kind of thing it is.
+ *
+ * ## Purely descriptive
+ *
+ * **No evaluator reads it.** Not one of the fourteen family functions branches
+ * on it, `evaluateRules` and `evaluateCheckup` never look at it, and a rule
+ * declaring it evaluates identically to the same rule with the field removed
+ * ({@link ValidationRule.provenance} is pinned inert by a test). It exists for
+ * the violation bubble, for a conformance report, and for a host that wants to
+ * separate "your diagram breaks the standard" from "we suggest".
+ *
+ * ## One rule, one provenance
+ *
+ * The field describes THE RULE, so a rule whose clauses would answer
+ * differently is a rule that should be two — BPMN's sequence-flow endpoints
+ * (p.95, standard) and its no-self-loop house style split for exactly that
+ * reason, rather than declaring one provenance that is wrong half the time.
+ */
+export interface RuleProvenance {
+    /** Where this rule's authority comes from. */
+    source: ProvenanceSource;
+    /**
+     * Human-readable citation — e.g. `'OMG BPMN 2.0.2 (ISO/IEC 19510) p.244'` or
+     * `'bpmnlint no-duplicate-sequence-flows'`.
+     *
+     * Prose, deliberately, and displayed VERBATIM: a page number, a clause, a
+     * linter rule name and a book chapter have nothing in common but being
+     * readable, and a schema that tried to model all four would model none of
+     * them. It is never translated — a citation is the same in every language.
+     */
+    reference?: string;
+}
+/**
+ * A rule is declarative, versioned data owned by its framework (PRD principle
+ * 5) — never a subclass, never a closure. It is comparable, serializable and
+ * can be shipped by a host.
+ */
+export interface ValidationRule extends RuleMessage {
+    /** Stable id, namespaced by framework: `wardley.change-arrow-against-evolution`. */
+    id: string;
+    /** Owning framework, `wardley`. Rules never leave their framework. */
+    framework: string;
+    family: RuleFamily;
+    severity: ViolationSeverity;
+    /**
+     * When this rule runs. Absent = `'realtime'`, which is what every rule
+     * written before PF5.14 means and what the vast majority of rules want.
+     *
+     * `'on-demand'` takes the rule OUT of {@link evaluateRules} entirely — not
+     * out of the canvas affordance, out of the evaluation — and into
+     * {@link evaluateCheckup}, which only a user gesture calls.
+     */
+    moment?: ValidationMoment;
+    /**
+     * The role this rule is written on. An element matches when its own role IS
+     * that role or SPECIALISES it ({@link roleIsA}), so a rule on
+     * `wardley:component` covers `wardley:market` for free. An element with no
+     * role (a generalist square, a free text) never matches — proportionality,
+     * PRD principle 8.
+     *
+     * Absent for `no-overlap`, whose subjects are declared per PAIR, and for
+     * `view-admissibility`, whose subjects are declared per LEVEL: in both cases
+     * the rule has no single subject role, and naming one would be data that
+     * lies.
+     */
+    appliesTo?: RoleId;
+    /** The framework's role vocabulary, for the inheritance walk. */
+    roles: RoleDefs;
+    /** Bumped when the rule's meaning changes, so a host can pin behaviour. */
+    version: number;
+    /**
+     * Where this rule's authority comes from — see {@link RuleProvenance}.
+     *
+     * Optional, framework-agnostic and purely DESCRIPTIVE: the engine's
+     * evaluators never read it, so declaring it changes no verdict, no severity
+     * and no message. A rule that omits it simply says nothing about its
+     * authority, exactly as every rule did before the field existed.
+     */
+    provenance?: RuleProvenance;
+    /**
+     * The ROLE of the framework's background (`wardley:map`), i.e. the frame the
+     * subject roles are measured against.
+     *
+     * A role, not an element type: the engine never looks at a shape type, on
+     * either side of a rule (see `role.ts`). A background authored before its
+     * role existed carries none, frames nothing and raises nothing.
+     *
+     * Required by `element-in-background` and by any family reading the frame's
+     * declared facts; optional for `no-overlap`, where it only decides whether a
+     * finding can be waived map-wide.
+     */
+    backgroundRole?: RoleId;
+    /**
+     * The framework's background DECLARATION, carried as data exactly like
+     * {@link roles} is.
+     *
+     * This is what lets a rule read the frame's SEMANTICS — which axes it has and
+     * which way they run, where its zones meet — without the engine owning a
+     * registry of backgrounds or importing a renderer. The facts come out of
+     * `../framework-background/facts.js`, and are a pure function of this
+     * declaration plus the bounds of the instance a finding is measured against.
+     */
+    background?: FrameworkBackgroundDef;
+    /** `orientation-against-axis` only. */
+    against?: AgainstAxisDef;
+    /** `attachment` only. */
+    attachment?: AttachmentDef;
+    /** `no-overlap` only: the combinations that must not collide. */
+    overlap?: readonly OverlapPair[];
+    /** `relative-order-along-axis` only. */
+    relativeOrder?: RelativeOrderDef;
+    /** `relation-endpoints` only. */
+    endpoints?: RelationEndpointsDef;
+    /** `element-in-zone` only. */
+    inZone?: ElementInZoneDef;
+    /**
+     * `no-overlap` only: how DEEP a collision has to be, in model units, before
+     * it is worth reporting. Absent or `0` means any shared area at all.
+     *
+     * Penetration depth, not shared area: how far the two geometries reach INTO
+     * each other — `min(overlapX, overlapY)` for two boxes, and for a path the
+     * greatest distance any point of it gets under the edge of the box it
+     * crosses. A link clipping the corner of a name and a link drawn through the
+     * middle of it share the same "they overlap"; only the second one is
+     * something the eye trips over.
+     *
+     * Two paths crossing have no depth to measure — a line has no width — so a
+     * declared crossing is reported whatever this says.
+     */
+    minPenetration?: number;
+    /** `tone-convention` only. */
+    tone?: ToneConventionDef;
+    /** `majority-fact` only. */
+    majority?: MajorityDef;
+    /** `edge-degree` only: the subject nodes are named by {@link appliesTo}. */
+    degree?: EdgeDegreeDef;
+    /** `role-count` only: the frames are named by {@link backgroundRole}. */
+    roleCount?: RoleCountDef;
+    /** `edge-locality` only: the frames are named by {@link backgroundRole}. */
+    locality?: EdgeLocalityDef;
+    /** `reachability` only. */
+    reachability?: ReachabilityDef;
+    /** `label-presence` only: the subjects are named by {@link appliesTo}. */
+    label?: LabelPresenceDef;
+    /**
+     * `view-admissibility` only: the views are named by {@link backgroundRole},
+     * and the subjects by the level the view declares.
+     */
+    admissibility?: ViewAdmissibilityDef;
+}
+/**
+ * A level of requirement, as DATA (PF9) — the same declarative, versioned,
+ * host-shippable shape as a rule, a role or a background.
+ *
+ * A framework exposes several: Wardley ships a permissive learning profile and
+ * a strict one; BPMN would ship descriptive / analytic / executable. A profile
+ * says, for each rule of its framework, how hard that rule bites — or that it
+ * does not apply at all.
+ *
+ * ## What "absent from {@link rules}" means
+ *
+ * The rule keeps its OWN declared severity. A profile is an override table, not
+ * an allow-list: a rule the framework ships later must not silently vanish from
+ * a strict profile that was written before it existed. A profile that wants a
+ * rule gone says so — `'off'` — and a profile that wants it louder says that
+ * too. Nothing is ever raised implicitly (PF9.4): every severity a user gets is
+ * either the one the rule declares or one this table spells out.
+ *
+ * ## Scope
+ *
+ * A profile is CHOSEN per root instance, on the framework's background element
+ * (`GfxPrimitiveElementModel.validationProfile`) — see PF9.1. Two maps on one
+ * canvas therefore hold two independent levels of requirement.
+ *
+ * A background that names none INHERITS the choice made on the frame it is
+ * drawn inside ({@link inheritChosenProfiles}), and falls back to its
+ * framework's {@link isDefault} profile only when it sits inside nothing that
+ * chose. That is what lets a framework offer the picker on its outer frame
+ * alone and still govern the rules it frames against an inner one.
+ */
+export interface ValidationProfile {
+    /** Stable id, namespaced by framework: `wardley.sketch`. */
+    id: string;
+    /** Owning framework, `wardley`. A profile never applies across frameworks. */
+    framework: string;
+    /** i18n key of the human name; resolved by the host. No prose here either. */
+    labelKey: string;
+    /**
+     * The framework's own wording when the host ships no catalogue for the key —
+     * the same `labelKey` + `fallback` pair the background declaration uses for
+     * its axis and phase labels. The framework owns the word; the library still
+     * never invents one.
+     */
+    fallback?: string;
+    /**
+     * The one profile that applies when a background names none — and the one
+     * that, chosen explicitly, writes NOTHING on the element. It is the most
+     * permissive reasonable level, because the sketch wins (PRD principle 3).
+     */
+    isDefault?: boolean;
+    /** Severity override per rule id. A rule absent here keeps its own. */
+    rules: Readonly<Record<string, ProfileSeverity>>;
+}
+/**
+ * Severity `profile` gives `rule` — the rule's own when the profile is silent
+ * about it, or when there is no profile at all.
+ */
+export declare function profileSeverity(rule: ValidationRule, profile: ValidationProfile | undefined): ProfileSeverity;
+/**
+ * The profile a background of `framework` is checked against when it names
+ * none: the one flagged {@link ValidationProfile.isDefault}, or — failing that
+ * — the first one registered, so a framework that forgot the flag still has a
+ * resolvable answer instead of silently losing its profiles.
+ */
+export declare function defaultProfileOf(profiles: readonly ValidationProfile[], framework: string): ValidationProfile | undefined;
+/**
+ * The result of a rule that did not hold (PRD principle 6): an OBJECT, not a
+ * string and not a rendering. It names the rule, the elements at fault and an
+ * i18n key — never a sentence.
+ */
+export interface Violation {
+    ruleId: string;
+    /**
+     * The elements the rule indicts — one for an element-local family, TWO for
+     * `no-overlap` (which is about a pair and not about either half of it), and
+     * THREE for `relative-order-along-axis`: the two elements the relation links
+     * plus the edge that states it.
+     *
+     * The edge is in there deliberately. The finding has two honest resolutions —
+     * move a node, or reverse the relation — and the second one is only reachable
+     * from the edge, which carries the inversion command (`docs/adr/0010` M3). A
+     * finding that named the nodes alone would show the user two brackets and no
+     * way to the gesture that fixes half the cases.
+     *
+     * Always sorted by id, so the same situation reports the same way whichever
+     * order the surface happened to be walked in.
+     */
+    elementIds: string[];
+    severity: ViolationSeverity;
+    messageKey: string;
+    /** The framework's own wording for {@link messageKey}. */
+    messageFallback?: string;
+    /** i18n key of a remediation hint, when the rule carries one. */
+    suggestion?: string;
+    /** The framework's own wording for {@link suggestion}. */
+    suggestionFallback?: string;
+    /**
+     * The background this finding is attributed to — for `element-in-background`,
+     * the NEAREST one, none of them having contained the element (that is what
+     * being in violation means here).
+     *
+     * Recorded by the family at the moment it picks it, because nothing
+     * downstream can reconstruct it: a board carries several maps, and "which one
+     * did the user mean" is a question only the evaluation is in a position to
+     * answer. It is what makes the `map` exemption scope mean ONE map instead of
+     * every map on the document — see {@link ExemptionScope}.
+     *
+     * A heuristic, and an honest one: nearest by edge-to-edge gap
+     * ({@link gapSquared}), ties broken by the smaller id so that it never
+     * depends on the order the surface happened to be walked in.
+     *
+     * Absent for a family that measures against no background.
+     */
+    backgroundId?: string;
+    /**
+     * The named FRONTIER of that background the finding is about, when the family
+     * measured against one: `custom-built|product` for a transition band
+     * ({@link BackgroundTransitionBand}).
+     *
+     * "This bar is outside the equilibrium zone" is only half an answer — the
+     * other half is which zone it should have been in, and the band already knows
+     * its own name. Recorded at the moment the family picks the frontier, for the
+     * same reason {@link backgroundId} is: nothing downstream can reconstruct
+     * which of several transitions the user was aiming at.
+     *
+     * Absent for a family that measures against no such region.
+     */
+    boundaryId?: string;
+    /**
+     * Set when a user exception covers this finding (PF8), and names the SCOPE
+     * that covers it. Absent = live.
+     *
+     * The engine keeps reporting the violation either way — an exception changes
+     * its STATE, it never makes it vanish, so a board can never hide an
+     * arbitration it made (PF8.3). Suppressing the canvas affordance is a
+     * downstream filter ({@link liveViolations}); the panel and the bubble keep
+     * the whole list.
+     */
+    exemption?: ExemptionScope;
+}
+/**
+ * How far an exception reaches.
+ *
+ * - `element` — written on the element itself: the rule is disarmed for it and
+ *   for nothing else on the board (PF8.2).
+ * - `map` — written on ONE background element, the one named by the finding's
+ *   {@link Violation.backgroundId}: the rule is disarmed for the elements
+ *   measured against THAT map, and for no other map on the board (PF8.4).
+ *
+ * There is no third scope, and in particular no document-wide one: an exception
+ * is always carried by an element that can be selected, copied and deleted, so
+ * it has an owner, a lifetime and no hidden global state to garbage-collect.
+ * A board with three maps therefore holds three independent arbitrations, and
+ * deleting one map takes exactly its own with it.
+ */
+export type ExemptionScope = 'element' | 'map';
+/**
+ * Every element on the surface acting as a framework background for a REAL-TIME
+ * rule.
+ *
+ * Recorded by the manager after each evaluation, and read on the next one — the
+ * one fact about a deleted background that nothing else can reconstruct. See
+ * {@link ValidationManager._backgrounds}.
+ *
+ * ## Why the moment is filtered here too
+ *
+ * This runs on the gesture path, once per evaluation, and it is a FULL surface
+ * walk per rule. `evaluateRules` already refuses to walk an on-demand rule, so
+ * leaving it in here would have handed the drawing budget back exactly what the
+ * second moment took away from it — measured at +58 % on the manager's tick with
+ * the two Wardley check-up rules registered, and invisible to a bench that times
+ * `evaluateRules` alone.
+ *
+ * It is also the right answer and not merely the cheap one: `_backgrounds`
+ * exists to decide whether an incremental REAL-TIME pass must fall back to a
+ * full sweep. An on-demand rule never takes part in that pass, so the frames it
+ * measures against have nothing to invalidate — and a framework whose only rules
+ * are on-demand has no incremental pass to protect in the first place.
+ */
+export declare function backgroundElementIds(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[]): ReadonlySet<string>;
+/**
+ * The tone families a colour can fall into — the granularity a colour CONVENTION
+ * is actually written at ("the landscape is grey, red is what changes"), and
+ * deliberately not finer. A framework's palette entry and a user's colour are
+ * both reduced to one of these before they are compared.
+ */
+export type ColourTone = 'grey' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'purple' | 'magenta';
+/**
+ * Which tone family a colour belongs to, or `undefined` when the engine cannot
+ * honestly say.
+ *
+ * Two readings, in order: the NUMBER when the colour is a hex the process can
+ * actually see, and the NAME when it is a theme token it cannot. Anything else —
+ * `transparent`, a gradient, an `rgb()` triple, a variable with no tone in its
+ * name — is unclassifiable, and unclassifiable means silence: a convention rule
+ * that guessed would indict a user over a colour nobody here can see.
+ */
+export declare function toneOf(value: string | undefined): ColourTone | undefined;
+/**
+ * What a caller knows about a change, when it knows anything.
+ *
+ * `dirty` is every element id added, removed or updated since the findings in
+ * `previous` were computed. Handed in only by the manager's debounced path,
+ * where exactly that is known; every other caller — the first evaluation, a
+ * gesture that must land immediately, the bench, a test — evaluates in full.
+ *
+ * Only {@link evaluateNoOverlap} honours it. The element-local families are
+ * already constant per element and would gain nothing but a way to be subtly
+ * wrong.
+ */
+export interface IncrementalContext {
+    dirty: ReadonlySet<string>;
+    previous: readonly Violation[];
+}
+/** The exceptions an element carries, always an array, never a copy to keep. */
+export declare function elementExceptions(element: GfxPrimitiveElementModel): readonly ValidationException[];
+/** Whether `element` is excused from `ruleId`. */
+export declare function hasException(element: GfxPrimitiveElementModel, ruleId: string): boolean;
+/**
+ * Run every rule over every element. Pure and synchronous — the unit of the
+ * 16 ms budget (PF5.12), and the only thing the bench measures.
+ *
+ * `profiles` is the level of requirement in force (PF9). Omitted, every rule is
+ * judged by its own declared severity, which is exactly what a framework
+ * shipping no profile gets.
+ *
+ * `incremental` is what the caller knows about what CHANGED. Omitted — the
+ * default, and what every test and the bench's full-evaluation case pass — the
+ * whole surface is re-judged from scratch. Handed in, the pair-wise family
+ * re-tests only the couples a change can have affected; the answer is the same,
+ * it is just reached without walking the grid against itself.
+ */
+export declare function evaluateRules(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[], profiles?: readonly ValidationProfile[], incremental?: IncrementalContext): Violation[];
+/** The registered rules a check-up runs — and nothing else ever evaluates. */
+export declare function onDemandRules(rules: readonly ValidationRule[]): readonly ValidationRule[];
+/**
+ * Run the ON-DEMAND rules over the surface (PF5.14). The exact mirror of
+ * {@link evaluateRules}, for the moment the drawing path never touches.
+ *
+ * Synchronous and total: this is what a test, a host and a report call. The
+ * manager drives the same pipeline one rule at a time so a long check-up can
+ * yield the thread — see {@link ValidationManager.runCheckup} — and both reach
+ * the same answer, because both are {@link runRules}.
+ *
+ * The findings are ordinary {@link Violation} objects and go through the same
+ * profile and exception passes as any other. What makes them REMARKS rather
+ * than verdicts is where they land: they never reach `violations$`, so they
+ * never reach the timeline, the bracket or the badge. A framework declares them
+ * `audit` on top of that, which is the severity for "collected, invisible to the
+ * drawing user" — belt and braces, and the braces are structural.
+ */
+export declare function evaluateCheckup(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[], profiles?: readonly ValidationProfile[]): Violation[];
+/**
+ * One check-up, as the panel reads it: what it found, when it was asked for,
+ * and how far it has got.
+ *
+ * ONE timestamp for the whole run, taken when the user asked — a single click is
+ * a single question, whatever number of rules it happens to walk. The same rule
+ * `setException` follows for an arbitration.
+ *
+ * Session state, never persisted: a document says what it contains, not when
+ * somebody last looked at it.
+ */
+export interface CheckupRun {
+    /**
+     * The INSTANCE this run is about — the map the user asked about, and the only
+     * one its remarks are allowed to be measured on.
+     *
+     * A check-up walks the whole surface, because that is where the elements are;
+     * a board carries several maps, and without this the panel on one map would
+     * confidently list the components of the one next to it, and a map nobody has
+     * ever checked would show somebody else's timestamp. That is precisely the
+     * "tally over the whole surface" {@link evaluateMajorityFact} refuses to
+     * compute, reintroduced one layer up.
+     *
+     * The filter is applied in {@link ValidationManager.runCheckup}, on
+     * {@link Violation.backgroundId} — recorded by every family that measures
+     * against a frame — so `results` is already about this instance and nothing
+     * downstream has to remember to narrow it.
+     */
+    backgroundId: string;
+    /** Epoch ms, taken at the moment of the gesture. */
+    at: number;
+    /** The remarks so far — complete once {@link done} reaches {@link total}. */
+    results: readonly Violation[];
+    /** Rules evaluated so far. */
+    done: number;
+    /** Rules this run has to walk. `done < total` means it is still going. */
+    total: number;
+    /**
+     * Set when a rule threw and the run stopped early.
+     *
+     * The run is still reported FINISHED (`done === total`), because the one thing
+     * a failure must not do is leave the panel believing a check-up is in flight:
+     * that reads as "Checking…" for ever and disables the only button that could
+     * try again. A visible failure the user can retry beats a silent lock.
+     */
+    error?: true;
+}
+/**
+ * How long a check-up may hold the thread before yielding it back.
+ *
+ * One frame, so a check-up that turns out to be expensive costs a dropped frame
+ * at worst instead of a locked tab. A rule is the unit of interruption — the
+ * smallest slice that has a meaning — so a single rule slower than this still
+ * runs to completion and the next one waits for the following task.
+ *
+ * The rules shipped today cost well under a millisecond between them, so the
+ * yield never fires in the delivered configuration — which would leave the
+ * generation counter and the supersession path as code nothing reaches. It is
+ * therefore a DEFAULT rather than a constant: {@link ValidationManager.checkupSliceMs}
+ * is settable, and lowering it makes every rule a slice, which is how a test
+ * exercises the yield and the race with the real rules instead of a stub.
+ */
+export declare const CHECKUP_SLICE_MS = 16;
+/**
+ * Grant `ruleId` an exception on `element`, unless it already has one.
+ *
+ * The write goes through the declared `@field()` accessor, so it lands in the
+ * Y.Map, syncs to every peer, joins the undo stack and survives a copy — see the
+ * note on `GfxPrimitiveElementModel.validationExceptions`.
+ */
+export declare function grantException(element: GfxPrimitiveElementModel, ruleId: string, author?: string, now?: number): void;
+/** Remove `ruleId`'s exception from `element`, if it has one. */
+export declare function revokeException(element: GfxPrimitiveElementModel, ruleId: string): void;
+/** One stored exception, and the element it is actually written on. */
+export interface AnchoredException {
+    /** The element carrying the exception — a group member, or the element. */
+    element: GfxPrimitiveElementModel;
+    ruleId: string;
+}
+/**
+ * The exceptions `element` ANSWERS FOR, i.e. the ones a menu on it should be
+ * able to revoke.
+ *
+ * Same rule the canvas mark follows ({@link anchorOf}): an exception is
+ * answered for by the outermost canvas group containing the element that
+ * carries it, or by that element when it is not grouped. So the entry lives on
+ * the whole Wardley component rather than on the bare node inside it, moves
+ * down to the element the moment the group is dissolved, and appears on a
+ * framework background for the map-wide arbitration it carries.
+ *
+ * Reads STORED exceptions, not current violations: an exception outlives the
+ * violation that prompted it (move the component back onto the map and the
+ * finding goes, the arbitration stays), and it is the arbitration the user is
+ * asking to take back.
+ */
+export declare function exceptionsAnchoredOn(element: GfxPrimitiveElementModel, surface: SurfaceBlockModel): AnchoredException[];
+/** One rule's arbitration taken back, as reported to telemetry. */
+export interface RevokedException {
+    ruleId: string;
+    framework: string;
+    scope: ExemptionScope;
+    /** How many elements the single gesture wrote to. */
+    elementCount: number;
+}
+/** A framework registers its rules here; nothing else registers rules. */
+export declare const ValidationRuleIdentifier: import("../../global/di/types.js").ServiceIdentifier<ValidationRule> & (<U extends ValidationRule = ValidationRule>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Register a framework's rules. Call it from the FLAG-GATED view extension —
+ * validation is tooling, so a disabled framework must contribute nothing.
+ *
+ * ```ts
+ * context.register(ValidationRuleExtension(WARDLEY_RULES));
+ * ```
+ */
+export declare function ValidationRuleExtension(rules: readonly ValidationRule[]): ExtensionType;
+/** A framework registers its profiles here; nothing else registers profiles. */
+export declare const ValidationProfileIdentifier: import("../../global/di/types.js").ServiceIdentifier<ValidationProfile> & (<U extends ValidationProfile = ValidationProfile>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Register a framework's profiles. Call it from the FLAG-GATED view extension,
+ * beside {@link ValidationRuleExtension}: a level of requirement is tooling, so
+ * a disabled framework offers none — and the id already written on a background
+ * simply goes unread until the flag comes back.
+ *
+ * ```ts
+ * context.register(ValidationProfileExtension(WARDLEY_PROFILES));
+ * ```
+ */
+export declare function ValidationProfileExtension(profiles: readonly ValidationProfile[]): ExtensionType;
+/**
+ * A framework declaring that a ROLE is one of its root instances — with no rule
+ * to derive it from.
+ *
+ * ## Why this exists
+ *
+ * Until now, "is this element a framework's frame" was read off the registered
+ * rules: a rule names the role of the background it measures against, so the
+ * answer came for free and no framework had to say the same thing twice. It is
+ * still the answer for every framework that ships a rule, and this declaration
+ * changes none of it.
+ *
+ * What it fixes is the framework that ships NONE. Estuarine has nudges and a
+ * quality panel and nothing the tool can compute — a map's constraints are
+ * negotiated, not measured — so under the derived-only gate its background was a
+ * root instance of nothing, its checklist was offered on no element, and the
+ * only way to give it one would have been to invent a rule that never fires.
+ * Data claiming an effect it does not have is the one thing this engine has
+ * refused everywhere else (see the Wardley `blocking-overridable` note); so the
+ * gate gets a second, explicit source instead.
+ *
+ * Registered from the FLAG-GATED view extension, beside the rules and the
+ * nudges: being a root instance is what the tooling is offered ON, so it goes
+ * off with the tooling and the ids already written on the element go unread
+ * until the flag comes back.
+ */
+export interface ValidationFrameworkDef {
+    /** Owning framework, `estuarine`. */
+    framework: string;
+    /** The role its background carries — the same thing a rule's `backgroundRole` names. */
+    backgroundRole: RoleId;
+    /** The framework's role vocabulary, for the inheritance walk. */
+    roles: RoleDefs;
+}
+/** A framework declares its root instances here, when no rule already does. */
+export declare const ValidationFrameworkIdentifier: import("../../global/di/types.js").ServiceIdentifier<ValidationFrameworkDef> & (<U extends ValidationFrameworkDef = ValidationFrameworkDef>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Register a framework's root-instance declaration.
+ *
+ * ```ts
+ * context.register(
+ *   ValidationFrameworkExtension([
+ *     { framework: 'estuarine', backgroundRole: 'estuarine:map', roles: ESTUARINE_ROLES },
+ *   ])
+ * );
+ * ```
+ *
+ * Keyed by framework AND role, so a framework with two kinds of board declares
+ * both and neither silently replaces the other.
+ */
+export declare function ValidationFrameworkExtension(defs: readonly ValidationFrameworkDef[]): ExtensionType;
+/**
+ * The frameworks `role` is a ROOT INSTANCE of — the one test that decides
+ * whether an element is somebody's frame, and the only one.
+ *
+ * TWO sources, and they answer the same question:
+ *
+ * - a registered RULE naming this role as the background it measures against.
+ *   A rule that frames against a role is a framework saying "this is my map",
+ *   with no second registry to keep in step;
+ * - a registered {@link ValidationFrameworkDef}, for the framework whose whole
+ *   contribution is nudges and which therefore has no rule to be derived from.
+ *
+ * Pure, and exported, because every per-instance surface downstream — the
+ * profile picker, the nudge checklist, the check-up — is built on this answer,
+ * and a function taking its inputs is testable without a DI container, a
+ * surface or an editor.
+ *
+ * Empty for a neutral element, and for a background authored before its role
+ * existed: no role, no framework, no tooling.
+ */
+export declare function frameworksOfRole(role: RoleId | undefined, rules: readonly ValidationRule[], frameworkDefs?: readonly ValidationFrameworkDef[]): ReadonlySet<string>;
+/**
+ * Element props that can change a verdict, WHATEVER the registered rules are.
+ * Everything else — `opacity` and the other `@local()` fields, colours,
+ * labels — is ignored, so brushing a canvas (`SpotlightManager` writes
+ * `opacity` on every element it dims) neither re-evaluates the surface nor
+ * pushes the pending evaluation further away.
+ *
+ * A framework can add to this list without the engine learning its name: see
+ * {@link verdictPropsOf}.
+ */
+export declare const VERDICT_PROPS: string[];
+/**
+ * {@link VERDICT_PROPS} plus what the REGISTERED rules make verdict-bearing.
+ *
+ * A framework background can carry visibility toggles, and one of them may be
+ * the toggle that shows the frontiers a rule measures against — hide the
+ * dashed columns of a Wardley map and the findings about them stop being
+ * findings ({@link backgroundTransitionBands}). Without this the toggle would be
+ * as inert as a colour: the marks would stay on screen until some unrelated
+ * drag happened to wake the engine, which is a board that lies about a document
+ * that has already changed.
+ *
+ * Derived from the DECLARATIONS the engine was handed, never from a name it
+ * knows: `backgroundTransitionVisibleProps` reads the prop each framework
+ * writes beside the line it gates. A framework whose background declares no
+ * toggle contributes nothing and the set is the constant.
+ *
+ * ## `text`, and why it is not in the constant
+ *
+ * `label-presence` is the one family whose verdict turns on an element's words,
+ * and words are what a user changes by TYPING. Watched unconditionally, every
+ * keystroke in every shape on the board would wake the debounced evaluation —
+ * a cost paid by every document, for a question most of them never ask.
+ *
+ * So it is added exactly when a REAL-TIME rule of that family is registered.
+ * The moment filter is deliberate and mirrors {@link backgroundElementIds}: an
+ * on-demand rule is never evaluated on the gesture path, so waking that path for
+ * it would hand back precisely what declaring the second moment bought — and a
+ * framework that wants its naming checked while the user types says so by
+ * declaring the rule real-time, which is the one place that decision belongs.
+ */
+export declare function verdictPropsOf(rules: readonly ValidationRule[]): ReadonlySet<string>;
+/**
+ * Whether an `elementUpdated` payload can have changed a verdict.
+ *
+ * It has to read `oldValues` as well as `props`, because a Y.Map **delete**
+ * fills only the former (`syncElementFromY` puts a key in `props` for `add` and
+ * `update` only). `validationExceptions` is the first {@link VERDICT_PROPS}
+ * entry whose normal life includes being removed — `xywh` and `rotate` are
+ * never deleted, `role` is only ever added — so this branch had never been
+ * exercised. Reading `props` alone means an UNDO of an exception, which deletes
+ * the key, wakes nothing: the board keeps showing a finding as excused when the
+ * document no longer says so, and its Revoke button becomes a no-op.
+ *
+ * A payload carrying neither is unreadable, so it counts as "might have": the
+ * cost of a spurious re-evaluation is a debounce tick, the cost of a missed one
+ * is a board that lies.
+ */
+export declare function touchesVerdict(payload: {
+    props?: Record<string, unknown>;
+    oldValues?: Record<string, unknown>;
+}, watched?: ReadonlySet<string> | readonly string[]): boolean;
+/**
+ * Owns the evaluation and the reactive violation list. No-op until a framework
+ * registers a rule.
+ */
+export declare class ValidationManager extends InteractivityExtension {
+    static key: string;
+    /**
+     * Current violations. The reactive seam a host panel (wave 2) subscribes to;
+     * wave 1 ships only the canvas affordance.
+     */
+    readonly violations$: import("@preact/signals-core").Signal<readonly Violation[]>;
+    /**
+     * Level 3 — what an AI audit reported, and ONLY that (PF14.1).
+     *
+     * A second signal rather than a marked subset of {@link violations$}, and the
+     * reason is the invariant the whole audit seam exists to protect: **the
+     * deterministic engine never depends on the AI**. Nothing in `evaluate()`
+     * reads this signal, writes it or is slowed by it; nothing here is ever
+     * recomputed, carried over by an incremental pass, or judged by a profile.
+     * The 16 ms budget is measured on a function that cannot see this field.
+     *
+     * Merging the two lists and discriminating by severity would have been
+     * cheaper to type and much more expensive to reason about: every consumer of
+     * `violations$` — the overlay, the timeline, the bubble, the exception
+     * toolbar, `userFacingViolations`, the incremental carry-over — would have
+     * had to learn to skip entries it must never touch, and forgetting one of
+     * them in some future slice would put a model's opinion behind a canvas
+     * bracket. Two signals make that a type error instead of a review.
+     *
+     * The findings ARE violation objects (`AuditFinding` is assignable to
+     * {@link Violation}, pinned by a test), so a host panel renders them with the
+     * code it already has. They are session state, never persisted: an audit is
+     * an opinion at a moment, and the document says what it contains, not what a
+     * model thought of it on Tuesday.
+     */
+    readonly auditFindings$: import("@preact/signals-core").Signal<readonly AuditFinding[]>;
+    /**
+     * Publish an audit's results. The ONLY writer of {@link auditFindings$}, and
+     * deliberately dumb: it stores, it does not evaluate, re-judge or merge.
+     *
+     * Replaces rather than appends — a run's findings are a whole answer about
+     * the board as it was, so accumulating two runs would show a user a
+     * contradiction and call it a list.
+     */
+    setAuditFindings(findings: readonly AuditFinding[]): void;
+    /**
+     * Which violations are still FRESH, i.e. still owed the loud bracket.
+     *
+     * It lives here rather than inside the overlay because the affordance has two
+     * halves on two different technologies — a canvas bracket that fades, and a
+     * DOM badge that takes over — and they are mutually exclusive: the badge
+     * appears only once the bracket is fully gone. Two copies of "when did I
+     * first see this" would drift, and the handover would show both at once or
+     * neither.
+     *
+     * Session state, never persisted: a document says which rules it breaks, not
+     * when you happened to look at them.
+     */
+    readonly timeline: ViolationTimeline;
+    /**
+     * The last check-up (PF5.14), or `null` while none has been asked for.
+     *
+     * A SEPARATE signal from {@link violations$}, and that separation is the whole
+     * design: a remark never reaches the timeline, the bracket or the badge,
+     * because it never reaches the list those three read. "Outside the canvas
+     * affordance" is therefore a property of the wiring, not a filter somebody has
+     * to remember to apply.
+     *
+     * Reset to `null` on unmount and never persisted: a document says what it
+     * contains, not when somebody last checked it.
+     */
+    readonly checkup$: import("@preact/signals-core").Signal<CheckupRun | null>;
+    /**
+     * The element whose Map quality panel is OPEN, or `null` — the seam between
+     * the toolbar entry that asks for it (`validation-toolbar.ts`, PF7.11) and the
+     * widget that draws it.
+     *
+     * A signal rather than a DOM call because the two live in different trees: the
+     * entry is a lit template inside `editor-menu-button`'s shadow root, and the
+     * panel is a widget on the root block. Session state, like every other "what
+     * is open" in this file.
+     */
+    readonly mapQualityFor$: import("@preact/signals-core").Signal<string | null>;
+    private _pending;
+    /**
+     * Bumped by every {@link runCheckup}, so a run that yielded the thread can
+     * tell it has been superseded and drop its partial results on the floor
+     * instead of overwriting a newer answer.
+     */
+    private _checkupGeneration;
+    /**
+     * How long {@link runCheckup} may hold the thread between two rules.
+     *
+     * Settable rather than fixed so the interruption and the supersession are
+     * TESTABLE with the rules a framework actually ships: at the shipped default
+     * the Wardley check-up costs half a millisecond and never yields, which would
+     * leave the whole race path unreached by anything. Dropped to zero, every rule
+     * becomes a slice.
+     */
+    checkupSliceMs: number;
+    /**
+     * Element ids added, removed or updated since the last verdict — the dirty
+     * set of PF5.13. Filled by the subscriptions, drained by every evaluation.
+     */
+    private _dirty;
+    /** Whether {@link violations$} holds a verdict a dirty set can build on. */
+    private _evaluated;
+    /**
+     * The ids that were framework BACKGROUNDS at the last evaluation.
+     *
+     * `no-overlap` already sends the surface back through a full sweep when a
+     * frame is touched, and it finds a DELETED one by looking for its id in the
+     * previous findings — the only trace a departed element leaves. That trace
+     * does not exist when the frame's profile put the rule on `'off'`: the
+     * findings measured against it were dropped by `applyProfiles`, so `previous`
+     * is empty, the deletion looks like an ordinary one, and the overlap that
+     * comes back to life under the default profile is never reported. No family
+     * can close that hole — an element that is gone from the surface AND absent
+     * from the findings is invisible to everything except a memory of it.
+     *
+     * So the manager keeps that memory. A dirty id that used to be a background
+     * forces the full pass, whatever the previous findings say or fail to say —
+     * which makes `incremental === full` true by construction rather than by the
+     * luck of no shipped profile using `'off'` yet.
+     */
+    private _backgrounds;
+    private _rules;
+    /** Registered rules, resolved once. Empty when every framework is flagged off. */
+    private get _activeRules();
+    private _verdictProps;
+    /**
+     * The props worth re-evaluating for, given what is registered. Resolved once,
+     * beside the rules it is derived from — see {@link verdictPropsOf}.
+     */
+    private get _watchedProps();
+    private _nudges;
+    /**
+     * Registered nudges, resolved once. Empty when no framework ships one, or
+     * when every framework is flagged off.
+     */
+    private get _activeNudges();
+    private _frameworks;
+    /**
+     * Registered root-instance declarations, resolved once. Empty when every
+     * framework derives its frames from its rules, which is all of them but the
+     * ones that ship no rule at all — see {@link ValidationFrameworkDef}.
+     */
+    private get _activeFrameworks();
+    private _profiles;
+    /**
+     * Registered profiles, resolved once. Empty when no framework ships one, in
+     * which case every rule is judged by its own declared severity.
+     */
+    private get _activeProfiles();
+    private _subscriptions;
+    private _disposeSurfaceEffect;
+    private get _overlay();
+    mounted(): void;
+    unmounted(): void;
+    private _unsubscribe;
+    private _resubscribe;
+    private _schedule;
+    /**
+     * Evaluate now. Exposed so a host (and the bench) can drive it directly.
+     *
+     * `incremental` is the DEBOUNCED path's privilege and nobody else's: it is
+     * the only caller that knows exactly which elements moved since the last
+     * verdict. Everything else — a gesture that must land on the spot, a surface
+     * arriving, a host asking — pays for a full pass, because a full pass is
+     * always right and a wrong dirty set is a board that lies.
+     */
+    evaluate(incremental?: boolean): void;
+    /** The registered rule with this id, if its framework is enabled. */
+    ruleOf(ruleId: string): ValidationRule | undefined;
+    /**
+     * The profiles selectable on `element`, i.e. those of every framework it is a
+     * ROOT INSTANCE of ({@link frameworksOf}).
+     *
+     * Gated for free: flag off, nothing registered, no framework, no profile
+     * offered. A framework that ships profiles and is a root instance of nothing —
+     * neither a rule framing against the role nor a declaration naming it —
+     * offers nothing to choose between, correctly.
+     *
+     * Empty for a neutral element, and for a background authored before its role
+     * existed: no role, no framework, no profile.
+     */
+    profilesFor(element: GfxPrimitiveElementModel): readonly ValidationProfile[];
+    /**
+     * The frameworks `element` is a ROOT INSTANCE of — those with a registered
+     * rule measuring against a background carrying this element's role, and those
+     * that declared the role outright ({@link ValidationFrameworkDef}).
+     *
+     * The one test that decides whether an element is a framework's frame, and the
+     * only one: every per-instance surface (the profile picker, the nudge
+     * checklist, the check-up) agrees about what a root instance is without any of
+     * them saying so twice. Both sources are registered from the flag-gated view
+     * extension, so it stays gated for free — flag off, nothing registered, no
+     * framework.
+     *
+     * Empty for a neutral element, and for a background authored before its role
+     * existed.
+     */
+    frameworksOf(element: GfxPrimitiveElementModel): ReadonlySet<string>;
+    /**
+     * The nudges offered on `element` (PF7.10), in declared order.
+     *
+     * Same derivation as {@link profilesFor} and gated the same way: a framework
+     * that registers no nudge — or whose flag is off — offers none, and the ids
+     * already ticked on the element stay written, unread, until it comes back.
+     */
+    nudgesFor(element: GfxPrimitiveElementModel): readonly QualityNudge[];
+    /** The on-demand rules a check-up on `element` would walk (PF5.14). */
+    checkupRulesFor(element: GfxPrimitiveElementModel): readonly ValidationRule[];
+    /**
+     * Whether `element` has a Map quality panel to open at all: a framework of
+     * its own declaring a NUDGE.
+     *
+     * The panel is the checklist and nothing else since the PO recette of
+     * 02/08/2026, so this asks for the checklist and nothing else — a framework
+     * that declared only on-demand rules would otherwise be offered a panel with
+     * nothing in it. {@link checkupRulesFor} and {@link runCheckup} are unchanged
+     * and unrelated: a host can still ask for a check-up, it simply is not what
+     * this panel is.
+     *
+     * Generic by construction (PF7.11) — nothing here names a framework. A second
+     * framework shipping nudges gets the entry and the panel with no code written
+     * anywhere.
+     */
+    hasMapQuality(element: GfxPrimitiveElementModel): boolean;
+    /**
+     * Open the Map quality panel on `element`; the widget draws it.
+     *
+     * Opening on a DIFFERENT instance forgets the last check-up. The panel already
+     * refuses to render a run belonging to another map ({@link CheckupRun.backgroundId}),
+     * so this is not what makes the display correct — it is what stops a result
+     * measured on a map the user has moved on from (or deleted) sitting in memory
+     * waiting to be shown again. Reopening on the SAME map keeps its stamp, which
+     * is the one case where "last check-up: 01:51" is worth reading.
+     */
+    openMapQuality(element: GfxPrimitiveElementModel): void;
+    closeMapQuality(): void;
+    /**
+     * Drop the current check-up when it is about `backgroundId` — or, with
+     * `unless`, when it is about anything else.
+     *
+     * The two callers are the two ways a run stops being about something the user
+     * can look at: the instance it measured was deleted, and the panel moved to a
+     * different instance.
+     */
+    private _forgetCheckupOf;
+    /**
+     * Run the check-up on `element` (PF5.14).
+     *
+     * ## It is about ONE instance
+     *
+     * The walk covers the whole surface — that is where the elements are — but the
+     * ANSWER is narrowed to the map that was asked about, on
+     * {@link Violation.backgroundId}, which every family measuring against a frame
+     * already records. A board carrying two Wardley maps holds two independent
+     * answers, and handing the panel a tally over both would be exactly the
+     * whole-surface count {@link evaluateMajorityFact} goes out of its way not to
+     * compute. Narrowed HERE and not at the rendering: a run that reaches a host,
+     * a report or the agent has to already be about one map.
+     *
+     * ## Why this is async, for two rules that take a microsecond
+     *
+     * Because the moment exists precisely so that a framework may ship a control
+     * that does NOT fit a frame. A check-up walks the surface with no dirty set
+     * and no budget over its head, and the honest way to offer that is to be
+     * interruptible: the driver evaluates ONE RULE at a time — the smallest slice
+     * that has a meaning — and yields the thread whenever the slice has held it
+     * for {@link checkupSliceMs}. The panel sees `done` climb towards `total`, so
+     * progress is the same value the results arrive in and there is no second
+     * signal to keep in step.
+     *
+     * A run started while another is still yielding SUPERSEDES it: the older one
+     * notices its generation is stale on its next slice and drops what it had.
+     * Clicking twice therefore gives the second answer, never a race between two.
+     *
+     * ## A rule that throws
+     *
+     * ...ends the run, visibly. The failure must not leave the panel believing a
+     * check-up is in flight — that reads as "Checking…" for ever and disables the
+     * one button that could try again, on every map, until the editor is
+     * remounted. So the run is finished with {@link CheckupRun.error} and whatever
+     * it had managed to collect.
+     *
+     * @returns the finished run, or `null` if it was superseded or there was
+     * nothing to run.
+     */
+    runCheckup(element: GfxPrimitiveElementModel): Promise<CheckupRun | null>;
+    /**
+     * The profile `element` is actually checked against — the one it names, or
+     * its framework's default. `undefined` when it is not a root instance of any
+     * enabled framework, or when its framework ships no profile.
+     */
+    profileOf(element: GfxPrimitiveElementModel): ValidationProfile | undefined;
+    /**
+     * Put `element` on `profileId`, and re-judge the board on the spot.
+     *
+     * Choosing the DEFAULT clears the key rather than writing it, so a background
+     * that never left the default stays byte-identical to one created before
+     * profiles existed — and a user who tries strict and comes back leaves no
+     * trace. Everything else is one flat string in the same `@field()` the role
+     * and the exceptions live in: it syncs, it undoes, it survives a copy and an
+     * export, with no block schema change.
+     *
+     * Exceptions are deliberately left alone. A level of requirement is not an
+     * amnesty: raising it must not resurrect decisions the user made, and
+     * lowering it must not quietly delete them (PF9.3).
+     *
+     * @returns whether the document actually changed.
+     */
+    setProfile(element: GfxPrimitiveElementModel, profileId: string): boolean;
+    /**
+     * Which elements an exception of the given scope is written on.
+     *
+     * `element` — the elements the rule actually indicts, which is what makes the
+     * exception local (PF8.2): excusing one component says nothing about the next.
+     *
+     * `map` — the background element these findings were MEASURED AGAINST, and
+     * only that one. It comes from {@link Violation.backgroundId}, recorded by the
+     * rule family when it picked the frame, so a board carrying three maps holds
+     * three independent arbitrations and a gesture made on one writes on one.
+     * That choice is what lets a map-wide arbitration exist with NO block schema
+     * change and no hidden per-document store: it is one more value in the same
+     * `@field()`, on an element that is selected, copied, exported and deleted
+     * like any other. A family that measures against no background records no
+     * `backgroundId`, has no map to hang an exception on, and offers no map scope.
+     */
+    private _targetsOf;
+    /**
+     * Grant or revoke `ruleId`'s exception at `scope`, over the elements the given
+     * violations indict.
+     *
+     * Takes the whole set rather than one violation on purpose: a Wardley
+     * component is a GROUP, so one bubble line can stand for several indicted
+     * members, and one click has to settle all of them.
+     *
+     * Re-evaluates on the spot instead of waiting for the 120 ms debounce the
+     * field write would trigger anyway — the gesture must apply immediately
+     * (PF8.1).
+     *
+     * @returns the elements actually written to, so the caller can tell a real
+     * arbitration from a no-op and only report the former.
+     */
+    setException(violations: readonly Violation[], scope: ExemptionScope, granted: boolean, author?: string): GfxPrimitiveElementModel[];
+    /**
+     * The exceptions on `element` that can still be taken back — those it answers
+     * for ({@link exceptionsAnchoredOn}) whose rule is actually REGISTERED.
+     *
+     * The rule filter is what makes the menu entry disappear with the framework:
+     * flag off, no rule reaches the container, so there is nothing to arbitrate
+     * on and nothing to offer. The exceptions themselves are untouched — they are
+     * document data and outlive the tooling (PF8.6).
+     */
+    revocableExceptionsOn(element: GfxPrimitiveElementModel): AnchoredException[];
+    /**
+     * Take back every exception `element` answers for, in one gesture.
+     *
+     * @returns one entry per (rule, scope) actually written, so the caller can
+     * report the arbitration and tell a real one from a no-op.
+     */
+    revokeExceptionsOn(element: GfxPrimitiveElementModel): RevokedException[];
+}
+/**
+ * What SHAPE the anchor is, and therefore where its persistent badge belongs.
+ *
+ * The same split {@link RoleKind} makes for MEASURING, made here for MARKING,
+ * and for the same reason: the bounding box of a diagonal link covers half the
+ * map, so its top-right corner is a point on the white paper with nothing under
+ * it. The PO's capture of 02/08 is exactly that — an amber dot floating a
+ * hundred units away from the trait it accuses.
+ *
+ * - `node` — marked on the top-right corner of its bounds, as before.
+ * - `edge` — marked on the MIDDLE of the link: the midpoint of the drawn path
+ *   when the element exposes one, and otherwise the intersection of the
+ *   bounding rectangle's diagonals, which is its centre.
+ */
+export type ViolationAnchorKind = 'node' | 'edge';
+/**
+ * One anchor and everything reported against it: where to draw, and what the
+ * detail bubble has to list when the badge on it is clicked.
+ */
+export interface ViolationAnchor {
+    /** The element the mark is drawn on — the outermost group, or the element. */
+    id: string;
+    bound: Bound;
+    /** What the mark is pinned to. See {@link ViolationAnchorKind}. */
+    kind: ViolationAnchorKind;
+    /**
+     * Where the persistent badge is pinned, in MODEL space — the one point both
+     * the badge and the bubble it opens are laid out from.
+     *
+     * Computed here rather than by the widget so it is one pure function of the
+     * document, testable with asserted coordinates and identical for every
+     * surface that ever draws a mark.
+     */
+    markAt: [number, number];
+    violations: Violation[];
+}
+/**
+ * Group violations by the anchor their mark is drawn on — one entry per
+ * anchor, so several violating members of the same group share a single
+ * bracket, a single badge and a single bubble.
+ *
+ * Pure and stateless, and called at paint time by both halves of the
+ * affordance, so the mark follows a group that moves and falls back onto the
+ * element the moment the group is dissolved, with nothing to invalidate.
+ *
+ * @param vocabularies the registered role vocabularies, for the SEMANTIC half
+ * of "is this an edge" ({@link anchorKindOf}). Optional: a caller that only
+ * reads `bound` — the canvas overlay draws the same bracket either way — needs
+ * none, and still gets the geometric answer.
+ */
+export declare function resolveViolationAnchors(violations: readonly Violation[], surface: SurfaceBlockModel, vocabularies?: readonly RoleDefs[]): ViolationAnchor[];
+/**
+ * Violations the drawing user is meant to SEE. `audit` is collected for
+ * reporting and stays invisible on the canvas — that is what the severity
+ * means (see {@link ViolationSeverity}), and the UI is the only place that can
+ * honour it: the engine reports everything, unfiltered, to the host panel.
+ */
+export declare function userFacingViolations(violations: readonly Violation[]): Violation[];
+/**
+ * Violations still asking for something, i.e. not covered by an exception.
+ *
+ * This is the whole of PF8's canvas behaviour: an exempted finding is dropped
+ * from the timeline, so it never flashes, and from the overlay, so it carries no
+ * bracket. It keeps its badge and its line in the bubble, where it reads as
+ * "exception" and can be revoked — the state changed, the finding did not
+ * disappear.
+ */
+export declare function liveViolations(violations: readonly Violation[]): Violation[];
+/**
+ * One violation per RULE, first occurrence wins.
+ *
+ * What a detail bubble renders is rule-level — a label, a severity, a hint —
+ * so two components of the same group both drawn off the map, which are two
+ * violations, would produce the same sentence twice. The engine is right to
+ * report both (it names the elements); a list that repeats itself is just
+ * noise. Which member moved is on the canvas, not in a list.
+ */
+export declare function distinctByRule(violations: readonly Violation[]): Violation[];
+/**
+ * How loudly an ANCHOR is drawn: the loudest of the violations sharing it, so
+ * a fresh finding is not muted by an older one on the same group.
+ *
+ * The single arbiter between the two markers. `> 0` means the bracket still has
+ * the anchor; exactly `0` means it is done and the badge takes over. Both
+ * halves call this, on the same timeline, so they can never both claim it.
+ */
+export declare function anchorEmphasis(anchor: ViolationAnchor, timeline: ViolationTimeline, now: number): number;
+/**
+ * Gap between the anchor's bounds and the mark, in MODEL units. Exported
+ * because the badge sits ON the bracket's top-right corner and has to use the
+ * same gap to land there.
+ */
+export declare const VIOLATION_MARK_PADDING = 6;
+/** Diameter of the persistent badge, in MODEL units. */
+export declare const VIOLATION_BADGE_SIZE = 16;
+/** The one amber the affordance is drawn in, canvas and DOM alike. */
+export declare const VIOLATION_MARK_COLOR = "#f5a623";
+/**
+ * The EPHEMERAL half of the PF7 affordance: amber corner brackets that flash on
+ * the anchor of a violation the moment it appears, hold for a few seconds, then
+ * fade out (see {@link ViolationTimeline}). What stays behind afterwards is the
+ * badge — `affine-violation-detail-widget`, a DOM sibling of this overlay.
+ *
+ * The handover is strict: an anchor whose emphasis has reached zero is skipped
+ * here and picked up by the badge, so the two markers are never on screen at
+ * the same time. {@link anchorEmphasis} is the single arbiter, read from the
+ * one timeline the manager owns.
+ *
+ * An overlay rather than a renderer change: it touches no element model, writes
+ * nothing to the document, creates no undo entry, and disappears with the rule
+ * that produced it. The fade is session state too — nothing about "when did I
+ * first see this" ever reaches the document.
+ *
+ * The mark is anchored on the outermost enclosing canvas group rather than on
+ * the bare element — see {@link resolveMarkAnchors}. Evaluation is untouched by
+ * this: it stays on the element carrying the role, because its position is what
+ * the rule is about.
+ */
+export declare class ValidationOverlay extends Overlay {
+    static overlayName: string;
+    /**
+     * The violations themselves — NOT their bounds, and not their groups either.
+     * Both are resolved at paint time so the mark tracks what it accuses:
+     * evaluation is debounced, the renderer is not, so a frozen snapshot would
+     * leave the bracket behind at the drag's starting point until 120 ms after
+     * the user let go — and a dissolved group would keep framing nothing.
+     */
+    private _violations;
+    /**
+     * Handed in with the violations by {@link ValidationManager}, which owns it —
+     * the DOM badge reads the same instance, and the two markers must never
+     * disagree about whether the bracket is done.
+     */
+    private _timeline;
+    /** Armed only while something is still fading. */
+    private _frame;
+    /**
+     * Whether the renderer this overlay paints into is gone.
+     *
+     * It matters because the two ends of the affordance are on different
+     * lifecycles: the overlay dies with the surface COMPONENT (the renderer
+     * disposes it), while {@link ValidationManager} lives on the gfx scope and
+     * keeps its subscriptions on the surface MODEL, which outlives the component.
+     * So an evaluation can perfectly well land here after teardown — switch to
+     * page mode, edit the doc — and without this flag it would arm an animation
+     * loop repainting a dead renderer sixty times a second for three seconds.
+     *
+     * Not permanent: the overlay is a DI singleton and is handed a new renderer
+     * if the surface comes back.
+     */
+    private _detached;
+    private readonly _onFrame;
+    /**
+     * Repaint, and keep repainting for as long as a mark is inside its window.
+     *
+     * This is the only clock the affordance runs, and it stops on its own: a
+     * board with no violation, or whose violations have all settled, requests no
+     * animation frame at all.
+     */
+    private _schedule;
+    private _cancelFrame;
+    private _forget;
+    /**
+     * @param violations already filtered to what the user is meant to see.
+     * @param timeline the manager's, already synced against these violations.
+     */
+    setViolations(violations: readonly Violation[], timeline: ViolationTimeline): void;
+    setRenderer(renderer: CanvasRenderer | null): void;
+    clear(): void;
+    dispose(): void;
+    render(ctx: CanvasRenderingContext2D, _rc: RoughCanvas): void;
+}