@formicoidea/labre-framework-wardley 0.31.0 → 0.33.0

package/dist/reading.d.ts

@@ -0,0 +1,3 @@
+import type { ReadingNamingConvention, ReadingProfile } from '@formicoidea/labre-core/blocks/surface';
+export declare const WARDLEY_NAMING_CONVENTIONS: readonly ReadingNamingConvention[];
+export declare const WARDLEY_READING: ReadingProfile;

package/dist/reading.js

@@ -0,0 +1,129 @@
+import { WARDLEY_BACKGROUND } from './background.js';
+import { WARDLEY_NATURE, WARDLEY_NATURE_TAG_ID } from './natures.js';
+import { WARDLEY_ROLE, WARDLEY_ROLES } from './roles.js';
+/**
+ * What Wardley lets the tool read of a component (MF3, the reversed reading).
+ *
+ * DATA, like the rules and the profiles beside it: the engine
+ * (`@labre/affine-block-surface`) knows how to read a role, a tag, a typed edge
+ * and a declared background — it knows nothing about Wardley. Everything below
+ * is already stated somewhere else in this framework and is merely POINTED AT
+ * here: the role vocabulary (`roles.ts`), the nature tag (`natures.ts`), the
+ * dependency edge (ADR 0010 § 2 tier 2) and the map's own zones
+ * (`background.ts`).
+ *
+ * Registered from the FLAG-GATED view extension: reading a map is tooling, so a
+ * board whose Wardley flag is off keeps every element it has and simply stops
+ * being read (ADR 0009).
+ */
+/**
+ * ## The naming convention, and why it is one motif rather than a grammar
+ *
+ * Wardley's four natures answer "what KIND of thing is this?", and two of the
+ * four answers are visible in the NAME long before anyone opens a picker: an
+ * activity is something that is DONE, and the other three are things that
+ * ARE — something recorded, a way of doing, something known.
+ *
+ * So the convention retained is exactly one motif — **does the name read as an
+ * action?** — expressed as the English gerund (`…ing`), applied POSITIVELY to
+ * `activity` and NEGATIVELY to the three others:
+ *
+ * | nature    | expected                          | example              |
+ * | --------- | --------------------------------- | -------------------- |
+ * | activity  | reads as an action                | "Brewing tea"        |
+ * | data      | does NOT read as an action        | "Customer register"  |
+ * | practice  | does NOT read as an action        | "Agile method"       |
+ * | knowledge | does NOT read as an action        | "Thermodynamics"     |
+ *
+ * One motif, four entries, no word list. A vocabulary of "practice-ish nouns"
+ * would be a dictionary the library would then own, in one language, and would
+ * be wrong for the first client who names things in their own — whereas the
+ * gerund is a single, checkable shape a user can predict from the sentence they
+ * are shown.
+ *
+ * ## The motif is ENGLISH, and it says so
+ *
+ * `\p{L}+ing` is a fact about English, so every entry below declares
+ * `lang: 'en'` and the engine keeps quiet unless the host says it is serving
+ * English. That is not a detail: on a board named in French the same motif is
+ * wrong in BOTH directions — "Facturation" on an activity would be told to use
+ * a verb, and "Planning", "Sourcing" or "Reporting" on data would be told they
+ * read as actions. An out-of-scope suggestion is worse than none, because it is
+ * confident.
+ *
+ * Extending the coverage is adding entries, not changing code: one more
+ * convention per `valueId` with its own `lang` and its own motif (French, say,
+ * would key on the `-tion`/`-ment` nominalisations against an infinitive), and
+ * the first one in scope wins. A host that declares no language gets silence,
+ * which is the honest answer to "I do not know what language these words are
+ * in".
+ *
+ * It is a SUGGESTION and never a verdict: it produces no violation, blocks no
+ * gesture, and the panel prints the wording below rather than a red mark. A
+ * component named "Tea" whose nature is `activity` is very often correct — the
+ * architect writing shorthand — and the reading's job is to ask, not to insist.
+ *
+ * The wording travels as an i18n key with an English fallback, like every other
+ * declaration in this framework: the host localises it, and a host with no
+ * catalogue still reads a real sentence.
+ */
+const ACTION_MOTIF = String.raw `\b\p{L}+ing\b`;
+const naming = (valueId, expectsAction, key, fallback) => ({
+    valueId,
+    // The gerund is a fact about English: out of that scope the engine says
+    // nothing rather than something confident and wrong.
+    lang: 'en',
+    // The negative form is the same motif under a lookahead, so the two can never
+    // drift apart: change what "reads as an action" means and both sides move.
+    // `[\s\S]` rather than `.` because a canvas label wraps, and a name on two
+    // lines must be judged on what it says, not on where it broke.
+    pattern: expectsAction
+        ? ACTION_MOTIF
+        : `^(?![\\s\\S]*${ACTION_MOTIF})[\\s\\S]+$`,
+    hintKey: key,
+    hintFallback: fallback,
+});
+export const WARDLEY_NAMING_CONVENTIONS = [
+    naming(WARDLEY_NATURE.activity, true, 'com.labre.wardley.reading.naming.activity', 'An activity is something that is done — name it with a verb ("Brewing tea"), not with a thing.'),
+    naming(WARDLEY_NATURE.data, false, 'com.labre.wardley.reading.naming.data', 'Data is something recorded — name it as a thing ("Customer register"), not as an action.'),
+    naming(WARDLEY_NATURE.practice, false, 'com.labre.wardley.reading.naming.practice', 'A practice is a way of doing — name the practice ("Agile method"), not the doing.'),
+    naming(WARDLEY_NATURE.knowledge, false, 'com.labre.wardley.reading.naming.knowledge', 'Knowledge is something known — name what is known ("Thermodynamics"), not an activity.'),
+];
+export const WARDLEY_READING = {
+    id: 'wardley',
+    framework: 'wardley',
+    roles: WARDLEY_ROLES,
+    // The subject is a component. `market` and `ecosystem` specialise it and are
+    // read for free through `roleIsA` — that is the entire reason role hierarchy
+    // is data. The `anchor` (a user / need) is deliberately NOT a child of
+    // `component` and is deliberately not read: a need has no nature and no
+    // phase, it has a demand.
+    appliesTo: WARDLEY_ROLE.component,
+    // On this canvas a name IS a separate free text element grouped with the
+    // node — the same fact W3 measures overlaps against.
+    labelRole: WARDLEY_ROLE.label,
+    nature: {
+        tagId: WARDLEY_NATURE_TAG_ID,
+        conventions: WARDLEY_NAMING_CONVENTIONS,
+    },
+    // The value-chain link. ADR 0010 § 2: `source` is the subject of the role's
+    // verb, and this role's verb is "depends on" — so the source is the consumer
+    // and the target is what it needs.
+    relation: { edgeRole: WARDLEY_ROLE.dependency },
+    frame: {
+        backgroundRole: WARDLEY_ROLE.map,
+        background: WARDLEY_BACKGROUND,
+        // Evolution runs along the plot's x axis; its four zones ARE the phases.
+        axis: 'x',
+    },
+    /**
+     * The two record properties a reading may compare itself against.
+     *
+     * Host keys, and plain ones on purpose: the library does not name a property
+     * of somebody else's document, it states which two it would read IF the host
+     * ships them (and lists them in `hoverFields`). A host whose record spells
+     * them differently gets no comparison and no drift — silence, which is the
+     * correct answer to "I cannot see the record's nature".
+     */
+    recordKeys: { nature: 'nature', phase: 'phase' },
+};

