@formicoidea/labre-framework-bpmn 0.40.0 → 0.42.0

package/dist/import.js

@@ -1,3 +1,4 @@
+import { InterchangeImportError, } from '@formicoidea/labre-core/blocks/surface';
 import { ConnectorMode, PointStyle, StrokeStyle } from '@formicoidea/labre-core/model';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
 import { ASSOCIATION_STROKE, ASSOCIATION_WIDTH, MESSAGE_STROKE, MESSAGE_WIDTH, NODE_SIZE, POOL_BAND_WIDTH, POOL_REF_HEIGHT, POOL_REF_WIDTH, SEQUENCE_STROKE, SEQUENCE_WIDTH, } from './consts.js';
@@ -5,21 +6,33 @@ import { BPMN_FORMAT_ID, BPMN_NS, BPMN_OWN_DECLARATIONS, BPMN_SCOPE, BPMN_XML_OF
 import { bpmnNodeProps } from './presets.js';
 import { BPMN_ROLE } from './roles.js';
 /**
- * The remarks whose wording is FIXED, as `[key, English]` pairs.
+ * The remarks whose wording is FIXED, as `[key, English]` pairs — one entry
+ * per SHAPE of sentence, never one per exact string: a remark that names
+ * something out of the file (`<boundaryEvent>`, an id, a count of lanes)
+ * carries `{{name}}` / `{{count}}` holes in the fallback here, filled at the
+ * call site by `messageParams` (`InterchangeNote.messageParams`) — never by
+ * minting a new key for every value the file happens to carry.
  *
  * A reader is a pure function of text (`docs/adr/0012`, P3) and has no `std`,
- * so it cannot ask the host's catalogue for anything: it declares the key on
- * the note and `reportInterchangeImport` resolves it when it draws the report
- * (`InterchangeNote.messageKey`). The English string stays here and stays the
- * fallback, so the console table and a playground with no catalogue read
- * exactly what they read before.
+ * so it cannot ask the host's catalogue for anything: it declares the key
+ * (and, where the sentence has a hole, the params) on the note, and
+ * `reportInterchangeImport` resolves both when it draws the report
+ * (`InterchangeNote.messageKey` / `.messageParams`). The English string stays
+ * here and stays the fallback, so the console table and a playground with no
+ * catalogue read exactly what they read before: `translateKey` fills a
+ * `{{…}}` hole from `messageParams` even with no `TranslationProvider`
+ * registered (`fillPlaceholders`), so the ENGLISH sentence a call site builds
+ * is unchanged by giving it a key.
  *
- * These three and no others, and the line is not arbitrary: every remaining
- * remark NAMES something out of the file — `<boundaryEvent>`, an id, a count of
- * lanes — and the seam has neither interpolation nor pluralisation. A key for
- * one of those would be a sentence with holes in it that a translator cannot
- * see the shape of, which is the same refusal the interchange count labels
- * already make (`interchange-import.ts`).
+ * Plural wording is the host's: where a count can be 0, 1 or many, the
+ * fallback stays grammatically neutral (`'{{count}} lane(s)…'`) rather than
+ * picking English's own singular/plural — the same rule
+ * `interchange-import.ts`'s own count labels follow.
+ *
+ * `BPMN_QUARANTINE_REASON` (declared further down, with its own key pairing)
+ * is the one exception: its plain string is ALSO written verbatim into
+ * `ForeignInterchange.quarantined[].reason` (data, never translated), so it
+ * cannot become a `[key, english]` pair without breaking that contract.
  *
  * They are contributed to the manifest by `./translations.ts`, with the
  * framework, because they ship in the BPMN bundle rather than in core.
@@ -37,6 +50,80 @@ export const BPMN_IMPORT_REMARKS = {
         'com.labre.bpmn.import.remark.must-understand',
         'The file declares an extension that it says MUST be understood to read the model correctly. Labre does not understand it: the import went ahead, and this reading of the process may be wrong.',
     ],
+    duplicateId: [
+        'com.labre.bpmn.import.remark.duplicate-id',
+        'Two elements in this file share the id "{{id}}", which BPMN requires to be unique across a document. Both were imported; the second will be written back under an id Labre mints.',
+    ],
+    carriedChild: [
+        'com.labre.bpmn.import.remark.carried-child',
+        '<{{tag}}> has no Labre artefact, so it is kept verbatim on the nearest element that has one. It is not drawn, and no validation rule sees it.',
+    ],
+    inventedPoolLayout: [
+        'com.labre.bpmn.import.remark.invented-pool-layout',
+        'The participant "{{name}}" arrived with no diagram, so Labre placed its pool beside the drawing.',
+    ],
+    inventedLaneLayout: [
+        'com.labre.bpmn.import.remark.invented-lane-layout',
+        "{{count}} lane(s) arrived with no diagram, so Labre split the pool into equal bands. The proportions are Labre's and not the file's.",
+    ],
+    undrawnTrigger: [
+        'com.labre.bpmn.import.remark.undrawn-trigger',
+        '<{{tag}}> names its trigger by reference to "{{ref}}", which Labre does not draw. The event was kept whole rather than drawn as a plain one.',
+    ],
+    inventedNodeLayout: [
+        'com.labre.bpmn.import.remark.invented-node-layout',
+        "<{{tag}}> arrived with no diagram, so Labre placed it beside the drawing. Its position is Labre's and not the file's.",
+    ],
+    singleEndedFlow: [
+        'com.labre.bpmn.import.remark.single-ended-flow',
+        '<{{tag}}> names only one of its two ends, so there is no arrow to draw between them. It was left out.',
+    ],
+    danglingFlowEnd: [
+        'com.labre.bpmn.import.remark.dangling-flow-end',
+        '<{{tag}}> runs to {{ends}}, not drawn on this canvas. The flow is kept whole beside them rather than drawn with a loose end.',
+    ],
+    undeclaredShape: [
+        'com.labre.bpmn.import.remark.undeclared-shape',
+        'The diagram draws "{{id}}", which the file does not declare. The shape is kept, and nothing is drawn for it.',
+    ],
+    noProcessResidue: [
+        'com.labre.bpmn.import.remark.no-process-residue',
+        'This file declares {{count}} root element(s) and no process to draw, so there was no artefact for them to be kept on. Nothing was imported.',
+    ],
+    laneDrift: [
+        'com.labre.bpmn.import.remark.lane-drift',
+        'The file lists this artefact in the lane "{{listedLane}}" and draws it in "{{drawnLane}}". Labre reads the drawing: a lane holds what is drawn inside it.',
+    ],
+    inventedRouting: [
+        'com.labre.bpmn.import.remark.invented-routing',
+        '{{count}} flow(s) carry an explicit routing in the file. Labre routes a flow between its two ends and re-routes it whenever they move, so their bend points are not kept.',
+    ],
+};
+/**
+ * The reader's own refusals, as `[key, English]` pairs — thrown via
+ * {@link InterchangeImportError}, never returned, because none of these say
+ * "this is a file I can partly read" (see `parseDefinitions` and the
+ * choreography refusal, below). Same shape and the same reason as
+ * {@link BPMN_IMPORT_REMARKS}: one entry per shape of refusal, `{{name}}`
+ * holes filled by `InterchangeImportError.messageParams`.
+ */
+export const BPMN_IMPORT_ERRORS = {
+    malformedXml: [
+        'com.labre.bpmn.import.error.malformed-xml',
+        'This file is not well-formed XML, so no BPMN can be read out of it: {{detail}}',
+    ],
+    notDefinitions: [
+        'com.labre.bpmn.import.error.not-definitions',
+        'A BPMN file opens on <definitions>; this one opens on <{{tag}}>.',
+    ],
+    wrongNamespace: [
+        'com.labre.bpmn.import.error.wrong-namespace',
+        'This <definitions> is in "{{namespace}}", not in BPMN 2.0\'s ("{{bpmnNamespace}}"). A DMN decision model and a BPMN process open on the same element name and are not the same file.',
+    ],
+    declinedRootKind: [
+        'com.labre.bpmn.import.error.declined-root-kind',
+        'This file is a BPMN {{kind}}, which Labre does not draw. Only a process or a collaboration can be imported.',
+    ],
 };
 /**
  * A BPMN 2.0 interchange document, read as a board — the inverse of `export.ts`
@@ -223,6 +310,25 @@ export const BPMN_QUARANTINE_REASON = {
         'self-contained set), so writing this back would claim a resolution of ' +
         'another document that never happened.',
 };
+/**
+ * {@link BPMN_QUARANTINE_REASON}'s own i18n keys, one per reason.
+ *
+ * A SEPARATE table rather than folding the key into each reason string
+ * (`BPMN_IMPORT_REMARKS`'s `[key, english]` shape): `BPMN_QUARANTINE_REASON`'s
+ * plain strings are ALSO written verbatim into
+ * `ForeignInterchange.quarantined[].reason` — a DATA field the reader hands
+ * the writer, never re-emitted, never shown, and pinned in
+ * `import.unit.spec.ts` as the literal English text — so it cannot become a
+ * tuple without breaking that contract. Only the REPORT note (`messageKey`
+ * below) is resolved through the host's catalogue; the carried `reason` data
+ * stays English, exactly as it always has.
+ */
+export const BPMN_QUARANTINE_REASON_KEY = {
+    colour: 'com.labre.bpmn.import.quarantine.colour',
+    expanded: 'com.labre.bpmn.import.quarantine.expanded',
+    nestedLanes: 'com.labre.bpmn.import.quarantine.nested-lanes',
+    imported: 'com.labre.bpmn.import.quarantine.imported',
+};
 /**
  * The children of an activity that are NOT its body.
  *
@@ -344,21 +450,32 @@ function parseDefinitions(source) {
     const doc = new DOMParser().parseFromString(source, 'application/xml');
     const error = doc.querySelector('parsererror');
     if (error) {
-        throw new Error(`This file is not well-formed XML, so no BPMN can be read out of it: ` +
-            `${(error.textContent ?? '').trim().slice(0, 200)}`);
+        const detail = (error.textContent ?? '').trim().slice(0, 200);
+        throw new InterchangeImportError(`This file is not well-formed XML, so no BPMN can be read out of it: ${detail}`, {
+            messageKey: BPMN_IMPORT_ERRORS.malformedXml[0],
+            messageParams: { detail },
+        });
     }
     const root = doc.documentElement;
     if (!root || root.localName !== 'definitions') {
-        throw new Error(`A BPMN file opens on <definitions>; this one opens on <${root?.localName ?? 'nothing'}>.`);
+        const tag = root?.localName ?? 'nothing';
+        throw new InterchangeImportError(`A BPMN file opens on <definitions>; this one opens on <${tag}>.`, {
+            messageKey: BPMN_IMPORT_ERRORS.notDefinitions[0],
+            messageParams: { tag },
+        });
     }
     // The NAMESPACE, not the element name — `<definitions>` is also the root of a
     // DMN decision model, and of anything else built on the same OMG scaffolding.
     // Without this a `.dmn` imports as an empty board, which is exactly the
     // "three zeroes claiming an empty process" this reader refuses to return.
     if (root.namespaceURI !== BPMN_NS.model) {
-        throw new Error(`This <definitions> is in "${root.namespaceURI ?? 'no namespace'}", not ` +
+        const namespace = root.namespaceURI ?? 'no namespace';
+        throw new InterchangeImportError(`This <definitions> is in "${namespace}", not ` +
             `in BPMN 2.0's ("${BPMN_NS.model}"). A DMN decision model and a BPMN ` +
-            `process open on the same element name and are not the same file.`);
+            `process open on the same element name and are not the same file.`, {
+            messageKey: BPMN_IMPORT_ERRORS.wrongNamespace[0],
+            messageParams: { namespace, bpmnNamespace: BPMN_NS.model },
+        });
     }
     return root;
 }
@@ -612,8 +729,12 @@ export function importBpmnXml(source, context = {}) {
     if (processes.length === 0 && collaborations.length === 0) {
         const declined = roots.find(root => ['choreography', 'globalChoreographyTask', 'conversation'].includes(root.localName));
         if (declined) {
-            throw new Error(`This file is a BPMN ${declined.localName}, which Labre does not draw. ` +
-                `Only a process or a collaboration can be imported.`);
+            const kind = declined.localName;
+            throw new InterchangeImportError(`This file is a BPMN ${kind}, which Labre does not draw. ` +
+                `Only a process or a collaboration can be imported.`, {
+                messageKey: BPMN_IMPORT_ERRORS.declinedRootKind[0],
+                messageParams: { kind },
+            });
         }
     }
     /** `categoryValue` id → the label a `group` pointing at it wears. */
@@ -637,9 +758,9 @@ export function importBpmnXml(source, context = {}) {
                 kind: 'substituted-id',
                 sourceId,
                 element,
-                message: `Two elements in this file share the id "${sourceId}", which BPMN ` +
-                    `requires to be unique across a document. Both were imported; the ` +
-                    `second will be written back under an id Labre mints.`,
+                messageKey: BPMN_IMPORT_REMARKS.duplicateId[0],
+                message: `Two elements in this file share the id "${sourceId}", which BPMN requires to be unique across a document. Both were imported; the second will be written back under an id Labre mints.`,
+                messageParams: { id: sourceId },
             });
         }
         seenSourceIds.add(sourceId);
