@formicoidea/labre-core 0.37.0 → 0.38.1

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

@@ -34,7 +34,9 @@ import { ViolationTimeline } from './violation-timeline.js';
  *
  * - `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.
+ * - `audit` — collected for reporting, invisible to the drawing user, and
+ *   therefore evaluated ON DEMAND only — unless the level of requirement a
+ *   frame is on raises it ({@link ValidationMoment}).
  */
 export type ViolationSeverity = 'blocking-overridable' | 'warning' | 'audit';
 /**
@@ -89,6 +91,28 @@ export type ProfileSeverity = ViolationSeverity | 'off';
  *   drawn on it.
  */
 export type RuleFamily = 'element-in-background' | 'orientation-against-axis' | 'attachment' | 'no-overlap' | 'relative-order-along-axis' | 'relation-endpoints' | 'element-in-zone' | 'tone-convention' | 'majority-fact' | 'edge-degree' | 'role-count' | 'edge-locality' | 'reachability' | 'label-presence' | 'view-admissibility';
+/**
+ * What a verdict on one subject depends on (PF5.3). Ordered: each level
+ * includes the previous.
+ *
+ * - `element` — the subject's own props, plus the frame(s) it is attributed to.
+ *   A dirty frame already forces a full pass, so frames are free here.
+ * - `relations` — the subject, the edges touching it, and the elements at the
+ *   other end of those edges.
+ * - `frame` — every subject of the rule attributed to the same frame: the
+ *   population facts (a majority, a count, an order within a frame, "is there
+ *   another one of these on me").
+ * - `surface` — anything else. Today's behaviour for every family, and the
+ *   answer for anything unknown.
+ *
+ * Declared per FAMILY in {@link RULE_SCOPES} — the evaluator is what decides
+ * what a verdict reads, so the family owns the answer. A rule may only WIDEN
+ * it ({@link ValidationRule.scope}).
+ *
+ * Pure DATA: no evaluator reads it, and PF5.3 changes no verdict. It is the
+ * precondition of PF5.4, which will compute an incremental closure from it.
+ */
+export type RuleScope = 'element' | 'relations' | 'frame' | 'surface';
 /**
  * WHEN a rule is evaluated (PF5.14).
  *
@@ -105,6 +129,17 @@ export type RuleFamily = 'element-in-background' | 'orientation-against-axis' |
  * 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.
+ *
+ * `audit` severity implies `'on-demand'` (PF7.6) — a finding the canvas never
+ * shows has no business costing a frame. A rule may still declare `moment`
+ * explicitly, but `'realtime'` on an `audit` rule is IGNORED.
+ *
+ * The severity that decides this is the EFFECTIVE one, under the
+ * {@link ValidationProfile} in force: the framework's default level, and every
+ * level a frame on the surface has chosen ({@link momentOf}). So a board nobody
+ * raised evaluates none of its pack while the user draws, and the rules
+ * `c4.strict` shows come back on the gesture after that board is switched to it
+ * — per board, and not once for the pack.
  */
 export type ValidationMoment = 'realtime' | 'on-demand';
 /** `orientation-against-axis` configuration. */
@@ -977,8 +1012,23 @@ export interface ValidationRule extends RuleMessage {
      * `'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.
+     *
+     * A rule that is `audit` under every level in force on the surface is
+     * on-demand whatever this field says (PF7.6): declaring `'realtime'` on one
+     * is ignored, not honoured. The reverse never happens — an explicit
+     * `'on-demand'` is kept whatever a level says.
      */
     moment?: ValidationMoment;