package/dist/roles.d.ts

@@ -0,0 +1,50 @@
+import type { WardleyNodeKind } from '@formicoidea/labre-core/model';
+import type { RoleDefs } from '@formicoidea/labre-core/std/gfx';
+/**
+ * Wardley role vocabulary (PF13.1).
+ *
+ * Roles are the semantic identity of a Wardley artefact — no rule will ever
+ * look at a shape type. They mirror {@link WardleyNodeKind}, which the user
+ * already picks when choosing the artefact in the toolbox, plus the typed
+ * `dependency` EDGE carried by the Wardley link connector.
+ *
+ * Hierarchy is DATA (`parent`), never TS inheritance: `market` and `ecosystem`
+ * specialise `component`, so a rule written on `wardley:component` applies to
+ * them for free (see `roleIsA`). The `anchor` (user / need) is a role of its
+ * own — a component with no need of its own — and is deliberately NOT a child
+ * of `component`.
+ */
+/**
+ * ## Revision of decision #71 (PF13.4, 01/08/2026)
+ *
+ * PF1 left three artefacts NEUTRAL — the evolution arrow ("a movement
+ * annotation, not a dependency"), the inertia bar and the node labels — on the
+ * ground that nothing was written on them yet. That was right while the only
+ * rule was the pilot; it is wrong now that the framework has rules about them:
+ * an element with no role is never evaluated (proportionality, PRD principle
+ * 8), so leaving these neutral would have meant W1, W2 and W3 could not exist.
+ *
+ * The reversal writes new VALUES into the existing `role` field. No schema
+ * change, no migration, and no backfill of documents already drawn: a map
+ * authored before today carries arrows and bars with no role, so it raises
+ * nothing — which is the same promise every earlier role made.
+ */
+/** Every role this framework declares. */
+export type WardleyRole = WardleyNodeKind | 'dependency' | 'map' | 'change-arrow' | 'inertia' | 'label';
+export type WardleyRoleId = `wardley:${WardleyRole}`;
+/** Role ids, keyed by the `kind` used at the creation sites. */
+export declare const WARDLEY_ROLE: {
+    readonly component: "wardley:component";
+    readonly anchor: "wardley:anchor";
+    readonly pipeline: "wardley:pipeline";
+    readonly handle: "wardley:handle";
+    readonly market: "wardley:market";
+    readonly ecosystem: "wardley:ecosystem";
+    readonly method: "wardley:method";
+    readonly dependency: "wardley:dependency";
+    readonly map: "wardley:map";
+    readonly changeArrow: "wardley:change-arrow";
+    readonly inertia: "wardley:inertia";
+    readonly label: "wardley:label";
+};
+export declare const WARDLEY_ROLES: RoleDefs;

