@formicoidea/labre-framework-edgy 0.31.0 → 0.33.0

package/dist/relation.d.ts

@@ -0,0 +1,142 @@
+import { ConnectorElementModel } from '@formicoidea/labre-core/model';
+import type { XYWH } from '@formicoidea/labre-core/global/gfx';
+import type { SurfaceBlockModel } from '@formicoidea/labre-core/std/gfx';
+import { type EdgyRoleId } from './roles.js';
+/**
+ * **A relation drawn by hand names itself.**
+ *
+ * Until this module the 24 typed relations of the metamodel were born of the
+ * "EDGY dynamic" template and nowhere else: a user who wanted "this Process
+ * requires that Asset" on their own board had a plain connector, carrying no
+ * role, saying nothing, read by nothing (PO recette of 26/08/2026).
+ *
+ * ## Why ONE menu entry and not twenty-two
+ *
+ * The metamodel's 24 rows are 24 DISTINCT ordered pairs of elements, so the
+ * verb is entirely determined by the pair: there is exactly one thing a link
+ * from a Journey to a Channel can say, and it is "traverses". A palette of
+ * twenty-two verbs would therefore be twenty-two ways of asking the user a
+ * question the metamodel already answers — and twenty-one ways of getting it
+ * wrong. The toolbox arms ONE tool, stamped with the generic parent role
+ * `edgy:relation`, and this resolver reads the pair the user actually attached
+ * and writes the verb.
+ *
+ * ## What it writes, and what it refuses to write
+ *
+ * - **pair in the metamodel** → the verb's role (`EDGY_VERB_ROLE`) and the verb
+ *   as the link's visible label, in the same shape the template lays one down
+ *   (`text` + `labelXYWH` + `labelOffset`). The sentence is now legal, so E1
+ *   says nothing.
+ * - **pair known only the OTHER way round** → the role of the reversed match is
+ *   written anyway, and the edge is NOT flipped. This is deliberate: silently
+ *   turning the arrow round would overrule a gesture the user made on purpose,
+ *   and leaving the edge generic would hide the mistake behind the vaguer "not
+ *   a sentence of the metamodel". Naming it makes E1 report the precise
+ *   sentence — "a channel traverses a journey" — and `docs/adr/0010`'s M3
+ *   (`edge.invert-direction`) is one click away on the contextual toolbar. The
+ *   violation IS the affordance.
+ * - **pair in neither direction** → nothing is written. The edge keeps
+ *   `edgy:relation`, and E1 reports it as a relation the metamodel does not
+ *   declare between these two elements, which is exactly what it is.
+ * - **an end outside the alphabet** — a People node, a base Object, a plain
+ *   sticky, an element of another framework — → nothing is written and nothing
+ *   is said. Same contract as the `relation-endpoints` family: outside the
+ *   alphabet is outside the conversation (PRD principle 8).
+ *
+ * ## Once, and only from the generic towards the verb
+ *
+ * A verb role already written is never rewritten — not by this module, not
+ * ever. Re-resolution is allowed only while the edge still carries the generic
+ * role, which is what makes "drop the end on the wrong element, then move it"
+ * work without the tool fighting the hand. And nothing here ever writes
+ * `edgy:relation` back over a verb: the resolution runs one way.
+ */
+/**
+ * Recompute delay. The connector tool rewrites `target` on every pointer move
+ * of the drag, so resolving on the spot would name the relation after the FIRST
+ * element the cursor passed over — and, the naming being write-once, would then
+ * refuse to name it after the one the user actually dropped it on. Debouncing
+ * means the pair that gets read is the pair that ended up on the board.
+ *
+ * Same value as the validation engine's, and for the same reason: it is the
+ * shortest wait a human does not perceive at the end of a gesture.
+ */
+export declare const EDGY_RELATION_DELAY_MS = 120;
+/** Where the verb sits along the link. The templates' own default. */
+export declare const EDGY_RELATION_LABEL_DISTANCE = 0.5;
+/**
+ * The label BOX for a verb — `x`/`y` are re-centred on the path at the first
+ * layout, but the `w`/`h` are the box, so it has to be sized to the word or the
+ * verb wraps mid-syllable on a two-word relation like "is part of".
+ *
+ * Exported and read by `templates/index.ts` as well: the 24 relations the
+ * template draws and the ones drawn by hand have to look identical, and two
+ * copies of `verb.length * 9 + 24` is one copy too many.
+ */
+export declare function edgyVerbLabelXYWH(verb: string): XYWH;
+/** What the metamodel calls the relation between two elements. */
+export interface EdgyRelationNaming {
+    /** The verb's own role: `edgy:traverses`. */
+    role: EdgyRoleId;
+    /** The verb, which also becomes the link's visible label. */
+    verb: string;
+    /**
+     * Whether the metamodel knows this pair only the OTHER way round. The edge is
+     * named all the same and never flipped — see the note at the top of the file.
+     */
+    reversed: boolean;
+}
+/**
+ * The verb the metamodel gives an ordered pair of element roles, direct match
+ * first, reversed match second, `null` when it knows neither.
+ *
+ * Pure, and exported for the unit spec: it is the whole opinion of this module,
+ * and a function taking two strings is testable without a surface, an editor or
+ * a DI container around it.
+ */
+export declare function edgyRelationNaming(sourceRole: string | undefined, targetRole: string | undefined): EdgyRelationNaming | null;
+/**
+ * Whether this edge is a generic EDGY relation with both ends ATTACHED — the
+ * one state this module acts on.
+ *
+ * `role === EDGY_ROLE.relation` exactly, never `roleIsA`: a verb role
+ * specialises the parent, and treating it as a candidate is precisely how the
+ * resolver would start rewriting its own work. An end released over empty
+ * canvas relates nothing to nothing, so it is not a candidate either — it
+ * becomes one the moment the user drags it onto something.
+ *
+ * A LOCKED edge is left alone, the guard `edge.invert-direction` applies for
+ * the same reason: locking is the user saying "do not touch this", and a
+ * resolver that wrote to one anyway would be the one gesture on this canvas
+ * that ignores it.
+ */
+export declare function isUnnamedEdgyRelation(edge: ConnectorElementModel): boolean;
+/**
+ * The naming this edge has earned from the elements it is attached to, or
+ * `null` when there is nothing to write. Reads only; the writes are below.
+ */
+export declare function edgeRelationNaming(surface: SurfaceBlockModel, edge: ConnectorElementModel): EdgyRelationNaming | null;
+/**
+ * Write the verb onto one edge.
+ *
+ * Through `surface.updateElement` and never through `EdgelessCRUDIdentifier`,
+ * for the reason `edge.invert-direction` spells out at length: `crud`'s wrapper
+ * calls `recordLastProps`, which would make this relation's label geometry the
+ * DEFAULT for every connector drawn afterwards. Naming one relation is a
+ * statement about that relation, never a style preference.
+ */
+export declare function writeEdgyRelationName(surface: SurfaceBlockModel, edge: ConnectorElementModel, naming: EdgyRelationNaming): void;
+/**
+ * Name every edge among `ids` that has earned a name, in ONE undo step.
+ *
+ * The seam, and the only function here that writes. Two phases on purpose: the
+ * namings are decided BEFORE anything is captured, so a flush that finds
+ * nothing to say costs no undo entry at all — an empty capture would turn every
+ * stray connector into a stop on the user's way back through their own history.
+ *
+ * Read-only is checked here rather than trusted: `surface.updateElement`
+ * THROWS on a read-only store, so a resolver that did not ask would turn
+ * opening a shared board in read-only into an exception per connector drawn on
+ * it.
+ */
+export declare function resolveEdgyRelations(surface: SurfaceBlockModel, ids: Iterable<string>): EdgyRelationNaming[];