+    /**
+     * WIDER than the family's own dependency scope, when this rule reads more
+     * than its family usually does (PF5.3).
+     *
+     * A rule — or a host shipping one — can only WIDEN {@link RULE_SCOPES}, never
+     * narrow it: the evaluator is what actually reads the surface, and a rule
+     * claiming to read less than its family does would be data that lies. Absent,
+     * the family's scope applies. See {@link scopeOf}.
+     */
+    scope?: RuleScope;
     /**
      * 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
@@ -1254,6 +1304,11 @@ export type ExemptionScope = 'element' | 'map';
  * 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.
+ *
+ * The DECLARED moment, deliberately, and not the one the levels in force decide
+ * ({@link momentOf}): this is a set of ids and not a verdict, so an audit rule
+ * whose frames it guards costs one extra id and can never make an answer wrong,
+ * where reading the levels here would mean re-reading the surface for it.
  */
 export declare function backgroundElementIds(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[]): ReadonlySet<string>;
 /**
@@ -1282,14 +1337,172 @@ export declare function toneOf(value: string | undefined): ColourTone | undefine
  * 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.
+ * Since PF5.4 the TWELVE families that are not `'surface'` honour it, and not
+ * one of them computes what it means: {@link runRules} derives the SUBJECTS
+ * each rule must judge from {@link dirtyClosure} — which reads {@link scopeOf}
+ * and nothing else — and hands them down. A family's whole part in this is one
+ * early `continue` in the loop it raises from; its indexes still span the
+ * surface, or an edge whose far end is outside the subset would look dangling
+ * and a majority would be counted over a handful.
+ *
+ * The other three never see `subjects` and are not written to look for it, on
+ * purpose: {@link evaluateNoOverlap} keeps the pair logic it has had since
+ * PF5.13, and `attachment` and `reachability` are declared `'surface'` in
+ * {@link RULE_SCOPES}, so they evaluate in full. Giving them a filter that
+ * cannot fire would read as an invitation to narrow their table entry, which is
+ * exactly the change that would make them wrong.
  */
 export interface IncrementalContext {
     dirty: ReadonlySet<string>;
     previous: readonly Violation[];
+    /**
+     * The frames each element was attributed to at the PREVIOUS pass — the one
+     * fact about a move that the current surface cannot reconstruct, since an
+     * element that has left a frame no longer says where it was.
+     *
+     * The manager's memory ({@link frameMembership}). Absent — every caller but
+     * the debounced path — the closure reads the current attribution alone, which
+     * is safe for everything except a `'frame'`-scope verdict about the frame an
+     * element has just LEFT, and that is precisely why the manager keeps it.
+     */
+    wasIn?: ReadonlyMap<string, readonly string[]>;
+    /**
+     * Filled by {@link runRules}, per rule: the subjects this evaluation must
+     * JUDGE. Absent means judge everything — a full pass for this rule, which is
+     * what a `'surface'` scope, a dirty frame and the crossover guard all resolve
+     * to.
+     *
+     * Never set by a caller: it is an answer about ONE rule, and a context is
+     * handed in for a whole pass.
+     */
+    subjects?: ReadonlySet<string>;
 }