package/dist/roles.js

@@ -0,0 +1,132 @@
+/** Role ids, keyed by the `kind` used at the creation sites. */
+export const WARDLEY_ROLE = {
+    component: 'wardley:component',
+    anchor: 'wardley:anchor',
+    pipeline: 'wardley:pipeline',
+    handle: 'wardley:handle',
+    market: 'wardley:market',
+    ecosystem: 'wardley:ecosystem',
+    method: 'wardley:method',
+    dependency: 'wardley:dependency',
+    map: 'wardley:map',
+    changeArrow: 'wardley:change-arrow',
+    inertia: 'wardley:inertia',
+    label: 'wardley:label',
+};
+const DEFS = [
+    {
+        id: WARDLEY_ROLE.component,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.component',
+    },
+    // A user / need: a component with no need of its own, hence its own role
+    // rather than a specialisation of `component`.
+    {
+        id: WARDLEY_ROLE.anchor,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.anchor',
+    },
+    // The pipeline body. Connections go through its handle, never the body.
+    {
+        id: WARDLEY_ROLE.pipeline,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.pipeline',
+    },
+    {
+        id: WARDLEY_ROLE.handle,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.handle',
+    },
+    {
+        id: WARDLEY_ROLE.market,
+        parent: WARDLEY_ROLE.component,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.market',
+    },
+    {
+        id: WARDLEY_ROLE.ecosystem,
+        parent: WARDLEY_ROLE.component,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.ecosystem',
+    },
+    {
+        id: WARDLEY_ROLE.method,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.method',
+    },
+    /**
+     * The value-chain link: "A depends on B".
+     *
+     * The comment above was the whole of the convention until `docs/adr/0010`
+     * made it DATA. Tier 1 of that ADR is generic — `source` is the subject of
+     * the role's verb, `target` its object — and tier 2 is this `direction`
+     * block: the verb of THIS role is "depends on", so its source is the
+     * consumer and its target is what the consumer needs. Needs descend from
+     * source to target; value flows back up. W4 evaluates exactly that reading,
+     * and the tool hint below is what makes it a statement the user made rather
+     * than a by-product of which end their finger landed on first.
+     */
+    {
+        id: WARDLEY_ROLE.dependency,
+        kind: 'edge',
+        labelKey: 'com.labre.wardley.role.dependency',
+        labelFallback: 'Dependency',
+        direction: {
+            verbKey: 'com.labre.wardley.role.dependency.verb',
+            verbFallback: 'depends on',
+            gestureHintKey: 'com.labre.wardley.role.dependency.gesture',
+            gestureHintFallback: 'Drag from the component that has the need to what it needs.',
+        },
+    },
+    // The map itself: the axes frame the other roles are positioned against.
+    // A frame, not a component, so it specialises nothing — a rule written on
+    // `wardley:component` must never match the map it measures against.
+    {
+        id: WARDLEY_ROLE.map,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.map',
+    },
+    // The change (evolution) arrow: "this is where it is going". An EDGE, and
+    // deliberately not a specialisation of `dependency` — it says nothing about
+    // what depends on what, and W1 must not fall on a value-chain link.
+    {
+        id: WARDLEY_ROLE.changeArrow,
+        kind: 'edge',
+        labelKey: 'com.labre.wardley.role.change-arrow',
+        labelFallback: 'Evolution arrow',
+        // Tier 1 applies to every edge role, so this one states its own verb — and
+        // it is NOT "depends on". An arrow says where a component is going: source
+        // is where it stands today, target where it is heading. W4 reads the
+        // dependency's verb and never this one.
+        direction: {
+            verbKey: 'com.labre.wardley.role.change-arrow.verb',
+            verbFallback: 'is evolving towards',
+            gestureHintKey: 'com.labre.wardley.role.change-arrow.gesture',
+            gestureHintFallback: 'Drag from where the component stands today to where it is heading.',
+        },
+    },
+    // The inertia bar: resistance to a movement, drawn ASTRIDE the phase divider
+    // the thing refuses to cross (W2). A plain filled rect on the canvas, which
+    // is exactly why it needs a role — nothing about its shape says what it
+    // means.
+    {
+        id: WARDLEY_ROLE.inertia,
+        kind: 'node',
+        labelKey: 'com.labre.wardley.role.inertia',
+    },
+    // The name written next to an artefact. A role of its own rather than a
+    // property of the node it labels: on this canvas a label IS a separate free
+    // text element, grouped with its node, and W3 is about where it lands.
+    //
+    // `text`, not `node`: a label is created 120 to 200 units wide whatever it
+    // reads, so its BOX is not a statement about anything the eye can see. The
+    // kind is what tells a rule to measure the words instead.
+    {
+        id: WARDLEY_ROLE.label,
+        kind: 'text',
+        labelKey: 'com.labre.wardley.role.label',
+    },
+];
+// 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 WARDLEY_ROLES = Object.assign(Object.create(null), Object.fromEntries(DEFS.map(def => [def.id, def])));