@@ -671,9 +792,9 @@ export function importBpmnXml(source, context = {}) {
             kind: 'carried',
             element: child.nodeName,
             sourceId,
-            message: `<${child.nodeName}> has no Labre artefact, so it is kept verbatim on ` +
-                `the nearest element that has one. It is not drawn, and no validation ` +
-                `rule sees it.`,
+            messageKey: BPMN_IMPORT_REMARKS.carriedChild[0],
+            message: `<${child.nodeName}> has no Labre artefact, so it is kept verbatim on the nearest element that has one. It is not drawn, and no validation rule sees it.`,
+            messageParams: { tag: child.nodeName },
         });
     };
     /** One diagram fragment, kept under the scope of what it DRAWS. */
@@ -684,13 +805,23 @@ export function importBpmnXml(source, context = {}) {
         };
         carried++;
     };
-    const quarantine = (payload, fragment, reason, entry) => {
+    const quarantine = (payload, fragment, reason, entry, 
+    // The reason's OWN key ({@link BPMN_QUARANTINE_REASON_KEY}) — separate
+    // from `reason` because that string is also written into
+    // `payload.quarantined[].reason` (data, never translated); only the
+    // REPORT note below carries the key.
+    reasonKey) => {
         payload.quarantined = [
             ...(payload.quarantined ?? []),
             { fragment, reason },
         ];
         quarantined++;
-        note({ kind: 'quarantined', ...entry, message: reason });
+        note({
+            kind: 'quarantined',
+            ...entry,
+            message: reason,
+            ...(reasonKey ? { messageKey: reasonKey } : {}),
+        });
     };
     /** Every attribute the reader does not model — colours quarantined (D5). */
     const sortAttributes = (element, payload, scope, sourceId, understood = READ_ATTRS[element.localName] ??
@@ -701,7 +832,7 @@ export function importBpmnXml(source, context = {}) {
             if (understood.includes(attr.name))
                 continue;
             if (isColourAttr(attr)) {
-                quarantine(payload, `${attr.name}="${escapeAttr(attr.value)}"`, BPMN_QUARANTINE_REASON.colour, { sourceId, element: attr.name });
+                quarantine(payload, `${attr.name}="${escapeAttr(attr.value)}"`, BPMN_QUARANTINE_REASON.colour, { sourceId, element: attr.name }, BPMN_QUARANTINE_REASON_KEY.colour);
                 continue;
             }
             carryAttr(payload, scope, attr.name, attr.value);
@@ -792,12 +923,14 @@ export function importBpmnXml(source, context = {}) {
         if (process)
             poolOfProcess.set(process, draft);
         if (!bounds) {
+            const name = draft.props.name || 'unnamed';
             note({
                 kind: 'invented-layout',
                 sourceId,
                 element: 'participant',
-                message: `The participant "${draft.props.name || 'unnamed'}" arrived with no ` +
-                    `diagram, so Labre placed its pool beside the drawing.`,
+                messageKey: BPMN_IMPORT_REMARKS.inventedPoolLayout[0],
+                message: `The participant "${name}" arrived with no diagram, so Labre placed its pool beside the drawing.`,
+                messageParams: { name },
             });
         }
     }
@@ -887,7 +1020,7 @@ export function importBpmnXml(source, context = {}) {
                 const name = attrOf(lane, 'name') ?? '';
                 const nested = modelChild(lane, 'childLaneSet');
                 if (nested) {
-                    quarantine(pool.payload, fragmentOf(nested), BPMN_QUARANTINE_REASON.nestedLanes, { sourceId, element: 'childLaneSet' });
+                    quarantine(pool.payload, fragmentOf(nested), BPMN_QUARANTINE_REASON.nestedLanes, { sourceId, element: 'childLaneSet' }, BPMN_QUARANTINE_REASON_KEY.nestedLanes);
                     // A lane holding a child set is not a band Labre paints — its LEAVES
                     // are — so the shape drawing it describes a subdivision the flat pool
                     // does not have. Accounted for by the quarantine, and kept out of the
@@ -959,9 +1092,9 @@ export function importBpmnXml(source, context = {}) {
                 kind: 'invented-layout',
                 sourceId: attrOf(laneSet, 'id'),
                 element: 'laneSet',
-                message: `${bands.length === 1 ? 'This lane' : `Some of these ${bands.length} lanes`} ` +
-                    `arrived with no diagram, so Labre split the pool into equal bands. ` +
-                    `The proportions are Labre's and not the file's.`,
+                messageKey: BPMN_IMPORT_REMARKS.inventedLaneLayout[0],
+                message: `${bands.length} lane(s) arrived with no diagram, so Labre split the pool into equal bands. The proportions are Labre's and not the file's.`,
+                messageParams: { count: bands.length },
             });
         }
         // Bands that do not tile the pool are still only WEIGHTS here — Labre lays
@@ -1035,13 +1168,14 @@ export function importBpmnXml(source, context = {}) {
         // whole into the carried branch below rather than onto the canvas claiming
         // something the file did not say.
         if (kind === undefined && triggerRef !== undefined) {
+            const ref = triggerRef.textContent?.trim() ?? '';
             note({
                 kind: 'warning',
                 sourceId,
                 element: local,
-                message: `<${local}> names its trigger by reference to ` +
-                    `"${triggerRef.textContent?.trim() ?? ''}", which Labre does not ` +
-                    `draw. The event was kept whole rather than drawn as a plain one.`,
+                messageKey: BPMN_IMPORT_REMARKS.undrawnTrigger[0],
+                message: `<${local}> names its trigger by reference to "${ref}", which Labre does not draw. The event was kept whole rather than drawn as a plain one.`,
+                messageParams: { tag: local, ref },
             });
         }
         if (kind === undefined) {
@@ -1100,7 +1234,7 @@ export function importBpmnXml(source, context = {}) {
                 continue;
             }
             if (expanded && isModel(child) && !NOT_A_BODY.has(child.localName)) {
-                quarantine(payload, fragmentOf(child), BPMN_QUARANTINE_REASON.expanded, { sourceId, element: child.nodeName });
+                quarantine(payload, fragmentOf(child), BPMN_QUARANTINE_REASON.expanded, { sourceId, element: child.nodeName }, BPMN_QUARANTINE_REASON_KEY.expanded);
                 // The body's diagram goes with the body, all the way down. A shape left
                 // behind here is an ORPHAN — nothing declares what it draws any more —
                 // so the residue sweep at the end of this reader would pick it up and
@@ -1152,8 +1286,9 @@ export function importBpmnXml(source, context = {}) {
                 kind: 'invented-layout',
                 sourceId,
                 element: local,
-                message: `<${local}> arrived with no diagram, so Labre placed it beside the ` +
-                    `drawing. Its position is Labre's and not the file's.`,
+                messageKey: BPMN_IMPORT_REMARKS.inventedNodeLayout[0],
+                message: `<${local}> arrived with no diagram, so Labre placed it beside the drawing. Its position is Labre's and not the file's.`,
+                messageParams: { tag: local },
             });
         }
     };
@@ -1188,8 +1323,9 @@ export function importBpmnXml(source, context = {}) {
                     kind: 'warning',
                     sourceId,
                     element: local,
-                    message: `<${local}> names only one of its two ends, so there is no arrow ` +
-                        `to draw between them. It was left out.`,
+                    messageKey: BPMN_IMPORT_REMARKS.singleEndedFlow[0],
+                    message: `<${local}> names only one of its two ends, so there is no arrow to draw between them. It was left out.`,
+                    messageParams: { tag: local },
                 });
                 continue;
             }
@@ -1208,16 +1344,17 @@ export function importBpmnXml(source, context = {}) {
                 if (edgeDi) {
                     carryDi(host.payload, sourceId ?? hostScope, fragmentOf(edgeDi.element));
                 }
-                note({
-                    kind: 'warning',
-                    sourceId,
-                    element: local,
-                    message: `<${local}> runs to ${dangling.map(end => `"${end}"`).join(' and ')}, ` +
-                        `which ${dangling.length === 1 ? 'is' : 'are'} not drawn on this ` +
-                        `canvas. The flow is kept whole beside ` +
-                        `${dangling.length === 1 ? 'it' : 'them'} rather than drawn with a ` +
-                        `loose end.`,
-                });
+                {
+                    const ends = dangling.map(end => `"${end}"`).join(' and ');
+                    note({
+                        kind: 'warning',
+                        sourceId,
+                        element: local,
+                        messageKey: BPMN_IMPORT_REMARKS.danglingFlowEnd[0],
+                        message: `<${local}> runs to ${ends}, not drawn on this canvas. The flow is kept whole beside them rather than drawn with a loose end.`,
+                        messageParams: { tag: local, ends },
+                    });
+                }
                 continue;
             }
             claim(sourceId, local);
@@ -1340,7 +1477,7 @@ export function importBpmnXml(source, context = {}) {
             // file, so writing an `<import>` back would claim a resolution we never
             // made.
             if (isModel(root) && root.localName === 'import') {
-                quarantine(host.payload, fragmentOf(root), BPMN_QUARANTINE_REASON.imported, { element: 'import' });
+                quarantine(host.payload, fragmentOf(root), BPMN_QUARANTINE_REASON.imported, { element: 'import' }, BPMN_QUARANTINE_REASON_KEY.imported);
                 continue;
             }
             // Not quarantine: the file telling us our reading of it may be wrong,
@@ -1376,8 +1513,9 @@ export function importBpmnXml(source, context = {}) {
                 kind: 'warning',
                 sourceId: target,
                 element: shape.localName,
-                message: `The diagram draws "${target}", which the file does not declare. ` +
-                    `The shape is kept, and nothing is drawn for it.`,
+                messageKey: BPMN_IMPORT_REMARKS.undeclaredShape[0],
+                message: `The diagram draws "${target}", which the file does not declare. The shape is kept, and nothing is drawn for it.`,
+                messageParams: { id: target },
             });
         }
     }
