@formicoidea/labre-core 0.32.0 → 0.34.1

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

@@ -61,8 +61,34 @@ export type ProfileSeverity = ViolationSeverity | 'off';
  * - `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' | 'tone-convention' | 'majority-fact';
+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).
  *
@@ -296,6 +322,642 @@ export interface RelativeOrderDef {
      */
     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
@@ -324,14 +986,25 @@ export interface ValidationRule extends RuleMessage {
      * 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.
+     * 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.
@@ -364,6 +1037,10 @@ export interface ValidationRule extends RuleMessage {
     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.
@@ -383,6 +1060,21 @@ export interface ValidationRule extends RuleMessage {
     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,
@@ -406,8 +1098,13 @@ export interface ValidationRule extends RuleMessage {
  *
  * 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.
+ * 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`. */
@@ -759,6 +1456,78 @@ export declare const ValidationProfileIdentifier: import("../../global/di/types.
  * ```
  */
 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,
@@ -785,6 +1554,20 @@ export declare const VERDICT_PROPS: string[];
  * 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>;
 /**
@@ -948,6 +1731,13 @@ export declare class ValidationManager extends InteractivityExtension {
      * 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
@@ -975,30 +1765,29 @@ export declare class ValidationManager extends InteractivityExtension {
     /** 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.
+     * The profiles selectable on `element`, i.e. those of every framework it is a
+     * ROOT INSTANCE of ({@link frameworksOf}).
      *
-     * 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.
+     * 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, i.e. those with a registered
-     * rule measuring against a background carrying this element's role.
+     * 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: 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.
+     * 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.