package/dist/rules.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationRule } from '@formicoidea/labre-core/blocks/surface';
+export declare const WARDLEY_RULES: readonly ValidationRule[];

package/dist/rules.js

@@ -0,0 +1,286 @@
+import { WARDLEY_BACKGROUND } from './background.js';
+import { WARDLEY_ROLE, WARDLEY_ROLES } from './roles.js';
+/**
+ * Wardley validation rules (PF13.4 / PF13.5 / PF13.6).
+ *
+ * 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 a Wardley rule is adding an entry to this array.
+ *
+ * Registered from the flag-gated `WardleyViewExtension`, so switching the
+ * Wardley flag off removes the rules with the rest of the tooling — already
+ * drawn maps keep rendering, they simply stop being checked (see
+ * `docs/adr/0009`).
+ *
+ * ## The pilot rule is gone
+ *
+ * `wardley.component-outside-map` was the tracer bullet's rule: it existed to
+ * prove the engine, the affordance, the exceptions and the profiles could work
+ * end to end, never because a Wardley practitioner asked for it. Parking a node
+ * in the margin while you think is normal work, and PO decision of 01/08/2026
+ * removed it the moment there were real rules for the machinery to carry.
+ * Nothing was left behind: every test that exercised the pipework through it
+ * now exercises it through W1, W2 or W3.
+ *
+ * ## Severity, and a hole that is named rather than papered over
+ *
+ * W1 and W2 are the two the architect would put at `blocking-overridable`. They
+ * are declared `warning`, because NOTHING downstream implements a blocking
+ * level: no gesture is refused anywhere in this library, so shipping the value
+ * would be data claiming an effect that does not exist. The severity moves to
+ * `blocking-overridable` in the profiles, in one line each, the day the gesture
+ * refusal lands. Building it was explicitly out of this slice.
+ */
+/**
+ * **W1** — a change arrow may not point against the sense of evolution.
+ *
+ * The whole grammar of a Wardley map is that things move left to right: a red
+ * arrow pointing back towards Genesis says the opposite of what the map means.
+ * Written on `wardley:change-arrow`, the role PF13.4 puts on the arrow at
+ * creation — value-chain links are a different role and are never touched.
+ *
+ * The 30° dead zone is deliberate. An arrow drawn straight up a value chain is
+ * neither with evolution nor against it, and one drawn slightly up-and-back is
+ * a hand that slipped, not a claim about the world. Only an arrow genuinely
+ * heading back — more than 120° off the axis' forward sense — is one.
+ */
+const changeArrowAgainstEvolution = {
+    id: 'wardley.change-arrow-against-evolution',
+    framework: 'wardley',
+    family: 'orientation-against-axis',
+    severity: 'warning',
+    appliesTo: WARDLEY_ROLE.changeArrow,
+    roles: WARDLEY_ROLES,
+    messageKey: 'com.labre.wardley.validation.change-arrow-against-evolution',
+    messageFallback: 'This change arrow points against evolution.',
+    suggestionKey: 'com.labre.wardley.validation.change-arrow-against-evolution.suggestion',
+    suggestionFallback: 'Evolution runs left to right — turn the arrow towards the commodity end, or draw a dependency instead.',
+    version: 1,
+    provenance: {
+        source: 'recommendation',
+        reference: 'Wardley mapping — the evolution axis runs left to right, and a component moves with it',
+    },
+    backgroundRole: WARDLEY_ROLE.map,
+    // The frame's own declaration, carried as data exactly like `roles` is: it is
+    // where "which way does evolution run" is written, and the engine reads it
+    // rather than knowing anything about Wardley.
+    background: WARDLEY_BACKGROUND,
+    against: { axis: 'evolution', toleranceDeg: 30 },
+};
+/**
+ * **W2** — the inertia bar straddles a phase transition.
+ *
+ * > "The horizontal position of an inertia bar is only valid if it is ASTRIDE
+ * > two evolution phases, that is, superimposed on a dashed vertical axis."
+ * > — the PO, spelling the rule out on the recette of 02/08/2026
+ *
+ * Inertia is resistance to crossing a frontier. The bar is the frontier being
+ * refused, so it is drawn ON the divider; a bar parked in the middle of a phase
+ * marks nothing at all and becomes a black rectangle.
+ *
+ * ## What this rule used to ask, and no longer does
+ *
+ * Until this version it ALSO demanded a dependency under the bar, and reported
+ * that half first ("This inertia bar is not drawn on a dependency."). That was
+ * our reading of inertia, not the PO's rule, and it was wrong in both
+ * directions: a bar alone on a divider — a perfectly ordinary way to say "this
+ * whole column is stuck" — was flagged, while nothing in the sentence pointed at
+ * the position that actually decides the verdict. The carrier condition is gone
+ * entirely, with the second message that existed only to tell the two halves
+ * apart. One condition, one sentence.
+ *
+ * ## "Astride", as geometry
+ *
+ * The engine takes the bar's own horizontal EXTENT and asks whether it
+ * intersects the transition band — the divider widened by the map's declared
+ * `transitionBandWidth` (see {@link AttachmentDef.boundaryAxis}). That single
+ * overlap test says both halves of "superimposed on the axis": a bar wide enough
+ * to cover the divider genuinely has the line running through it, and a bar too
+ * thin to cover anything (the toolbox draws it eight units wide) is accepted
+ * inside the band the map itself declares around the frontier — Wardley's zone
+ * of punctuated equilibrium, where inertia lives.
+ *
+ * Measured on the extent rather than on the centre because "superimposed on the
+ * line" is a statement about ink; measured against a band declared as a RATIO of
+ * the plot because the same gesture must get the same verdict on a map somebody
+ * resized (the lesson of the 01/08/2026 recette).
+ */
+const inertiaOffTransition = {
+    id: 'wardley.inertia-off-transition',
+    framework: 'wardley',
+    family: 'attachment',
+    severity: 'warning',
+    appliesTo: WARDLEY_ROLE.inertia,
+    roles: WARDLEY_ROLES,
+    // ONE sentence, because there is now one condition. The key is the rule's own
+    // id: the two keys it replaces named halves of a rule that no longer has any.
+    messageKey: 'com.labre.wardley.validation.inertia-off-transition',
+    messageFallback: 'This inertia bar sits inside a phase, not astride a phase transition.',
+    suggestionKey: 'com.labre.wardley.validation.inertia-off-transition.suggestion',
+    suggestionFallback: 'Inertia bites at a frontier — slide the bar sideways until it sits astride the dashed line between two evolution phases.',
+    // 3: the carrier condition is gone and the position is judged on the bar's
+    // extent — a different verdict on the same map, so a new version.
+    version: 3,
+    provenance: {
+        source: 'labre-convention',
+        reference: 'Labre convention (PO, recette of 02/08/2026) — Wardley names the zone, not the rule',
+    },
+    backgroundRole: WARDLEY_ROLE.map,
+    background: WARDLEY_BACKGROUND,
+    attachment: {
+        boundaryAxis: 'evolution',
+    },
+};
+/**
+ * **W3** — nodes and labels must not sit on top of each other.
+ *
+ * A readability rule, not a semantic one, which is why it is the softest of the
+ * three: a map you cannot read is useless, but a momentary overlap while you
+ * drag things into place is not a mistake.
+ *
+ * The four declared combinations are the ones that actually make a map
+ * illegible. Node/node hides an artefact outright; label/label and label/node
+ * make a name unreadable or attach it to the wrong thing; label/link is the one
+ * everybody hits, a name crossed out by the dependency running under it.
+ *
+ * Link/link is deliberately ABSENT: dependencies cross all the time on a real
+ * value chain, and that is the map working, not the map broken.
+ *
+ * ## Calibration (PO acceptance, 01/08/2026)
+ *
+ * Shipped, the rule was noisy in two ways the corpus could not see, because its
+ * fixtures were boxes rather than words:
+ *
+ * 1. a link crossing the EMPTY MARGIN of a label raised label/link. A label is
+ *    created 120–200 units wide whatever it says, so a short name left-aligned
+ *    in one leaves most of its box blank. Fixed where the mistake was: the
+ *    label role is `kind: 'text'`, so the engine measures the ink and not the
+ *    box (`textInkBound`).
+ * 2. two labels whose WORDS are nowhere near each other raised label/label,
+ *    for the same reason and with the same fix.
+ *
+ * `minPenetration` is what remains: not every touch is a collision. **4 model
+ * units** — under a quarter of the 18-unit node, a sixth of the 26-unit label
+ * line, and about the width of a dependency's own stroke. A link grazing the
+ * top of a name and two names whose last and first letter share a hair are
+ * silent; a link through the middle of a name scores half its line height (13)
+ * and a name written across a node scores the height of the letters, so both
+ * are still reported with room to spare.
+ *
+ * It also absorbs the declared imprecision of the width approximation, which is
+ * on the same scale — measured against the real renderer over 28 names, the
+ * engine's per-character table reads between 11 % narrow and dead on, never
+ * wide — and points the same way, towards silence.
+ *
+ * IN RESERVE, if label/link is still noisy after this (PO, 01/08/2026): an
+ * ANGLE criterion — only a link crossing a name roughly PERPENDICULARLY strikes
+ * it out, one running along it at a shallow angle mostly runs beside it. It
+ * would be declared here as data, exactly like the threshold, and evaluated by
+ * the family. Not built: nobody has yet seen the noise it would remove.
+ */
+const overlappingArtefacts = {
+    id: 'wardley.overlapping-artefacts',
+    framework: 'wardley',
+    family: 'no-overlap',
+    severity: 'warning',
+    // No `appliesTo`: this rule has no single subject role — the subjects are the
+    // pairs below, and naming one of them here would be data that lies.
+    roles: WARDLEY_ROLES,
+    messageKey: 'com.labre.wardley.validation.overlapping-artefacts',
+    messageFallback: 'These two overlap and make the map harder to read.',
+    suggestionKey: 'com.labre.wardley.validation.overlapping-artefacts.suggestion',
+    suggestionFallback: 'Move one of them aside.',
+    // 2: measured on the ink of a label rather than on its creation box, and
+    // calibrated with a penetration threshold — the same mistakes, fewer of the
+    // things that were never mistakes.
+    version: 2,
+    provenance: {
+        source: 'labre-convention',
+        reference: 'Labre readability convention — no Wardley mapping rule speaks of overlapping ink',
+    },
+    // Not a frame the rule measures against — an overlap is an overlap wherever
+    // it happens — but the map a finding is ATTRIBUTED to, so the arbitration
+    // "ignore this rule on the whole map" has one map to be written on.
+    backgroundRole: WARDLEY_ROLE.map,
+    overlap: [
+        [WARDLEY_ROLE.component, WARDLEY_ROLE.component],
+        [WARDLEY_ROLE.label, WARDLEY_ROLE.label],
+        [WARDLEY_ROLE.label, WARDLEY_ROLE.component],
+        [WARDLEY_ROLE.label, WARDLEY_ROLE.dependency],
+    ],
+    // How deep a collision has to be before it is one. See the header.
+    minPenetration: 4,
+};
+/**
+ * **W4** — a provider may not be positioned higher than its consumer.
+ *
+ * The value chain is the whole grammar of the map: the user sits at the top,
+ * each component rests on the components below it, and value flows back up. A
+ * dependency drawn from a component to something ABOVE it says the opposite of
+ * what the map means — either the link was drawn the wrong way round, or one of
+ * the two nodes is in the wrong place.
+ *
+ * ## The rule this one could not have been before `docs/adr/0010`
+ *
+ * W4 reads the persisted `source → target` pair of the edge, and that pair only
+ * became a STATEMENT the day the three mechanisms of that ADR landed: the link
+ * tool announces which way to drag (M1), a typed edge shows its orientation on
+ * hover and selection (M2), and the user can reverse it in one gesture (M3).
+ * Before them the direction was a by-product of which end the finger landed on
+ * first, and a rule on top of it would have spent the validation platform's
+ * credibility on its first false positive.
+ *
+ * The alternative — deriving the direction from the y coordinates — is not a
+ * cheaper W4, it is no W4 at all: the rule would compare the layout against
+ * itself and could never fire.
+ *
+ * ## The violation IS the affordance
+ *
+ * Nothing normalises the direction at creation, deliberately. An edge drawn
+ * upside-down raises this finding on the spot, and the user resolves it their
+ * way: drag the node, or reverse the relation. Either resolution is theirs.
+ *
+ * ## Tolerance
+ *
+ * 2% of the map's height, as a ratio and never as a number of units (the lesson
+ * of the 01/08/2026 recette, already learned by the equilibrium zone). Two
+ * components drawn level are not a mistake — a chain gets lined up before it
+ * gets spread out — so the rule only speaks when one is genuinely under the
+ * other. On the 900-high reference map that is 18 units, about the diameter of
+ * a component node.
+ */
+const providerAboveConsumer = {
+    id: 'wardley.provider-above-consumer',
+    framework: 'wardley',
+    family: 'relative-order-along-axis',
+    severity: 'warning',
+    // No `appliesTo`: the subject of this rule is a RELATION, and the role that
+    // names it is declared where the family reads it — naming one of the three
+    // indicted elements here would be data that lies.
+    roles: WARDLEY_ROLES,
+    messageKey: 'com.labre.wardley.validation.provider-above-consumer',
+    messageFallback: 'This component sits above the one that depends on it.',
+    suggestionKey: 'com.labre.wardley.validation.provider-above-consumer.suggestion',
+    suggestionFallback: 'Needs run downwards on a Wardley map: move the provider below its consumer — or, if the link was drawn the wrong way round, reverse it.',
+    version: 1,
+    provenance: {
+        source: 'recommendation',
+        reference: 'Wardley mapping — the value-chain grammar of the map',
+    },
+    backgroundRole: WARDLEY_ROLE.map,
+    background: WARDLEY_BACKGROUND,
+    relativeOrder: {
+        edgeRole: WARDLEY_ROLE.dependency,
+        axis: 'value-chain',
+        // Tier 2 of ADR 0010: the verb of `wardley:dependency` is "depends on", so
+        // its source is the CONSUMER and sits higher on the visibility axis.
+        expect: 'source-ahead',
+        toleranceRatio: 0.02,
+    },
+};
+export const WARDLEY_RULES = [
+    changeArrowAgainstEvolution,
+    inertiaOffTransition,
+    overlappingArtefacts,
+    providerAboveConsumer,
+];