package/dist/relation.js

@@ -0,0 +1,188 @@
+import { ConnectorElementModel } from '@formicoidea/labre-core/model';
+import * as Y from 'yjs';
+import { EDGY_PAIR_TO_VERB, EDGY_ROLE, EDGY_VERB_ROLE, edgyPairKey, } from './roles.js';
+/**
+ * **A relation drawn by hand names itself.**
+ *
+ * Until this module the 24 typed relations of the metamodel were born of the
+ * "EDGY dynamic" template and nowhere else: a user who wanted "this Process
+ * requires that Asset" on their own board had a plain connector, carrying no
+ * role, saying nothing, read by nothing (PO recette of 26/08/2026).
+ *
+ * ## Why ONE menu entry and not twenty-two
+ *
+ * The metamodel's 24 rows are 24 DISTINCT ordered pairs of elements, so the
+ * verb is entirely determined by the pair: there is exactly one thing a link
+ * from a Journey to a Channel can say, and it is "traverses". A palette of
+ * twenty-two verbs would therefore be twenty-two ways of asking the user a
+ * question the metamodel already answers — and twenty-one ways of getting it
+ * wrong. The toolbox arms ONE tool, stamped with the generic parent role
+ * `edgy:relation`, and this resolver reads the pair the user actually attached
+ * and writes the verb.
+ *
+ * ## What it writes, and what it refuses to write
+ *
+ * - **pair in the metamodel** → the verb's role (`EDGY_VERB_ROLE`) and the verb
+ *   as the link's visible label, in the same shape the template lays one down
+ *   (`text` + `labelXYWH` + `labelOffset`). The sentence is now legal, so E1
+ *   says nothing.
+ * - **pair known only the OTHER way round** → the role of the reversed match is
+ *   written anyway, and the edge is NOT flipped. This is deliberate: silently
+ *   turning the arrow round would overrule a gesture the user made on purpose,
+ *   and leaving the edge generic would hide the mistake behind the vaguer "not
+ *   a sentence of the metamodel". Naming it makes E1 report the precise
+ *   sentence — "a channel traverses a journey" — and `docs/adr/0010`'s M3
+ *   (`edge.invert-direction`) is one click away on the contextual toolbar. The
+ *   violation IS the affordance.
+ * - **pair in neither direction** → nothing is written. The edge keeps
+ *   `edgy:relation`, and E1 reports it as a relation the metamodel does not
+ *   declare between these two elements, which is exactly what it is.
+ * - **an end outside the alphabet** — a People node, a base Object, a plain
+ *   sticky, an element of another framework — → nothing is written and nothing
+ *   is said. Same contract as the `relation-endpoints` family: outside the
+ *   alphabet is outside the conversation (PRD principle 8).
+ *
+ * ## Once, and only from the generic towards the verb
+ *
+ * A verb role already written is never rewritten — not by this module, not
+ * ever. Re-resolution is allowed only while the edge still carries the generic
+ * role, which is what makes "drop the end on the wrong element, then move it"
+ * work without the tool fighting the hand. And nothing here ever writes
+ * `edgy:relation` back over a verb: the resolution runs one way.
+ */
+/**
+ * Recompute delay. The connector tool rewrites `target` on every pointer move
+ * of the drag, so resolving on the spot would name the relation after the FIRST
+ * element the cursor passed over — and, the naming being write-once, would then
+ * refuse to name it after the one the user actually dropped it on. Debouncing
+ * means the pair that gets read is the pair that ended up on the board.
+ *
+ * Same value as the validation engine's, and for the same reason: it is the
+ * shortest wait a human does not perceive at the end of a gesture.
+ */
+export const EDGY_RELATION_DELAY_MS = 120;
+/** Where the verb sits along the link. The templates' own default. */
+export const EDGY_RELATION_LABEL_DISTANCE = 0.5;
+/**
+ * The label BOX for a verb — `x`/`y` are re-centred on the path at the first
+ * layout, but the `w`/`h` are the box, so it has to be sized to the word or the
+ * verb wraps mid-syllable on a two-word relation like "is part of".
+ *
+ * Exported and read by `templates/index.ts` as well: the 24 relations the
+ * template draws and the ones drawn by hand have to look identical, and two
+ * copies of `verb.length * 9 + 24` is one copy too many.
+ */
+export function edgyVerbLabelXYWH(verb) {
+    return [0, 0, verb.length * 9 + 24, 26];
+}
+/**
+ * The verb the metamodel gives an ordered pair of element roles, direct match
+ * first, reversed match second, `null` when it knows neither.
+ *
+ * Pure, and exported for the unit spec: it is the whole opinion of this module,
+ * and a function taking two strings is testable without a surface, an editor or
+ * a DI container around it.
+ */
+export function edgyRelationNaming(sourceRole, targetRole) {
+    if (sourceRole === undefined || targetRole === undefined)
+        return null;
+    const direct = EDGY_PAIR_TO_VERB[edgyPairKey(sourceRole, targetRole)];
+    if (direct !== undefined) {
+        return { role: EDGY_VERB_ROLE[direct], verb: direct, reversed: false };
+    }
+    const reversed = EDGY_PAIR_TO_VERB[edgyPairKey(targetRole, sourceRole)];
+    if (reversed !== undefined) {
+        return { role: EDGY_VERB_ROLE[reversed], verb: reversed, reversed: true };
+    }
+    return null;
+}
+/**
+ * Whether this edge is a generic EDGY relation with both ends ATTACHED — the
+ * one state this module acts on.
+ *
+ * `role === EDGY_ROLE.relation` exactly, never `roleIsA`: a verb role
+ * specialises the parent, and treating it as a candidate is precisely how the
+ * resolver would start rewriting its own work. An end released over empty
+ * canvas relates nothing to nothing, so it is not a candidate either — it
+ * becomes one the moment the user drags it onto something.
+ *
+ * A LOCKED edge is left alone, the guard `edge.invert-direction` applies for
+ * the same reason: locking is the user saying "do not touch this", and a
+ * resolver that wrote to one anyway would be the one gesture on this canvas
+ * that ignores it.
+ */
+export function isUnnamedEdgyRelation(edge) {
+    return (edge.role === EDGY_ROLE.relation &&
+        Boolean(edge.source?.id) &&
+        Boolean(edge.target?.id) &&
+        !edge.isLocked());
+}
+/**
+ * The naming this edge has earned from the elements it is attached to, or
+ * `null` when there is nothing to write. Reads only; the writes are below.
+ */
+export function edgeRelationNaming(surface, edge) {
+    if (!isUnnamedEdgyRelation(edge))
+        return null;
+    const source = surface.getElementById(edge.source.id);
+    const target = surface.getElementById(edge.target.id);
+    if (!source || !target)
+        return null;
+    return edgyRelationNaming(source.role, target.role);
+}
+/**
+ * Write the verb onto one edge.
+ *
+ * Through `surface.updateElement` and never through `EdgelessCRUDIdentifier`,
+ * for the reason `edge.invert-direction` spells out at length: `crud`'s wrapper
+ * calls `recordLastProps`, which would make this relation's label geometry the
+ * DEFAULT for every connector drawn afterwards. Naming one relation is a
+ * statement about that relation, never a style preference.
+ */
+export function writeEdgyRelationName(surface, edge, naming) {
+    surface.updateElement(edge.id, {
+        role: naming.role,
+        // The verb travels with the link as a label, exactly as the template lays
+        // it down — the role is what the engine reads, the label is what the user
+        // reads out loud to notice a sentence running backwards.
+        text: new Y.Text(naming.verb),
+        labelXYWH: edgyVerbLabelXYWH(naming.verb),
+        labelOffset: { distance: EDGY_RELATION_LABEL_DISTANCE },
+    });
+}
+/**
+ * Name every edge among `ids` that has earned a name, in ONE undo step.
+ *
+ * The seam, and the only function here that writes. Two phases on purpose: the
+ * namings are decided BEFORE anything is captured, so a flush that finds
+ * nothing to say costs no undo entry at all — an empty capture would turn every
+ * stray connector into a stop on the user's way back through their own history.
+ *
+ * Read-only is checked here rather than trusted: `surface.updateElement`
+ * THROWS on a read-only store, so a resolver that did not ask would turn
+ * opening a shared board in read-only into an exception per connector drawn on
+ * it.
+ */
+export function resolveEdgyRelations(surface, ids) {
+    if (surface.store.readonly)
+        return [];
+    const planned = [];
+    for (const id of ids) {
+        const edge = surface.getElementById(id);
+        if (!(edge instanceof ConnectorElementModel))
+            continue;
+        const naming = edgeRelationNaming(surface, edge);
+        if (naming)
+            planned.push([edge, naming]);
+    }
+    if (planned.length === 0)
+        return [];
+    // BEFORE the writes: `Store.transact` is no undo boundary, so without this
+    // the naming would be undone TOGETHER with the drag that produced it and the
+    // user would lose the link they just drew to take back a word.
+    surface.store.captureSync();
+    for (const [edge, naming] of planned) {
+        writeEdgyRelationName(surface, edge, naming);
+    }
+    return planned.map(([, naming]) => naming);
+}

