@formicoidea/labre-framework-ddd-event-storming 0.32.0 → 0.34.1

package/dist/legend.js

@@ -0,0 +1,58 @@
+import { ES_HOTSPOT, ES_STICKIES, LABEL_COLOR, roleLabel, } from '@formicoidea/labre-ddd-shared';
+import { ES_ROLE, ES_STICKY_ROLE, EVENT_STORMING_ROLES } from './roles.js';
+/**
+ * What the Event Storming board's automatic legend can say — a TABLE, and
+ * nothing else: the scan, the placement and the box are `createAutoLegend`'s
+ * job.
+ *
+ * Every row is DERIVED from the palette the stickies are drawn with
+ * ({@link ES_STICKIES}, {@link ES_HOTSPOT}) and from the role vocabulary's own
+ * labels, never restated — so the colour ladder the legend shows is by
+ * construction the colour ladder on the wall, and a tenth sticky kind added to
+ * `ES_STICKIES` gets its legend row with no edit.
+ *
+ * The hotspot is appended for the same reason `roles.ts` appends it: it lives in
+ * its own preset (a diamond, not a square) rather than in the table.
+ */
+export const EVENT_STORMING_AUTO_LEGEND = {
+    title: 'Legend',
+    roles: EVENT_STORMING_ROLES,
+    sections: [
+        {
+            title: 'Stickies',
+            entries: [
+                ...ES_STICKIES.map(preset => ({
+                    role: ES_STICKY_ROLE[preset.kind],
+                    row: {
+                        swatch: 'square',
+                        color: preset.fill,
+                        label: preset.label,
+                    },
+                })),
+                {
+                    role: ES_STICKY_ROLE.hotspot,
+                    row: {
+                        swatch: 'square',
+                        color: ES_HOTSPOT.fill,
+                        label: ES_HOTSPOT.label,
+                    },
+                },
+            ],
+        },
+        {
+            title: 'Flow',
+            entries: [
+                {
+                    role: ES_ROLE.flow,
+                    row: {
+                        swatch: 'line',
+                        // The style `activateEventStormingFlow` arms the connector tool
+                        // with: a solid line in the label colour.
+                        color: LABEL_COLOR,
+                        label: roleLabel(EVENT_STORMING_ROLES, ES_ROLE.flow),
+                    },
+                },
+            ],
+        },
+    ],
+};

package/dist/nudges.d.ts

@@ -0,0 +1,26 @@
+import type { QualityNudge } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * Event Storming **board quality** — the checklist (WS5, level 2).
+ *
+ * `./rules.ts` is level 1: deterministic, decidable, real time. This file is
+ * everything a board needs that no algorithm can decide. The split is the
+ * taxonomy's whole point — ticking is assuming, never verifying.
+ *
+ * ## The past tense lives HERE, and that was an arbitration
+ *
+ * "Order placed" is a domain event; "Place order" is a command. It is the first
+ * thing a facilitator corrects and the most tempting rule in the whole plan —
+ * and it is a nudge, by PO arbitration of 26/08/2026, because deciding it means
+ * parsing a human sentence. In whatever language the room speaks. Written in
+ * marker pen. By somebody who abbreviates. A regular expression over `Y.Text`
+ * would be wrong every fifth sticky, and a validation platform gets exactly one
+ * chance to be wrong about something the user can see is right.
+ *
+ * So it is a tick, and the tick is honest: it says the room LOOKED, which is
+ * what the facilitator wanted anyway.
+ *
+ * Registered from the flag-gated `DddEventStormingViewExtension`: a checklist
+ * is tooling. Switching the flag off takes it away and leaves the ticks written
+ * on the board, unread, until it comes back.
+ */
+export declare const EVENT_STORMING_NUDGES: readonly QualityNudge[];

package/dist/nudges.js