+/**
+ * What a verdict of each family DEPENDS ON (PF5.3) — read off the evaluator
+ * beside it, one line of justification each.
+ *
+ * `Record<RuleFamily, RuleScope>`, so a family added without an entry is a
+ * BUILD error and never a silent `'surface'`. Nothing reads this table yet:
+ * PF5.4 will compute its dirty-set closure from it, and a family that changes
+ * what its evaluator reads has to change its line here on the same commit.
+ *
+ * Over-approximating is always SAFE — a wider scope re-evaluates more than it
+ * had to. Under-approximating is a stale verdict, so a family whose evidence is
+ * ambiguous is declared wider, not narrower.
+ */
+export declare const RULE_SCOPES: Record<RuleFamily, RuleScope>;
+/**
+ * The dependency scope in force for `rule`: the WIDER of its family's and its
+ * own.
+ *
+ * Widening-only by construction rather than by a test — the answer is a
+ * `Math.max` over two positions in {@link SCOPE_ORDER}, so a rule declaring a
+ * narrower scope than its family simply does not get it.
+ *
+ * An unknown family — a serialized rule shipped by a host against a build that
+ * does not have it — resolves to `'surface'`, the safe answer.
+ */
+export declare function scopeOf(rule: ValidationRule): RuleScope;
+/**
+ * The frames each element is attributed to, for the FRAME-scope rules
+ * registered — the manager's memory of a pass, handed to the next one as
+ * {@link IncrementalContext.wasIn}.
+ *
+ * The one fact the current surface cannot reconstruct: an element that has left
+ * a frame no longer says where it was, and the frame it left has one fewer
+ * subject to count. Without it a `'frame'`-scope rule has no honest incremental
+ * answer at all, which is exactly what {@link dirtyClosure} falls back to.
+ *
+ * ## Two depths, and why the shallow one is not optional
+ *
+ * The full attribution — which frame every element is on — is built for the
+ * `'frame'` scope only, since no other scope reads it. A framework like Wardley,
+ * whose rules are element, relations and surface, never pays for that walk.
+ *
+ * But every PIVOTAL element records itself under its own id — the same
+ * statement about a frame ("it is on itself"), asked at no cost beyond a role
+ * read and a prop read. Two kinds are pivotal:
+ *
+ * - a **frame** of any rule that frames against a background;
+ * - an element that **declares a level of requirement** (`validationProfile`),
+ *   because the levels in force decide the severity AND the moment of every
+ *   rule on the board, and they are INHERITED by containment
+ *   ({@link inheritChosenProfiles}) — so one of them is never a fact about one
+ *   subject.
+ *
+ * Those entries are what let {@link runRules} and {@link dirtyClosure} tell a
+ * dirty element that WAS one of the two from one that was never anything of the
+ * sort. That is the case a deletion makes unknowable, and that a role or a level
+ * changed AWAY makes invisible even while the element is still there. Without
+ * it, an incremental pass keeps verdicts measured against a map the user has
+ * just stopped calling a map, or judged at a level nobody holds any more.
+ *
+ * Real-time rules only, and the DECLARED moment, exactly like
+ * {@link backgroundElementIds} and for the same reason: an on-demand rule never
+ * takes part in an incremental pass, so it has nothing to invalidate.
+ */
+export declare function frameMembership(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[]): ReadonlyMap<string, readonly string[]>;
+/**
+ * What ONE pass has to re-judge, and what it may keep — derived from the dirty
+ * set and {@link scopeOf}, and from nothing else.
+ */
+export interface DirtyClosure {
+    /**
+     * The subjects `rule` must judge, or `null` for "judge everything" — a full
+     * pass for this rule, which is what a `'surface'` scope, a touched frame and
+     * a missing memory all resolve to.
+     */
+    subjectsOf(rule: ValidationRule): ReadonlySet<string> | null;
+    /**
+     * The previous findings of `rule` this pass keeps unchanged, given the
+     * subjects it judged. Call it ONLY with the set {@link subjectsOf} answered.
+     */
+    carried(rule: ValidationRule, subjects: ReadonlySet<string>): Violation[];
+}
+/**
+ * The closure of a change (PF5.4): for each rule, which subjects a pass must
+ * re-judge for its answer to be the one a FULL pass would give.
+ *
+ * Framework-agnostic by construction — it reads roles only through
+ * {@link backgroundsOf}, ends only through {@link rawEndpointIds}, and geometry
+ * only through `elementBound`. It never asks what anything IS.
+ *
+ * ## The three closures
+ *
+ * - `'element'` — the dirty set itself. A verdict about an element's own props
+ *   changes when those props change and at no other time.
+ * - `'relations'` — the dirty set, plus the ends of every dirty edge, plus every
+ *   edge touching one of those ends. Two hops, on purpose: a dirty edge reaches
+ *   its ends, and its ends reach their SIBLING edges — which is precisely what
+ *   the duplicate and exclusivity verdicts of `relation-endpoints` read.
+ * - `'frame'` — the dirty set, plus every frame a dirty element is or WAS
+ *   attributed to, plus everything attributed to one of those frames. The frame
+ *   ids are in the set themselves, since `role-count` and `majority-fact` raise
+ *   their findings ON the frame.
+ *
+ * ## Where it refuses to answer
+ *
+ * Each of these returns `null`, i.e. a full pass for that rule, and each is a
+ * case where a narrower answer would be a GUESS:
+ *
+ * - **a frame of the rule is dirty** — moving, resizing or deleting one
+ *   re-attributes every finding measured against it. The deletion is the case a
+ *   "is a current background dirty" test cannot see on its own, so the previous
+ *   findings are asked too, exactly as {@link evaluateNoOverlap} asks them.
+ * - **a dirty element is GONE, for a `'relations'` rule** — a removal reports an
+ *   id and nothing else, so the ends of a deleted edge cannot be recovered, and
+ *   the nodes it used to bind would keep a degree nobody counts any more.
+ * - **no `wasIn`, for a `'frame'` rule** — see {@link frameMembership}.
+ *
+ * ## Cost
+ *
+ * Lazy throughout: a board of element-scope rules alone never walks an edge,
+ * and one whose frames nothing touched never builds a membership map. The
+ * relations closure is two passes over the elements, shared by every
+ * relations-scope rule; the frame membership is one pass per frame ROLE, shared
+ * by every rule framing against it.
+ */
+export declare function dirtyClosure(elements: readonly GfxPrimitiveElementModel[], dirty: ReadonlySet<string>, previous: readonly Violation[], wasIn?: ReadonlyMap<string, readonly string[]>): DirtyClosure;
 /** 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`. */