@@ -1387,11 +1525,9 @@ export function importBpmnXml(source, context = {}) {
         // process and no participant has none.
         note({
             kind: 'warning',
-            message: `This file declares ${residue.length} root ` +
-                `${residue.length === 1 ? 'element' : 'elements'} and no process to ` +
-                `draw, so there was no artefact for ` +
-                `${residue.length === 1 ? 'it' : 'them'} to be kept on. Nothing was ` +
-                `imported.`,
+            messageKey: BPMN_IMPORT_REMARKS.noProcessResidue[0],
+            message: `This file declares ${residue.length} root element(s) and no process to draw, so there was no artefact for them to be kept on. Nothing was imported.`,
+            messageParams: { count: residue.length },
         });
     }
     /* ── Lane membership: checked against the drawing, never stored (D3) ─ */
@@ -1413,9 +1549,12 @@ export function importBpmnXml(source, context = {}) {
                     kind: 'warning',
                     sourceId: ref,
                     element: 'flowNodeRef',
-                    message: `The file lists this artefact in the lane "${band.lane.name}" and ` +
-                        `draws it in "${drawnIn.lane.name}". Labre reads the drawing: a ` +
-                        `lane holds what is drawn inside it.`,
+                    messageKey: BPMN_IMPORT_REMARKS.laneDrift[0],
+                    message: `The file lists this artefact in the lane "${band.lane.name ?? ''}" and draws it in "${drawnIn.lane.name ?? ''}". Labre reads the drawing: a lane holds what is drawn inside it.`,
+                    messageParams: {
+                        listedLane: band.lane.name ?? '',
+                        drawnLane: drawnIn.lane.name ?? '',
+                    },
                 });
             }
         }