@@ -0,0 +1,73 @@
+/**
+ * Event Storming **board quality** — the checklist (WS5, level 2).
+ *
+ * `./rules.ts` is level 1: deterministic, decidable, real time. This file is
+ * everything a board needs that no algorithm can decide. The split is the
+ * taxonomy's whole point — ticking is assuming, never verifying.
+ *
+ * ## The past tense lives HERE, and that was an arbitration
+ *
+ * "Order placed" is a domain event; "Place order" is a command. It is the first
+ * thing a facilitator corrects and the most tempting rule in the whole plan —
+ * and it is a nudge, by PO arbitration of 26/08/2026, because deciding it means
+ * parsing a human sentence. In whatever language the room speaks. Written in
+ * marker pen. By somebody who abbreviates. A regular expression over `Y.Text`
+ * would be wrong every fifth sticky, and a validation platform gets exactly one
+ * chance to be wrong about something the user can see is right.
+ *
+ * So it is a tick, and the tick is honest: it says the room LOOKED, which is
+ * what the facilitator wanted anyway.
+ *
+ * Registered from the flag-gated `DddEventStormingViewExtension`: a checklist
+ * is tooling. Switching the flag off takes it away and leaves the ticks written
+ * on the board, unread, until it comes back.
+ */
+export const EVENT_STORMING_NUDGES = [
+    {
+        /** See the header: the rule that is deliberately not a rule. */
+        id: 'es.q1-events-past-tense',
+        framework: 'ddd-event-storming',
+        labelKey: 'com.labre.event-storming.quality.events-past-tense',
+        fallback: 'Domain events are named in the past tense — something that happened, not something to do.',
+        order: 1,
+    },
+    {
+        /**
+         * `es.against-timeline` judges each arc against the axis; nothing can judge
+         * whether the frieze as a whole tells the story the room means. Reading it
+         * out loud, left to right, is the move that finds the missing half of it.
+         */
+        id: 'es.q2-timeline-read',
+        framework: 'ddd-event-storming',
+        labelKey: 'com.labre.event-storming.quality.timeline-read',
+        fallback: 'The timeline has been read out loud left to right, and reordered where it did not hold.',
+        order: 2,
+    },
+    {
+        id: 'es.q3-hotspots-discussed',
+        framework: 'ddd-event-storming',
+        labelKey: 'com.labre.event-storming.quality.hotspots-discussed',
+        fallback: 'Every hotspot has been discussed — resolved, or assumed on purpose with a name against it.',
+        order: 3,
+    },
+    {
+        id: 'es.q4-actors-and-systems',
+        framework: 'ddd-event-storming',
+        labelKey: 'com.labre.event-storming.quality.actors-and-systems',
+        fallback: 'The actors and the external systems are identified: every command has someone who issues it.',
+        order: 4,
+    },
+    {
+        /**
+         * A pivotal event is a marking CONVENTION — a vertical bar, a bigger
+         * sticky, a line drawn on the paper — and the canvas cannot tell one from a
+         * sticky somebody happened to enlarge. What matters is that the room agreed
+         * which moments split the story, which is a conversation and not a shape.
+         */
+        id: 'es.q5-pivotal-events',
+        framework: 'ddd-event-storming',
+        labelKey: 'com.labre.event-storming.quality.pivotal-events',
+        fallback: 'The pivotal events are marked: the board says where the story changes phase.',
+        order: 5,
+    },
+];

package/dist/profiles.d.ts

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

package/dist/profiles.js