@@ -1307,10 +1520,33 @@ export declare function hasException(element: GfxPrimitiveElementModel, ruleId:
  * 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.
+ *
+ * ## Two ways to hand one in, and two contracts
+ *
+ * - With a `previous` that IS the last verdict — the manager's debounced path —
+ *   the answer is exactly what a full pass would give, whole. That is PF5.4's
+ *   contract and the fuzz asserts it finding for finding.
+ * - With `previous: []` — a caller SEEDING the pass with its own dirty set, e.g.
+ *   the host's selection (PF7.9) — nothing is carried, so the answer is the
+ *   fresh verdicts on the closure of the seed and nothing else. For a seed `S`:
+ *   `seeded ⊆ full`, and `seeded ∩ touching(S) = full ∩ touching(S)` where
+ *   `touching(S)` is the findings naming an element or a frame of `S`. A partial
+ *   answer, never a wrong one.
  */
 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[];
+/**
+ * The registered rules a check-up runs on THIS surface — and nothing else ever
+ * evaluates.
+ *
+ * The same question {@link evaluateCheckup} answers by running them, asked
+ * without running anything: a host listing what a check-up would walk, and the
+ * manager sizing one ({@link ValidationManager.checkupRulesFor}), get exactly
+ * the set that pass will use — which means asking it the same way, against the
+ * levels the surface's own frames have CHOSEN ({@link momentOf}) and not
+ * against the registry in the abstract. Hand it no elements and the framework
+ * defaults govern, which is what an empty board is.
+ */
+export declare function checkupRules(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[], profiles?: readonly ValidationProfile[]): 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.
@@ -1326,8 +1562,30 @@ export declare function onDemandRules(rules: readonly ValidationRule[]): readonl
  * 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.
+ *
+ * ## A SEED, i.e. "audit this much of the board" (PF7.9)
+ *
+ * `seed` is a set of element ids the caller wants judged — the host's selection,
+ * typically. It reaches the same pipeline as any other incremental pass, with
+ * `previous` deliberately EMPTY: a seed is not a change to build on, it is a
+ * question about a part of the board, so nothing is carried over and the answer
+ * is exactly the fresh verdicts on the closure of the seed ({@link dirtyClosure}).
+ * `wasIn` is the CURRENT attribution, which is the honest memory here: nothing
+ * moved between the two, so where an element is and where it was are the same
+ * fact.
+ *
+ * The contract, for a seed `S` and against the same call without one:
+ *
+ * - `seeded ⊆ full` — a seeded run never invents a verdict; and
+ * - `seeded ∩ touching(S) = full ∩ touching(S)`, where `touching(S)` is the
+ *   findings naming an element or a frame of `S` — a seeded run never MISSES one
+ *   that is about the seed.
+ *
+ * Everything between the two is what the caller chose not to ask about. A seed
+ * containing a frame asks about that whole map: the frame guards in
+ * {@link dirtyClosure} send every rule measured against it through a full pass.
  */
-export declare function evaluateCheckup(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[], profiles?: readonly ValidationProfile[]): Violation[];
+export declare function evaluateCheckup(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[], profiles?: readonly ValidationProfile[], seed?: ReadonlySet<string>): Violation[];
 /**
  * One check-up, as the panel reads it: what it found, when it was asked for,
  * and how far it has got.
@@ -1359,7 +1617,15 @@ export interface CheckupRun {
     backgroundId: string;
     /** Epoch ms, taken at the moment of the gesture. */
     at: number;
-    /** The remarks so far — complete once {@link done} reaches {@link total}. */
+    /**
+     * The remarks so far — complete once {@link done} reaches {@link total}.
+     *
+     * "Complete" is about the RULES walked, not about the board: a run given a
+     * seed ({@link ValidationManager.runCheckup}) is partial by construction, and
+     * says nothing about the elements the caller did not ask about. The seed is
+     * not recorded here because the only thing that can produce one is the caller
+     * that already holds it.
+     */
     results: readonly Violation[];
     /** Rules evaluated so far. */
     done: number;
@@ -1568,6 +1834,11 @@ export declare const VERDICT_PROPS: string[];
  * 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.
+ *
+ * The DECLARED moment, like {@link backgroundElementIds} and for the same
+ * reason: this set is computed ONCE per manager, before any surface exists to
+ * read a level from, and watching a prop nothing turns out to need costs a
+ * debounced pass that finds nothing — never a wrong verdict.
  */
 export declare function verdictPropsOf(rules: readonly ValidationRule[]): ReadonlySet<string>;
 /**
@@ -1716,6 +1987,17 @@ export declare class ValidationManager extends InteractivityExtension {
      * luck of no shipped profile using `'off'` yet.
      */
     private _backgrounds;
+    /**
+     * Where every element WAS, frame by frame, at the last evaluation — the other
+     * half of the memory {@link _backgrounds} is, and for the same kind of reason.
+     *
+     * A `'frame'`-scope verdict is about a frame's whole content, so an element
+     * that has just LEFT one changes the answer there as much as it does where it
+     * landed — and the surface, which only knows where things are now, cannot say
+     * where anything was. See {@link frameMembership}: empty, and free, unless a
+     * frame-scope rule is registered.
+     */
+    private _membership;
     private _rules;
     /** Registered rules, resolved once. Empty when every framework is flagged off. */
     private get _activeRules();
@@ -1755,13 +2037,24 @@ export declare class ValidationManager extends InteractivityExtension {
     /**
      * 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.
+     * An incremental pass is the privilege of WHOEVER KNOWS WHAT CHANGED — the
+     * debounced path by default, and since PF7.9 any caller willing to say so:
+     * `true` runs the debounced path's own accumulated dirty set, an object seeds
+     * the same pipeline with the caller's, `false` (the default) pays for a full
+     * pass. Nothing about the guarantee is relaxed by opening it: a full pass is
+     * always right, and a wrong seed is still a board that lies — so a caller that
+     * is not certain hands in nothing rather than a guess.
+     *
+     * The seed may contain FRAME ids, and that is a request rather than a mistake:
+     * a frame among the dirty ids means "re-judge this board", and it lands on the
+     * {@link _backgrounds} guard below, which is exactly a full pass.
+     *
+     * A pending debounce is never lost: what it had accumulated is folded INTO the
+     * seed and its timer cleared, so one pass answers both questions.
      */
-    evaluate(incremental?: boolean): void;
+    evaluate(seed?: boolean | {
+        dirty: ReadonlySet<string>;
+    }): void;
     /** The registered rule with this id, if its framework is enabled. */
     ruleOf(ruleId: string): ValidationRule | undefined;
     /**
@@ -1801,7 +2094,10 @@ export declare class ValidationManager extends InteractivityExtension {
      * 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). */
+    /**
+     * The on-demand rules a check-up on `element` would walk (PF5.14) — under the
+     * levels the surface's frames are on right now (PF7.6).
+     */
     checkupRulesFor(element: GfxPrimitiveElementModel): readonly ValidationRule[];
     /**
      * Whether `element` has a Map quality panel to open at all: a framework of
@@ -1877,10 +2173,19 @@ export declare class ValidationManager extends InteractivityExtension {
      * remounted. So the run is finished with {@link CheckupRun.error} and whatever
      * it had managed to collect.
      *
+     * ## A SEED, i.e. "audit this much of it" (PF7.9)
+     *
+     * `seed` narrows the QUESTION, never the answer's honesty: the run judges the
+     * closure of those ids ({@link evaluateCheckup}) and carries nothing, so what
+     * comes back is `full ∩ about-the-seed` — the same verdicts a whole-board
+     * check-up would have produced there, and none of the ones it would have
+     * produced elsewhere. A host that has a selection can therefore ask about it;
+     * one that has not passes nothing and gets the whole map, as before.
+     *
      * @returns the finished run, or `null` if it was superseded or there was
      * nothing to run.
      */
-    runCheckup(element: GfxPrimitiveElementModel): Promise<CheckupRun | null>;
+    runCheckup(element: GfxPrimitiveElementModel, seed?: ReadonlySet<string>): 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