package/dist/roles.d.ts

@@ -0,0 +1,108 @@
+import type { EdgyNodeKind } from '@formicoidea/labre-core/model';
+import type { RoleDefs } from '@formicoidea/labre-core/std/gfx';
+import { type EdgyElementName } from './metamodel.js';
+/**
+ * EDGY role vocabulary (WS1).
+ *
+ * A role is the semantic identity of an EDGY artefact — no rule will ever look
+ * at a shape type. Three families live here, and they answer three different
+ * questions:
+ *
+ * - the ELEMENTS: `edgy:element` at the root, the four PERSISTED kinds under it
+ *   (`people`, `outcome`, `object`, `activity` — the `EdgyNodeKind` the user
+ *   picks in the toolbox and the model stores), and the twelve OFFICIAL
+ *   elements of the metamodel under their own kind;
+ * - the BACKGROUNDS: `edgy:background`, specialised by the facets diagram and
+ *   the blank board — the two frames a finding can be attributed to;
+ * - the RELATIONS: `edgy:relation`, specialised by ONE ROLE PER CANONICAL VERB.
+ *
+ * Hierarchy is DATA (`parent`), never TS inheritance: a rule written on
+ * `edgy:element` covers `edgy:purpose` for free (see `roleIsA`), which is what
+ * lets `edgy.overlapping-artefacts` be one line rather than a matrix of
+ * sixteen.
+ *
+ * ## Why a role per VERB, and not one `edgy:relation`
+ *
+ * EDGY's grammar is not "these two things may be linked", it is "content
+ * EXPRESSES purpose". A single relation role could only ever check the pair,
+ * and would happily accept a link labelled "expresses" drawn between a task and
+ * a channel — the exact mistake the metamodel exists to prevent. One role per
+ * verb makes the sentence itself the unit the engine checks, through the
+ * `relation-endpoints` family: source, edge, target, all three named by role.
+ *
+ * Tier 1 of `docs/adr/0010` applies to every one of them: the SOURCE is the
+ * subject of the verb, the TARGET its object. The verb travels with the link as
+ * a visible label too — that is presentation, and it stays; the role is what
+ * the engine reads.
+ *
+ * ## Compatibility
+ *
+ * Nothing is backfilled. An EDGY board drawn before today carries elements and
+ * connectors with no role, so it is never evaluated and never says a word — the
+ * same promise every role in this library has made (PRD principle 8).
+ */
+/** The twelve official elements of the metamodel, by name. */
+export type EdgyElementRole = EdgyElementName;
+/** The static half of the vocabulary — everything not derived from a verb. */
+export type EdgyStaticRole = 'element' | EdgyNodeKind | 'background' | 'facets' | 'board' | 'relation' | EdgyElementRole;
+export type EdgyRoleId = `edgy:${string}`;
+/** Role ids, keyed by the name used at the creation sites. */
+export declare const EDGY_ROLE: {
+    readonly element: "edgy:element";
+    readonly people: "edgy:people";
+    readonly outcome: "edgy:outcome";
+    readonly object: "edgy:object";
+    readonly activity: "edgy:activity";
+    readonly purpose: "edgy:purpose";
+    readonly capability: "edgy:capability";
+    readonly task: "edgy:task";
+    readonly story: "edgy:story";
+    readonly process: "edgy:process";
+    readonly journey: "edgy:journey";
+    readonly content: "edgy:content";
+    readonly asset: "edgy:asset";
+    readonly channel: "edgy:channel";
+    readonly organisation: "edgy:organisation";
+    readonly product: "edgy:product";
+    readonly brand: "edgy:brand";
+    readonly background: "edgy:background";
+    readonly facets: "edgy:facets";
+    readonly board: "edgy:board";
+    readonly relation: "edgy:relation";
+};
+/**
+ * Role id per canonical verb, DERIVED from {@link EDGY_DYNAMIC_RELATIONS}.
+ *
+ * Derived rather than restated: the metamodel is written once (`./metamodel.ts`)
+ * and the template that draws it, the vocabulary that names it and the rule that
+ * checks it all read the same table. `requires` appears on three rows and gets
+ * ONE role — a verb is a verb wherever it is spoken, and the three sentences it
+ * belongs to are three triplets, not three roles.
+ */
+export declare const EDGY_VERB_ROLE: Readonly<Record<string, EdgyRoleId>>;
+/**
+ * Key of an ORDERED pair of element roles: `edgy:process edgy:capability`.
+ *
+ * A SPACE separates them, and not `-`, `:` or `>`: a role id already contains a
+ * colon and may contain a dash (`edgy:is-part-of`), and a separator that can
+ * occur inside a value is a lookup table with collisions waiting in it. No role
+ * id has ever contained whitespace — `verbRoleId` above replaces it on the one
+ * family that could.
+ */
+export declare const edgyPairKey: (source: string, target: string) => string;
+/**
+ * Ordered pair of ELEMENT roles → the canonical verb the metamodel gives it,
+ * DERIVED from {@link EDGY_DYNAMIC_RELATIONS}.
+ *
+ * The metamodel's 24 rows are 24 DISTINCT ordered pairs, so the verb of a
+ * relation is entirely determined by which two elements it runs between: there
+ * is never a choice to offer. That is what lets the toolbox ship ONE "Relation"
+ * entry instead of twenty-two, and what `./relation.ts` reads to name a
+ * hand-drawn link after the pair the user attached it to.
+ *
+ * Derived, never restated — same contract as {@link EDGY_VERB_ROLE}: a relation
+ * added to `./metamodel.ts` becomes nameable by hand without anybody editing
+ * this file.
+ */
+export declare const EDGY_PAIR_TO_VERB: Readonly<Record<string, string>>;
+export declare const EDGY_ROLES: RoleDefs;