@@ -0,0 +1,121 @@
+/**
+ * Event Storming validation profiles (WS5).
+ *
+ * DATA owned by the framework, like its rules and its roles. A profile is
+ * chosen per BOARD, not per document, and the choice rides on the board element
+ * itself — a Big Picture and a Process-modelling board coexist on one canvas at
+ * two levels of requirement, which is precisely how the workshop goes.
+ *
+ * ## Three, and why three (PO arbitration, 26/08/2026)
+ *
+ * Every other framework in this library ships two. Event Storming gets three
+ * because it is not one activity, it is a SEQUENCE of them, and the same wall
+ * means different things at each stage:
+ *
+ * 1. **Big Picture (Sketch)** — everything on the wall at once, out of order,
+ *    the grammar not yet decided. The linter must be silent;
+ * 2. **Process modelling** — the frieze gets read left to right and reordered.
+ *    Time starts to mean something; the grammar still does not;
+ * 3. **Software design** — the sentences are supposed to be sentences.
+ *
+ * Two profiles would have forced stage 2 to pick a side: either the timeline
+ * goes unchecked through the very session that is about ordering it, or the
+ * grammar starts firing at a wall that has not been cleaned up yet. The middle
+ * profile exists because the middle stage exists.
+ *
+ * Registered from the flag-gated `DddEventStormingViewExtension`, beside the
+ * rules: switching the flag off takes the choice away with the rest of the
+ * tooling, and a board already set to `design` simply stops being checked until
+ * it comes back — the id stays written, untouched.
+ */
+/**
+ * Sketch — the Big Picture. Every rule demoted to `audit`: findings still reach
+ * `violations$` for a host panel and a conformance report, and the canvas says
+ * nothing.
+ *
+ * Named **"Big Picture (Sketch)"** in the dropdown, both words on purpose (PO
+ * recette, 26/08/2026). "Sketch" is the vocabulary every framework in this
+ * library shares for its quietest level, and it is the word the recette script
+ * uses; "Big Picture" is the word the workshop uses for this stage and the only
+ * one a facilitator would look for. Carrying both is what lets the two readings
+ * meet on one entry instead of the user having to learn which name this
+ * framework chose.
+ *
+ * The DEFAULT, and more deliberately here than anywhere else in the library. A
+ * Big Picture is **supposed to be chaotic**: that is the method, not a failure
+ * of it. Events go up out of order because remembering is not sorting, arcs get
+ * drawn between things nobody has typed yet, and stickies get stacked three
+ * deep while a stack is what somebody means. A tool arguing with that hand is
+ * not strict, it is wrong — it is judging a stage of the workshop by the
+ * criteria of a later one.
+ *
+ * Being the default also means it WRITES NOTHING: a board on `sketch` carries no
+ * profile key, so every board ever stormed is on it, with no migration and no
+ * backfill.
+ */
+const sketch = {
+    id: 'es.sketch',
+    framework: 'ddd-event-storming',
+    labelKey: 'com.labre.event-storming.profile.sketch',
+    fallback: 'Big Picture (Sketch)',
+    isDefault: true,
+    rules: {
+        'es.against-timeline': 'audit',
+        'es.forbidden-arc': 'audit',
+        'es.overlapping-stickies': 'audit',
+    },
+};
+/**
+ * Process — the frieze is being read left to right and reordered.
+ *
+ * The timeline is the ONLY thing promoted, because ordering the frieze is
+ * exactly what this stage is for: an arc running backwards is now the finding
+ * the session is looking for, and the tool pointing at it is the tool helping.
+ *
+ * The grammar stays at `audit`, on purpose. The wall is still full of stickies
+ * whose kind nobody has settled — an event that is going to turn out to be a
+ * command, a read model somebody drew as an aggregate — and firing
+ * `forbidden-arc` at that is arguing about a sentence whose words are still
+ * being chosen. Overlaps stay quiet for the same reason: things are being
+ * MOVED, and everything overlaps while it is being moved.
+ */
+const process = {
+    id: 'es.process',
+    framework: 'ddd-event-storming',
+    labelKey: 'com.labre.event-storming.profile.process',
+    fallback: 'Process modelling',
+    rules: {
+        'es.against-timeline': 'warning',
+        'es.forbidden-arc': 'audit',
+        'es.overlapping-stickies': 'audit',
+    },
+};
+/**
+ * Design — the deliverable level: a board that leaves the room and is read by
+ * somebody who was not in it.
+ *
+ * All three at `warning`. By this stage every sticky has a kind, every arc is a
+ * claim about the model, and a frieze nobody can read is a frieze that will be
+ * misread. Every severity is spelled out rather than left absent, so the answer
+ * is readable in one place.
+ *
+ * Nothing here is `blocking-overridable`: nothing in this library implements
+ * refusal, and declaring it would be data claiming an effect that does not
+ * exist.
+ */
+const design = {
+    id: 'es.design',
+    framework: 'ddd-event-storming',
+    labelKey: 'com.labre.event-storming.profile.design',
+    fallback: 'Software design',
+    rules: {
+        'es.against-timeline': 'warning',
+        'es.forbidden-arc': 'warning',
+        'es.overlapping-stickies': 'warning',
+    },
+};
+export const EVENT_STORMING_PROFILES = [
+    sketch,
+    process,
+    design,
+];

