@formicoidea/labre-core 0.30.1 → 0.32.0

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

@@ -0,0 +1,1340 @@
+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.
+ */
+export type RuleFamily = 'element-in-background' | 'orientation-against-axis' | 'attachment' | 'no-overlap' | 'relative-order-along-axis' | 'tone-convention' | 'majority-fact';
+/**
+ * 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;
+}
+/**
+ * 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: 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;
+    /**
+     * 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;
+    /**
+     * `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;
+}
+/**
+ * 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, and a background
+ * that names none is checked against its framework's {@link isDefault} profile.
+ */
+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;
+/**
+ * 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.
+ */
+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 _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 that
+     * measures against a background carrying this element's ROLE.
+     *
+     * Derived from the registered rules rather than from a second registry: a
+     * rule already names the role of the frame it measures against
+     * (`backgroundRole`), which is the only thing that makes an element a root
+     * instance in the engine's eyes. So the answer is gated for free — flag off,
+     * no rule, no profile offered — and a framework that ships profiles but no
+     * rule 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, i.e. those with a registered
+     * rule measuring against a background carrying this element's role.
+     *
+     * The one test that decides whether an element is a framework's frame, and the
+     * only one: it is derived from the registered rules rather than from a second
+     * registry, so it is gated for free — flag off, no rule, no framework — and
+     * 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.
+     *
+     * 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;
+}