package/dist/roles.js

@@ -0,0 +1,182 @@
+import { EDGY_DYNAMIC_NODES, EDGY_DYNAMIC_RELATIONS, edgyElementLabel, } from './metamodel.js';
+import { NODE_LABEL } from './node/consts.js';
+/** Role ids, keyed by the name used at the creation sites. */
+export const EDGY_ROLE = {
+    element: 'edgy:element',
+    // The four persisted kinds (`EdgyNodeKind`).
+    people: 'edgy:people',
+    outcome: 'edgy:outcome',
+    object: 'edgy:object',
+    activity: 'edgy:activity',
+    // The twelve official elements.
+    purpose: 'edgy:purpose',
+    capability: 'edgy:capability',
+    task: 'edgy:task',
+    story: 'edgy:story',
+    process: 'edgy:process',
+    journey: 'edgy:journey',
+    content: 'edgy:content',
+    asset: 'edgy:asset',
+    channel: 'edgy:channel',
+    organisation: 'edgy:organisation',
+    product: 'edgy:product',
+    brand: 'edgy:brand',
+    // The two frames.
+    background: 'edgy:background',
+    facets: 'edgy:facets',
+    board: 'edgy:board',
+    // The parent of the 22 verbs.
+    relation: 'edgy:relation',
+};
+/**
+ * A canonical verb, as a role id: `is part of` → `edgy:is-part-of`.
+ *
+ * The verb IS the identifier, so a relation added to the metamodel gets its
+ * role for free and nobody has to remember to name it. No collision with the
+ * element roles above is possible in the metamodel as it stands, and a future
+ * verb colliding with an element name would be caught by the unit spec, which
+ * counts the vocabulary.
+ */
+function verbRoleId(verb) {
+    return `edgy:${verb.replace(/\s+/g, '-')}`;
+}
+/**
+ * Role id per canonical verb, DERIVED from {@link EDGY_DYNAMIC_RELATIONS}.
+ *
+ * Derived rather than restated: the metamodel is written once (`./metamodel.ts`)
+ * and the template that draws it, the vocabulary that names it and the rule that
+ * checks it all read the same table. `requires` appears on three rows and gets
+ * ONE role — a verb is a verb wherever it is spoken, and the three sentences it
+ * belongs to are three triplets, not three roles.
+ */
+export const EDGY_VERB_ROLE = Object.assign(Object.create(null), Object.fromEntries(EDGY_DYNAMIC_RELATIONS.map(([, , verb]) => [verb, verbRoleId(verb)])));
+/**
+ * Key of an ORDERED pair of element roles: `edgy:process edgy:capability`.
+ *
+ * A SPACE separates them, and not `-`, `:` or `>`: a role id already contains a
+ * colon and may contain a dash (`edgy:is-part-of`), and a separator that can
+ * occur inside a value is a lookup table with collisions waiting in it. No role
+ * id has ever contained whitespace — `verbRoleId` above replaces it on the one
+ * family that could.
+ */
+export const edgyPairKey = (source, target) => `${source} ${target}`;
+/**
+ * Ordered pair of ELEMENT roles → the canonical verb the metamodel gives it,
+ * DERIVED from {@link EDGY_DYNAMIC_RELATIONS}.
+ *
+ * The metamodel's 24 rows are 24 DISTINCT ordered pairs, so the verb of a
+ * relation is entirely determined by which two elements it runs between: there
+ * is never a choice to offer. That is what lets the toolbox ship ONE "Relation"
+ * entry instead of twenty-two, and what `./relation.ts` reads to name a
+ * hand-drawn link after the pair the user attached it to.
+ *
+ * Derived, never restated — same contract as {@link EDGY_VERB_ROLE}: a relation
+ * added to `./metamodel.ts` becomes nameable by hand without anybody editing
+ * this file.
+ */
+export const EDGY_PAIR_TO_VERB = Object.assign(Object.create(null), Object.fromEntries(EDGY_DYNAMIC_RELATIONS.map(([source, target, verb]) => [
+    edgyPairKey(EDGY_ROLE[source], EDGY_ROLE[target]),
+    verb,
+])));
+/** i18n key stem of a role id: `edgy:is-part-of` → `com.labre.edgy.role.is-part-of`. */
+const roleKey = (id) => `com.labre.edgy.role.${id.slice('edgy:'.length)}`;
+const ELEMENT_DEFS = [
+    // The root of every artefact a board is made of. A rule written here covers
+    // the four kinds and the twelve elements at once — which is exactly what
+    // `edgy.overlapping-artefacts` needs and why the root exists.
+    {
+        id: EDGY_ROLE.element,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE.element),
+        labelFallback: 'Element',
+    },
+    // The four PERSISTED kinds. They are the base shapes the toolbox offers, so
+    // they are what an element created from the palette carries: somebody
+    // dropping an "Object" on the board has said "object" and nothing more, and
+    // the role says exactly that much.
+    //
+    // The fallback is the wording the palette itself writes inside the shape
+    // (`node/consts.ts`), so a reader who meets the role in a legend or a
+    // direction reveal meets the word they dropped on the board.
+    ...['people', 'outcome', 'object', 'activity'].map(kind => ({
+        id: EDGY_ROLE[kind],
+        parent: EDGY_ROLE.element,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE[kind]),
+        labelFallback: NODE_LABEL[kind],
+    })),
+    // The twelve official elements, each under the kind the metamodel draws it
+    // with — Purpose is an outcome, Story an activity, Channel an object. The
+    // parent is READ from `EDGY_DYNAMIC_NODES` rather than restated: the diagram
+    // and the vocabulary cannot drift apart if there is only one table. So is the
+    // fallback wording, from the same table's own names.
+    ...Object.entries(EDGY_DYNAMIC_NODES).map(([name, { kind }]) => ({
+        id: EDGY_ROLE[name],
+        parent: EDGY_ROLE[kind],
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE[name]),
+        labelFallback: edgyElementLabel(name),
+    })),
+];
+const BACKGROUND_DEFS = [
+    // The frame, and deliberately NOT a child of `edgy:element`: a rule written
+    // on the artefacts must never match the board they are drawn on. Two frames
+    // specialise it — the facets diagram and the blank board — so a rule
+    // attributes its findings to whichever one the user is working on without
+    // naming either.
+    {
+        id: EDGY_ROLE.background,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE.background),
+    },
+    {
+        id: EDGY_ROLE.facets,
+        parent: EDGY_ROLE.background,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE.facets),
+    },
+    {
+        id: EDGY_ROLE.board,
+        parent: EDGY_ROLE.background,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE.board),
+    },
+];
+/**
+ * The relations: the parent, then one child per canonical verb.
+ *
+ * The parent carries no `direction` — it names no verb, so it has no sentence
+ * to state. Every child does, and the gesture hint is derived from the verb for
+ * the same reason the id is: "drag from the X to the Y" is the same sentence
+ * with the same two holes for all 22 of them, and writing it out 22 times would
+ * be 22 chances to write it out wrong.
+ */
+const RELATION_DEFS = [
+    {
+        id: EDGY_ROLE.relation,
+        kind: 'edge',
+        labelKey: roleKey(EDGY_ROLE.relation),
+        labelFallback: 'Relation',
+    },
+    ...Object.entries(EDGY_VERB_ROLE).map(([verb, id]) => ({
+        id,
+        parent: EDGY_ROLE.relation,
+        kind: 'edge',
+        labelKey: roleKey(id),
+        labelFallback: verb.charAt(0).toUpperCase() + verb.slice(1),
+        direction: {
+            verbKey: `${roleKey(id)}.verb`,
+            verbFallback: verb,
+            gestureHintKey: `${roleKey(id)}.gesture`,
+            gestureHintFallback: `Drag from the element that is the subject of "${verb}" to its object.`,
+        },
+    })),
+];
+const DEFS = [
+    ...ELEMENT_DEFS,
+    ...BACKGROUND_DEFS,
+    ...RELATION_DEFS,
+];
+// Null prototype: this is a lookup table keyed by ids that may one day come
+// from host-supplied packs, so `defs['toString']` must not resolve.
+export const EDGY_ROLES = Object.assign(Object.create(null), Object.fromEntries(DEFS.map(def => [def.id, def])));