package/dist/roles.d.ts

@@ -0,0 +1,62 @@
+import { ES_STICKIES } from '@formicoidea/labre-ddd-shared';
+import type { RoleDefs } from '@formicoidea/labre-core/std/gfx';
+/**
+ * Event Storming role vocabulary (WS5).
+ *
+ * A role is the semantic identity of an artefact — no rule will ever look at a
+ * shape type or at a fill colour. Three families:
+ *
+ * - the **board** (`es:board`), the paper roll the storm is run on;
+ * - the **sticky** (`es:sticky`), parent of the nine kinds the notation has;
+ * - the **flow** (`es:flow`), the edge that says one thing leads to another.
+ *
+ * ## Why a sticky PARENT
+ *
+ * Because two of the three rules are written on it and neither wants to know
+ * about the nine. `es.overlapping-stickies` is a readability rule — any two
+ * stickies on top of each other are unreadable, whichever kinds they are — and
+ * the day a tenth kind lands it is covered without a line changing.
+ * Specialisation is DATA (`parent`), read by `roleIsA`.
+ *
+ * ## The alphabet is smaller than the vocabulary
+ *
+ * All nine kinds get a role; only seven of them appear in the grammar
+ * (`es.forbidden-arc`). The **hotspot** and the **constraint** are declared here
+ * and cited by no triplet, deliberately: a hotspot is the workshop saying "we do
+ * not know", and a flow drawn onto one is somebody parking a question, not
+ * making a claim. Being outside the alphabet takes the whole edge out of the
+ * conversation (see `RelationEndpointsDef.allowed`), which is exactly the
+ * proportionality the family was built for.
+ *
+ * ## Compat
+ *
+ * Nothing is backfilled. Stickies placed before these roles existed carry none
+ * and are never evaluated (promesse #71): they stay drawings, in the documents
+ * they are in.
+ */
+/** The sticky kinds as used at the creation sites, hotspot included. */
+export type EventStormingStickyKind = (typeof ES_STICKIES)[number]['kind'] | 'hotspot';
+export type EventStormingRoleId = `es:${string}`;
+/**
+ * Role id per sticky kind, DERIVED from the shared preset table rather than
+ * restated — so the day a tenth sticky lands in `ES_STICKIES` it gets its role
+ * here with no edit. The hotspot is appended because it lives in its own preset
+ * (`ES_HOTSPOT`, a diamond rather than a square) and not in the table.
+ */
+export declare const ES_STICKY_ROLE: Record<EventStormingStickyKind, EventStormingRoleId>;
+/** The three roles that are not a sticky kind, plus the nine that are. */
+export declare const ES_ROLE: {
+    readonly domainEvent: `es:${string}`;
+    readonly command: `es:${string}`;
+    readonly aggregate: `es:${string}`;
+    readonly actor: `es:${string}`;
+    readonly constraint: `es:${string}`;
+    readonly policy: `es:${string}`;
+    readonly readModel: `es:${string}`;
+    readonly system: `es:${string}`;
+    readonly hotspot: `es:${string}`;
+    readonly board: "es:board";
+    readonly sticky: "es:sticky";
+    readonly flow: "es:flow";
+};
+export declare const EVENT_STORMING_ROLES: RoleDefs;

package/dist/roles.js