@@ -1425,11 +1564,9 @@ export function importBpmnXml(source, context = {}) {
     if (explicitRoutes > 0) {
         note({
             kind: 'invented-layout',
-            message: `${explicitRoutes} ${explicitRoutes === 1 ? 'flow carries' : 'flows carry'} ` +
-                `an explicit routing in the file. Labre routes a flow between its two ` +
-                `ends and re-routes it whenever they move, so ` +
-                `${explicitRoutes === 1 ? 'its bend points are' : 'their bend points are'} ` +
-                `not kept.`,
+            messageKey: BPMN_IMPORT_REMARKS.inventedRouting[0],
+            message: `${explicitRoutes} flow(s) carry an explicit routing in the file. Labre routes a flow between its two ends and re-routes it whenever they move, so their bend points are not kept.`,
+            messageParams: { count: explicitRoutes },
         });
     }
     /* ── Out ───────────────────────────────────────────────────────────── */

package/dist/interchange.d.ts

@@ -48,6 +48,40 @@ export declare const BPMN_XML_FORMAT: InterchangeFormat;
  * gives a centre inside two overlapping pools to the FIRST one, and the audit's
  * `attribute()` does the same. Sorting here would make the export disagree with
  * the badge the user can see.
+ *
+ * ## The filter is the ROLE, not the class
+ *
+ * A `BpmnNodeElementModel` is a shape with a `kind`; the ROLE is the author's
+ * statement that this circle IS the start of the process (`docs/adr/0010`, and
+ * C4's `isC4Node` before it). The distinction became load-bearing the day the
+ * pool grew a legend: a legend swatch is a real `bpmnNode` with a real `kind`
+ * and deliberately NO role, so a class-based filter would have written eighteen
+ * ghost `<task>` / `<startEvent>` / `<dataObject>` elements into the
+ * participant's process and broken the bpmn.io round trip the pack is for. The
+ * connectors have always been filtered this way (`EDGE_ELEMENT[connector.role]`
+ * in `export.ts`); this is the nodes and the pools catching up.
+ *
+ * ## What it costs, and the PO took that cost
+ *
+ * The pack shipped on 2026-06-13 and roles on 2026-08-26, with nothing
+ * backfilled (`roles.ts` says so in as many words). A process drawn between
+ * those two dates carries no role on anything and therefore no longer exports.
+ * Arbitrated on 2026-09-17: the alternative is an interchange file that cannot
+ * be trusted, which is worse than one that is not written.
+ *
+ * ## …and what it now SAYS
+ *
+ * The same ruling of 2026-09-17 added the other half: everything inside a
+ * pool's perimeter leaves in the board's generic SVG export (ADR 0025, R34),
+ * and only the roled artefacts leave in the `.bpmn`. That asymmetry is wanted;
+ * being silent about it was not. So the role-less things drawn INSIDE a pool
+ * are counted here — this is the only place that sees what was not picked —
+ * and `exportBpmnXmlWithWarnings` turns the count into one warning.
+ *
+ * Connectors are deliberately NOT counted: a neutral arrow states nothing
+ * (`docs/adr/0010`), so there is nothing to lose, which is the reason
+ * `export.ts` has always dropped one in silence. Neither is a generated legend
+ * — see {@link legendMemberIds}.
  */
 export declare function bpmnBoardFrom(elements: readonly GfxPrimitiveElementModel[]): BpmnExportBoard;
 /**

package/dist/interchange.js

@@ -1,7 +1,10 @@
-import { interchangeCapabilityId, parseSvgSketch, SVG_SKETCH_EXTENSION, SVG_SKETCH_FORMAT_ID, SVG_SKETCH_MIME, } from '@formicoidea/labre-core/blocks/surface';
+import { interchangeCapabilityId, LEGEND_ROLE, parseSvgSketch, SVG_SKETCH_EXTENSION, SVG_SKETCH_FORMAT_ID, SVG_SKETCH_MIME, } from '@formicoidea/labre-core/blocks/surface';
 import { BpmnNodeElementModel, BpmnPoolElementModel, ConnectorElementModel, } from '@formicoidea/labre-core/model';
+import { fillPlaceholders } from '@formicoidea/labre-core/shared/services';
 import { BPMN_FORMAT_ID, exportBpmnXmlWithWarnings, } from './export.js';
+import { bpmnPoolOf } from './facts.js';
 import { importBpmnXml } from './import.js';
+import { BPMN_ROLE, BPMN_ROLE_OF_KIND } from './roles.js';
 /**
  * BPMN's entries in the interchange registry (`docs/adr/0012`, P1).
  *
@@ -48,6 +51,41 @@ export const BPMN_XML_FORMAT = {
     mime: BPMN_XML_MIME,
 };
 /* ── Pure board helpers ───────────────────────────────────────────────── */
+/**
+ * Everything a generated legend is made of: the group the legend gesture stamps
+ * with {@link LEGEND_ROLE}, and everything under it.
+ *
+ * A legend is drawn INSIDE the board it documents (`createBoardLegend`) and is
+ * made, on purpose, of role-less shapes, texts and swatches — so without this
+ * it would be reported as fourteen things the `.bpmn` left out, which is
+ * exactly the surprise that warning exists to prevent. The group's ROLE is what
+ * it is read by: nothing here matches a title, a framework name or a box.
+ *
+ * Read defensively, like every other walk over stored data in this framework:
+ * the children came out of a Y.Map and are whatever a peer wrote.
+ */
+function legendMemberIds(elements) {
+    const byId = new Map(elements.map(element => [element.id, element]));
+    const members = new Set();
+    const walk = (element) => {
+        if (members.has(element.id))
+            return;
+        members.add(element.id);
+        const children = element.childIds;
+        if (!Array.isArray(children))
+            return;
+        for (const id of children) {
+            const child = typeof id === 'string' ? byId.get(id) : undefined;
+            if (child)
+                walk(child);
+        }
+    };
+    for (const element of elements) {
+        if (element.role === LEGEND_ROLE)
+            walk(element);
+    }
+    return members;
+}
 /**
  * The artefacts the exporter speaks about, picked out of a surface's elements
  * and kept in the order they were given.
@@ -56,20 +94,75 @@ export const BPMN_XML_FORMAT = {
  * gives a centre inside two overlapping pools to the FIRST one, and the audit's
  * `attribute()` does the same. Sorting here would make the export disagree with
  * the badge the user can see.
+ *
+ * ## The filter is the ROLE, not the class
+ *
+ * A `BpmnNodeElementModel` is a shape with a `kind`; the ROLE is the author's
+ * statement that this circle IS the start of the process (`docs/adr/0010`, and
+ * C4's `isC4Node` before it). The distinction became load-bearing the day the
+ * pool grew a legend: a legend swatch is a real `bpmnNode` with a real `kind`
+ * and deliberately NO role, so a class-based filter would have written eighteen
+ * ghost `<task>` / `<startEvent>` / `<dataObject>` elements into the
+ * participant's process and broken the bpmn.io round trip the pack is for. The
+ * connectors have always been filtered this way (`EDGE_ELEMENT[connector.role]`
+ * in `export.ts`); this is the nodes and the pools catching up.
+ *
+ * ## What it costs, and the PO took that cost
+ *
+ * The pack shipped on 2026-06-13 and roles on 2026-08-26, with nothing
+ * backfilled (`roles.ts` says so in as many words). A process drawn between
+ * those two dates carries no role on anything and therefore no longer exports.
+ * Arbitrated on 2026-09-17: the alternative is an interchange file that cannot
+ * be trusted, which is worse than one that is not written.
+ *
+ * ## …and what it now SAYS
+ *
+ * The same ruling of 2026-09-17 added the other half: everything inside a
+ * pool's perimeter leaves in the board's generic SVG export (ADR 0025, R34),
+ * and only the roled artefacts leave in the `.bpmn`. That asymmetry is wanted;
+ * being silent about it was not. So the role-less things drawn INSIDE a pool
+ * are counted here — this is the only place that sees what was not picked —
+ * and `exportBpmnXmlWithWarnings` turns the count into one warning.
+ *
+ * Connectors are deliberately NOT counted: a neutral arrow states nothing
+ * (`docs/adr/0010`), so there is nothing to lose, which is the reason
+ * `export.ts` has always dropped one in silence. Neither is a generated legend
+ * — see {@link legendMemberIds}.
  */
 export function bpmnBoardFrom(elements) {
     const pools = [];
     const nodes = [];
     const connectors = [];
+    const roleless = [];
     for (const element of elements) {
-        if (element instanceof BpmnPoolElementModel)
-            pools.push(element);
-        else if (element instanceof BpmnNodeElementModel)
-            nodes.push(element);
-        else if (element instanceof ConnectorElementModel)
+        if (element instanceof BpmnPoolElementModel) {
+            if (element.role === BPMN_ROLE.pool)
+                pools.push(element);
+            else
+                roleless.push(element);
+        }
+        else if (element instanceof BpmnNodeElementModel) {
+            if (element.role === BPMN_ROLE_OF_KIND[element.kind])
+                nodes.push(element);
+            else
+                roleless.push(element);
+        }
+        else if (element instanceof ConnectorElementModel) {
             connectors.push(element);
+        }
+        else {
+            roleless.push(element);
+        }
     }
-    return { pools, nodes, connectors };
+    // Against the pools that are actually WRITTEN: "inside the pool" has to mean
+    // inside a pool the file has, or the sentence names a perimeter the reader of
+    // the `.bpmn` cannot see. `bpmnPoolOf` is the same whole-containment test the
+    // audit and the serializer use, so what is reported left out is what the rest
+    // of the framework agrees is in there.
+    const legend = legendMemberIds(elements);
+    const leftOut = roleless.filter(element => !legend.has(element.id) &&
+        bpmnPoolOf(pools, element.elementBound) !== null).length;
+    return { pools, nodes, connectors, ...(leftOut > 0 ? { leftOut } : {}) };
 }
 /**
  * A name a file system will accept, minus the extension.
@@ -115,7 +208,18 @@ const runBpmnXmlExport = (elements, context) => {
         text,
         filename: `${name}${BPMN_XML_EXTENSION}`,
         mime: BPMN_XML_MIME,
-        ...(warnings.length > 0 ? { warnings } : {}),
+        // `InterchangeExportResult.warnings` is `readonly string[]` — a seam this
+        // capability shares with every other format and does not own — so each
+        // KEYED warning (`BpmnExportWarning`, `export.ts`) is resolved to its
+        // English fallback here. This adapter is `std`-free like the exporter it
+        // wraps (P3), so it cannot ask a host's catalogue either; the translated
+        // command path is `exportBpmnXmlFile` (`actions.ts`), which reads the
+        // structured warnings directly instead of going through this capability.
+        ...(warnings.length > 0
+            ? {
+                warnings: warnings.map(w => fillPlaceholders(w.fallback, w.params)),
+            }
+            : {}),
     };
 };
 /** `bpmn:bpmn:export` — the registry's first capability. */