package/dist/rules.d.ts

@@ -0,0 +1,43 @@
+import type { EndpointTriplet, ValidationRule } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * EDGY validation rules (WS1).
+ *
+ * DATA owned by the framework, versioned per rule: the engine
+ * (`@labre/affine-block-surface`) knows how to evaluate a FAMILY, never a
+ * concrete rule. Adding an EDGY rule is adding an entry to this array.
+ *
+ * Registered from the flag-gated `EdgyViewExtension`, so switching the EDGY
+ * flag off removes the rules with the rest of the tooling — boards already
+ * drawn keep rendering, they simply stop being checked (`docs/adr/0009`).
+ *
+ * ## Two rules, and the ones deliberately left out
+ *
+ * The PO arbitration of 26/08/2026 put EDGY's two JUDGEMENT controls — "every
+ * intersection element is linked to both its parent facets" and "every element
+ * wears its facet's colour" — in `./nudges.ts` rather than here. Neither is
+ * decidable: the first would have to guess which circle an element belongs to
+ * from where somebody dropped it, and the second would indict a board whose
+ * author uses their own palette. A checklist can ask them; an algorithm cannot
+ * answer them.
+ *
+ * ## Debt: `tree-mixed-kinds`
+ *
+ * EDGY's own notation has TREES — a capability tree, an organisation tree —
+ * whose levels must all be the same kind of element. There is no tree on this
+ * canvas yet: nothing draws one, nothing stores one, and no role names one. The
+ * rule is therefore deferred rather than written against an artefact that does
+ * not exist. When a tree lands, it comes with its own role and this is where its
+ * rule goes.
+ */
+/**
+ * The 24 sanctioned sentences, DERIVED from the metamodel.
+ *
+ * One triplet per row of `EDGY_DYNAMIC_RELATIONS`, read exactly as
+ * `docs/adr/0010` reads a typed edge: source is the subject, target the object.
+ * The matrix is never restated — a relation added to the metamodel is drawn by
+ * the template, gets a role from `roles.ts` and becomes legal here, all from the
+ * one table. `requires` contributes three triplets under one role, which is what
+ * it means for a verb to be spoken of three different pairs.
+ */
+export declare const EDGY_ALLOWED_RELATIONS: readonly EndpointTriplet[];
+export declare const EDGY_RULES: readonly ValidationRule[];