@@ -0,0 +1,84 @@
+import { ES_HOTSPOT, ES_STICKIES } from '@formicoidea/labre-ddd-shared';
+/** camelCase → kebab-case, the WS2 derivation. */
+const kebab = (kind) => kind.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+/**
+ * The one kind whose role id is not its kind kebab-cased.
+ *
+ * `system` is what the palette has called the sticky since the tool shipped and
+ * what its telemetry emits; `external-system` is what Event Storming calls the
+ * thing, and it is the word a rule and a hover reveal have to say. Renaming the
+ * kind would move a telemetry value (ADR 0008 forbids it) and renaming the role
+ * would make the grammar read `command → system`, which is not a sentence
+ * anybody says. One entry in a table is the cost of keeping both right.
+ */
+const ROLE_SLUG = {
+    system: 'external-system',
+};
+const slug = (kind) => ROLE_SLUG[kind] ?? kebab(kind);
+/**
+ * Role id per sticky kind, DERIVED from the shared preset table rather than
+ * restated — so the day a tenth sticky lands in `ES_STICKIES` it gets its role
+ * here with no edit. The hotspot is appended because it lives in its own preset
+ * (`ES_HOTSPOT`, a diamond rather than a square) and not in the table.
+ */
+export const ES_STICKY_ROLE = Object.fromEntries([
+    ...ES_STICKIES.map(preset => [preset.kind, `es:${slug(preset.kind)}`]),
+    ['hotspot', 'es:hotspot'],
+]);
+/** The three roles that are not a sticky kind, plus the nine that are. */
+export const ES_ROLE = {
+    board: 'es:board',
+    sticky: 'es:sticky',
+    flow: 'es:flow',
+    ...ES_STICKY_ROLE,
+};
+/** Human label per kind, from the same presets the palette renders. */
+const STICKY_LABEL = {
+    ...Object.fromEntries(ES_STICKIES.map(preset => [preset.kind, preset.label])),
+    hotspot: ES_HOTSPOT.label,
+};
+const DEFS = [
+    // The board: a frame, not a sticky. It specialises nothing, so a rule written
+    // on `es:sticky` can never fall on the roll its subjects are stuck to.
+    {
+        id: ES_ROLE.board,
+        kind: 'node',
+        labelKey: 'com.labre.event-storming.role.board',
+        labelFallback: 'Event Storming board',
+    },
+    {
+        id: ES_ROLE.sticky,
+        kind: 'node',
+        labelKey: 'com.labre.event-storming.role.sticky',
+        labelFallback: 'Sticky',
+    },
+    ...Object.keys(STICKY_LABEL).map((kind) => ({
+        id: ES_STICKY_ROLE[kind],
+        parent: ES_ROLE.sticky,
+        kind: 'node',
+        labelKey: `com.labre.event-storming.role.${slug(kind)}`,
+        labelFallback: STICKY_LABEL[kind],
+    })),
+    /**
+     * The flow. Tier 1 of `docs/adr/0010`: the source is the subject of the verb,
+     * so the source is what happens FIRST. Everything downstream of that sentence
+     * — the tool hint, the hover reveal, the inversion command and
+     * `es.against-timeline` — reads this one declaration and never a framework
+     * name.
+     */
+    {
+        id: ES_ROLE.flow,
+        kind: 'edge',
+        labelKey: 'com.labre.event-storming.role.flow',
+        labelFallback: 'Flow',
+        direction: {
+            verbKey: 'com.labre.event-storming.role.flow.verb',
+            verbFallback: 'leads to',
+            gestureHintKey: 'com.labre.event-storming.role.flow.gesture',
+            gestureHintFallback: 'Drag from what happens first to what follows.',
+        },
+    },
+];
+// 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 EVENT_STORMING_ROLES = Object.assign(Object.create(null), Object.fromEntries(DEFS.map(def => [def.id, def])));

package/dist/rules.d.ts

@@ -0,0 +1,20 @@
+import type { EndpointTriplet, ValidationRule } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * The canonical Event Storming sentence, as a matrix.
+ *
+ * Read aloud, which is how it was checked: an actor issues a command; a command
+ * lands on an aggregate, or on an external system; an aggregate raises a domain
+ * event, and so does an external system; a domain event triggers a policy, and
+ * a domain event feeds a read model; a policy issues a command; a read model
+ * informs an actor.
+ *
+ * Nine sentences and no more. Every one of them is in Brandolini's own picture
+ * of the "Big Picture → Process modelling" grammar, and nothing has been added
+ * because it seemed plausible: a matrix that sanctions a sentence the notation
+ * does not say is worse than no matrix, because the sentence it fails to catch
+ * is the one somebody will ship.
+ *
+ * Exported so a test asserts THIS table rather than a copy of it.
+ */
+export declare const ES_FLOW_MATRIX: readonly EndpointTriplet[];
+export declare const EVENT_STORMING_RULES: readonly ValidationRule[];