yarramate 1.23.2 → 1.25.0

package/dist/adapters/visual/protocol-contract.d.ts

@@ -267,6 +267,23 @@ export interface VisualLayoutPositions {
         readonly y: number;
     };
 }
+/**
+ * The routes the canvas was drawing when a layout was saved (ADR 0147), keyed
+ * by relationship id: absolute canvas coordinates from the source end, both
+ * endpoints included, and where along the route the label sits. Saved WITH
+ * the positions, because a route is only right for the positions it was
+ * computed for: a reader who moved one subject keeps every other edge's
+ * route, and only the moved subject's edges fall back to a straight line.
+ */
+export interface VisualLayoutRoutes {
+    readonly [relationshipId: string]: {
+        readonly points: readonly {
+            readonly x: number;
+            readonly y: number;
+        }[];
+        readonly labelAt: number | null;
+    };
+}
 /**
  * A change to a projection document, staged rather than written (ADR 0103).
  *
@@ -332,6 +349,8 @@ export interface VisualLayoutSavePayload {
      */
     readonly folded?: readonly string[];
     readonly unfolded?: readonly string[];
+    /** The routes in force at save time (ADR 0147); absent when nothing was routed. */
+    readonly routes?: VisualLayoutRoutes;
 }
 /**
  * Terminal event payload. Every reason is the runtime's to choose: only it

package/dist/adapters/visual/session-server.js

@@ -456,15 +456,16 @@ export const startVisualServer = async (options) => {
     // like a broken saved view above — presentation state must never fail a
     // session.
     const layoutDir = resolve(options.cwd, ".yarramate/visual-layout");
-    const { layouts, folds } = (() => {
+    const { layouts, folds, routes } = (() => {
         const layouts = {};
         const folds = {};
+        const routes = {};
         let entries;
         try {
             entries = readdirSync(layoutDir);
         }
         catch {
-            return { layouts, folds };
+            return { layouts, folds, routes };
         }
         for (const entry of entries) {
             if (extname(entry) !== ".yaml" && extname(entry) !== ".yml")
@@ -476,6 +477,10 @@ export const startVisualServer = async (options) => {
                     continue;
                 const sidecar = parsed;
                 layouts[sidecar.projectionId] = sidecar.positions;
+                // The routes the canvas was drawing when it saved (ADR 0147). A
+                // sidecar written before them says nothing, and the layout recomputes.
+                if (sidecar.routes !== undefined)
+                    routes[sidecar.projectionId] = sidecar.routes;
                 // A sidecar written before #473 has neither list, and says nothing
                 // about folding rather than saying "fold nothing" - the view's own
                 // default decides for it. Only a sidecar that STATES a fold overrides.
@@ -490,7 +495,7 @@ export const startVisualServer = async (options) => {
                 // Skipped sidecar: presentation state must never fail a session.
             }
         }
-        return { layouts, folds };
+        return { layouts, folds, routes };
     })();
     // `request.initialModel.graph` is the caller's compile (`buildVisualModelGraph`,
     // before invoking `yarramate-visual start`) and is only the fallback below:
@@ -505,6 +510,7 @@ export const startVisualServer = async (options) => {
         vocabulary: { conceptKinds: [], relationshipKinds: [] },
         layouts,
         ...(Object.keys(folds).length === 0 ? {} : { folds }),
+        ...(Object.keys(routes).length === 0 ? {} : { routes }),
         sourceDigests: request.initialModel.sourceDigests,
         // The request's model has no projections in it - `visual-model/v1` carries
         // a graph, not a workspace - so the fallback states nothing rather than
@@ -1424,7 +1430,7 @@ export const startVisualServer = async (options) => {
                 // never `git commit`ed. It never asks the agent anything, so it is
                 // answered here directly rather than through the pending queue a
                 // poll would drain.
-                const { projectionId, positions, folded, unfolded } = event.payload;
+                const { projectionId, positions, folded, unfolded, routes: savedRoutes } = event.payload;
                 if (!views.some((view) => view.id === projectionId)) {
                     sendFrame(socket, {
                         kind: "layout-save-result",
@@ -1446,10 +1452,16 @@ export const startVisualServer = async (options) => {
                     // sidecar written by one host is read by the other.
                     ...(folded === undefined ? {} : { folded }),
                     ...(unfolded === undefined ? {} : { unfolded }),
+                    // The routes in force, beside the positions they were computed
+                    // for (ADR 0147); a save with nothing routed writes none.
+                    ...(savedRoutes === undefined ? {} : { routes: savedRoutes }),
                 }), "utf8");
                 rendered = {
                     ...rendered,
                     layouts: { ...rendered.layouts, [projectionId]: positions },
+                    ...(savedRoutes === undefined
+                        ? {}
+                        : { routes: { ...rendered.routes, [projectionId]: savedRoutes } }),
                     ...(folded === undefined && unfolded === undefined
                         ? {}
                         : {

package/dist/adapters/visual/wire.d.ts

@@ -1,6 +1,6 @@
 import type { CanvasGraph } from '../../graph-projection.js';
 import type { PatternMembership, PatternVacancy } from '../../compiler.js';
-import type { VISUAL_PROTOCOL_VERSION, VisualApplyResultPayload, VisualAuthority, VisualBrowserInput, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFilterResultPayload, VisualFreezeReason, VisualKindOption, VisualPatternOption, VisualLayoutPositions, VisualLayoutSaveResultPayload, VisualResponse, VisualTerminationReason, VisualViewSummary } from './protocol-contract.js';
+import type { VISUAL_PROTOCOL_VERSION, VisualApplyResultPayload, VisualAuthority, VisualBrowserInput, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFilterResultPayload, VisualFreezeReason, VisualKindOption, VisualPatternOption, VisualLayoutPositions, VisualLayoutRoutes, VisualLayoutSaveResultPayload, VisualResponse, VisualTerminationReason, VisualViewSummary } from './protocol-contract.js';
 /**
  * Transport shapes the session server and the browser application both speak.
  *
@@ -77,6 +77,14 @@ export interface VisualRenderedModel {
             readonly unfolded: readonly string[];
         };
     };
+    /**
+     * The routes each saved layout was drawing (ADR 0147), keyed by projection
+     * id. A sibling of `layouts` for the reason `folds` is: a layout entry is
+     * positions, and widening it would reach every reader of it.
+     */
+    readonly routes?: {
+        readonly [projectionId: string]: VisualLayoutRoutes;
+    };
     /**
      * Which subject fills which slot of which instance (ADR 0131), and which
      * slots nothing fills (#447), forwarded so the browser can draw containment

package/dist/brief.js

@@ -1,4 +1,5 @@
 import { conceptKinds } from './profile.js';
+import { RELATIONSHIP_READING, humanizeKind } from './relationship-reading.js';
 const coreKindNames = new Map(conceptKinds.map(({ id, name }) => [id, name]));
 const motivationKindIds = new Set(conceptKinds
     .filter(({ layer }) => layer === 'motivation')
@@ -41,54 +42,32 @@ export const isDeclaredNonGoal = (kind, status, lineages) => {
     const core = coreLocalKind(kind, lineages);
     return core !== undefined && nonGoalKindIds.has(core);
 };
-const humanizeKind = (kind) => {
-    const local = kind.slice(kind.indexOf('#') + 1);
-    return local
-        .replaceAll(/([a-z0-9])([A-Z])/g, '$1 $2')
-        .replaceAll('-', ' ')
-        .toLowerCase();
-};
 const article = (reading) => /^[aeiou]/.test(reading) ? 'an' : 'a';
 const sentenceEnd = (text) => /[.!?]["')\]]*$/.test(text.trimEnd()) ? text.trimEnd() : `${text.trimEnd()}.`;
 const listPhrase = (items) => items.length <= 1
     ? (items[0] ?? '')
     : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
 // Phrase forms are the prose readings of each core relationship kind's
-// declared intent — the same table `next` reads for ordering, spoken
-// from the source's perspective.
+// declared intent - the same table `next` reads for ordering, spoken from
+// the source's perspective. The plain readings live in
+// `./relationship-reading.ts`, shared with the canvas's edge labels (ADR
+// 0147); only the two kinds whose reading depends on the relationship's own
+// fields are phrased here.
 const relationshipPhrase = (coreKind, fallbackKind, mode, content) => {
-    switch (coreKind) {
-        case 'serving':
-            return 'serves';
-        case 'access':
-            return mode === 'read'
-                ? 'reads'
-                : mode === 'write'
-                    ? 'writes'
-                    : mode === 'read-write'
-                        ? 'reads and writes'
-                        : 'accesses';
-        case 'realization':
-            return 'realizes';
-        case 'composition':
-            return 'comprises';
-        case 'aggregation':
-            return 'aggregates';
-        case 'assignment':
-            return 'is assigned to';
-        case 'triggering':
-            return 'triggers';
-        case 'flow':
-            return content === undefined ? 'flows to' : `sends ${content} to`;
-        case 'specialization':
-            return 'specializes';
-        case 'influence':
-            return 'influences';
-        case 'association':
-            return 'is associated with';
-        default:
-            return humanizeKind(fallbackKind);
+    if (coreKind === 'access') {
+        return mode === 'read'
+            ? 'reads'
+            : mode === 'write'
+                ? 'writes'
+                : mode === 'read-write'
+                    ? 'reads and writes'
+                    : 'accesses';
+    }
+    if (coreKind === 'flow') {
+        return content === undefined ? 'flows to' : `sends ${content} to`;
     }
+    const reading = coreKind === undefined ? undefined : RELATIONSHIP_READING[coreKind];
+    return reading ?? humanizeKind(fallbackKind);
 };
 const estimateTokens = (text) => Math.ceil(text.length / 4);
 export function renderBrief(result, profileContext, budgetTokens, 

package/dist/layout-mode.d.ts

@@ -0,0 +1,56 @@
+/**
+ * How a view arranges itself, kept in a module that imports nothing.
+ *
+ * Apart from `projection.ts` for the reason `./layout-direction.ts` gives: the
+ * browser needs the value and not only the type, and `projection.ts` drags Ajv
+ * and the projection schema in for one constant. `projection.ts` re-exports
+ * everything here.
+ *
+ * The four modes are a ladder; each keeps everything below it (ADR 0147).
+ *
+ * - `layered`: ELK places the nodes and cytoscape draws its own orthogonal
+ *   lines between them, through whatever happens to sit in the way. This is
+ *   what shipped before 1.24; measured on the ApertureX reference model, 127
+ *   of the Landscape's 206 drawn edges cut through a box that was not one of
+ *   their endpoints.
+ * - `routed`: ELK also routes every edge around the nodes and reserves room
+ *   for each label. Zero edges through boxes on every view measured.
+ * - `served-by`: routed, and serving, realization and specialization are
+ *   layered UPWARD, so the served, realized or general element sits above
+ *   what serves, realizes or specializes it, and the label reads down the
+ *   page as "served by". Only the layering turns; the arrowhead, which says
+ *   which end is which, keeps its ArchiMate form.
+ * - `bands`: served-by, and every element is pinned to its ArchiMate layer's
+ *   band, motivation at the top and physical at the bottom.
+ */
+export declare const LAYOUT_MODES: readonly ['layered', 'routed', 'served-by', 'bands'];
+export type LayoutMode = (typeof LAYOUT_MODES)[number];
+/**
+ * How a view lays out when it does not say. Served-by, because it is the
+ * mode that read correctly the first time anyone looked at real tiers: the
+ * plain top-down run put the system API above the experience API (ADR 0147).
+ * A view that wants the pre-1.24 picture declares `layout: layered`.
+ */
+export declare const DEFAULT_LAYOUT: LayoutMode;
+export declare const isLayoutMode: (value: unknown) => value is LayoutMode;
+/** Whether ELK's own routes are drawn, rather than cytoscape's straight lines. */
+export declare const routesEdges: (mode: LayoutMode) => boolean;
+/** Whether the upward kinds are layered target-above-source. */
+export declare const reversesForLayering: (mode: LayoutMode) => boolean;
+/** Whether every node is pinned to its ArchiMate layer's band. */
+export declare const partitionsByLayer: (mode: LayoutMode) => boolean;
+/**
+ * The kinds ArchiMate draws with the TARGET above the source: the served
+ * element above its server, the realized above its realizer, the general
+ * above its specialization. Reversed for layering only; the notation module
+ * still draws the arrowhead at the target.
+ */
+export declare const LAYERING_REVERSED_KINDS: ReadonlySet<string>;
+/**
+ * Each ArchiMate layer's band under `bands`, top to bottom. `composite` has no
+ * band of its own - a grouping holds members from any layer - and a subject
+ * with no layer floats free, so neither is listed: ELK partitions only what
+ * names a partition, and leaves the rest to the layering.
+ */
+export declare const LAYER_BAND: Readonly<Record<string, number>>;
+export declare const layerBandOf: (layer: string | null | undefined) => number | undefined;

package/dist/layout-mode.js

@@ -0,0 +1,67 @@
+/**
+ * How a view arranges itself, kept in a module that imports nothing.
+ *
+ * Apart from `projection.ts` for the reason `./layout-direction.ts` gives: the
+ * browser needs the value and not only the type, and `projection.ts` drags Ajv
+ * and the projection schema in for one constant. `projection.ts` re-exports
+ * everything here.
+ *
+ * The four modes are a ladder; each keeps everything below it (ADR 0147).
+ *
+ * - `layered`: ELK places the nodes and cytoscape draws its own orthogonal
+ *   lines between them, through whatever happens to sit in the way. This is
+ *   what shipped before 1.24; measured on the ApertureX reference model, 127
+ *   of the Landscape's 206 drawn edges cut through a box that was not one of
+ *   their endpoints.
+ * - `routed`: ELK also routes every edge around the nodes and reserves room
+ *   for each label. Zero edges through boxes on every view measured.
+ * - `served-by`: routed, and serving, realization and specialization are
+ *   layered UPWARD, so the served, realized or general element sits above
+ *   what serves, realizes or specializes it, and the label reads down the
+ *   page as "served by". Only the layering turns; the arrowhead, which says
+ *   which end is which, keeps its ArchiMate form.
+ * - `bands`: served-by, and every element is pinned to its ArchiMate layer's
+ *   band, motivation at the top and physical at the bottom.
+ */
+export const LAYOUT_MODES = ['layered', 'routed', 'served-by', 'bands'];
+/**
+ * How a view lays out when it does not say. Served-by, because it is the
+ * mode that read correctly the first time anyone looked at real tiers: the
+ * plain top-down run put the system API above the experience API (ADR 0147).
+ * A view that wants the pre-1.24 picture declares `layout: layered`.
+ */
+export const DEFAULT_LAYOUT = 'served-by';
+export const isLayoutMode = (value) => typeof value === 'string' && LAYOUT_MODES.includes(value);
+/** Whether ELK's own routes are drawn, rather than cytoscape's straight lines. */
+export const routesEdges = (mode) => mode !== 'layered';
+/** Whether the upward kinds are layered target-above-source. */
+export const reversesForLayering = (mode) => mode === 'served-by' || mode === 'bands';
+/** Whether every node is pinned to its ArchiMate layer's band. */
+export const partitionsByLayer = (mode) => mode === 'bands';
+/**
+ * The kinds ArchiMate draws with the TARGET above the source: the served
+ * element above its server, the realized above its realizer, the general
+ * above its specialization. Reversed for layering only; the notation module
+ * still draws the arrowhead at the target.
+ */
+export const LAYERING_REVERSED_KINDS = new Set([
+    'serving',
+    'realization',
+    'specialization',
+]);
+/**
+ * Each ArchiMate layer's band under `bands`, top to bottom. `composite` has no
+ * band of its own - a grouping holds members from any layer - and a subject
+ * with no layer floats free, so neither is listed: ELK partitions only what
+ * names a partition, and leaves the rest to the layering.
+ */
+export const LAYER_BAND = {
+    motivation: 0,
+    strategy: 1,
+    business: 2,
+    application: 3,
+    technology: 4,
+    physical: 5,
+    implementation: 6,
+};
+export const layerBandOf = (layer) => layer === null || layer === undefined ? undefined : LAYER_BAND[layer];

package/dist/notation/archimate.d.ts

@@ -55,7 +55,12 @@ export interface ConceptNotation extends ShapeMeta {
 }
 export declare const CONCEPT_NOTATION: readonly ConceptNotation[];
 export declare function conceptNotationOf(kindLabel: string): ConceptNotation | null;
-export declare function kindGlyphDataUriOf(kindLabel: string): string | null;
+/**
+ * The glyph as a data URI, drawn in `ink` - the notation's own by default, or
+ * the light stroke a dark ground needs (ADR 0148). The stroke is the only
+ * thing that varies; the strokes themselves are the notation's.
+ */
+export declare function kindGlyphDataUriOf(kindLabel: string, ink?: string): string | null;
 export interface ArrowNotation {
     readonly shape: 'none' | 'diamond' | 'triangle' | 'circle' | 'vee';
     readonly fill?: 'filled' | 'hollow';

package/dist/notation/archimate.js

@@ -38,10 +38,10 @@ export const ASPECT_SHAPES = {
 const KIND_SHAPE_OVERRIDES = {
     grouping: { borderStyle: 'dashed' },
 };
-function svg(body) {
+function svg(body, ink = INK) {
     return (`<svg xmlns="http://www.w3.org/2000/svg" width="${ICON_SIZE}" height="${ICON_SIZE}" ` +
         `viewBox="0 0 ${ICON_SIZE} ${ICON_SIZE}">` +
-        `<g fill="none" stroke="${INK}" stroke-width="1" stroke-linecap="round" stroke-linejoin="round">${body}</g>` +
+        `<g fill="none" stroke="${ink}" stroke-width="1" stroke-linecap="round" stroke-linejoin="round">${body}</g>` +
         `</svg>`);
 }
 function toDataUri(svgMarkup) {
@@ -205,9 +205,14 @@ const CONCEPT_NOTATION_BY_ID = Object.fromEntries(CONCEPT_NOTATION.map((row) =>
 export function conceptNotationOf(kindLabel) {
     return CONCEPT_NOTATION_BY_ID[kindLabel] ?? null;
 }
-export function kindGlyphDataUriOf(kindLabel) {
+/**
+ * The glyph as a data URI, drawn in `ink` - the notation's own by default, or
+ * the light stroke a dark ground needs (ADR 0148). The stroke is the only
+ * thing that varies; the strokes themselves are the notation's.
+ */
+export function kindGlyphDataUriOf(kindLabel, ink = INK) {
     const glyph = CONCEPT_NOTATION_BY_ID[kindLabel]?.glyph;
-    return glyph == null ? null : toDataUri(svg(glyph));
+    return glyph == null ? null : toDataUri(svg(glyph, ink));
 }
 // The 11 rows from `graph-canvas.tsx`'s ArchiMate edge selectors (Task 11).
 const RELATIONSHIP_STYLE = {

package/dist/projection.d.ts

@@ -51,7 +51,13 @@ export interface ProjectionDefinition {
     readonly presentation?: {
         readonly title?: string;
         readonly description?: string;
-        readonly layout?: 'layered';
+        /**
+         * How this view arranges itself: `layered`, `routed`, `served-by` or
+         * `bands`, a ladder where each keeps everything below it (ADR 0147). A
+         * view that says nothing lays out `served-by`. The canvas offers the
+         * choice on screen and a save writes what is in force.
+         */
+        readonly layout?: LayoutMode;
         /**
          * Which way this view runs its layers. Read by the LikeC4 export for its
          * `autoLayout` and by the canvas for ELK's `elk.direction` (ADR 0121); a
@@ -78,6 +84,13 @@ export interface ProjectionDefinition {
         readonly showLifecycle?: boolean;
         readonly showEvidence?: boolean;
         readonly showOwnership?: boolean;
+        /**
+         * Whether an unnamed relationship is labelled with its reading - "serves",
+         * "served by", "realizes" - or left to its line style and arrowhead
+         * (ADR 0147). A named relationship keeps its name either way. On when
+         * absent, which is what shipped.
+         */
+        readonly showKindLabels?: boolean;
         /**
          * The folder this view files itself under in an editor's rail: a label the
          * author declares, nested with `/`, never the directory the projection
@@ -116,6 +129,12 @@ import { type FoldMembership } from './fold-tree.js';
  */
 export { DEFAULT_DIRECTION, type LayoutDirection } from './layout-direction.js';
 import type { LayoutDirection } from './layout-direction.js';
+/**
+ * How a view arranges itself, and the default. Same split, same terms
+ * (ADR 0147).
+ */
+export { DEFAULT_LAYOUT, LAYOUT_MODES, type LayoutMode } from './layout-mode.js';
+import type { LayoutMode } from './layout-mode.js';
 export type ProjectionQuery = ProjectionDefinition['query'];
 export interface ProjectionResult {
     readonly format: 'yarramate/projection-result/v1';

package/dist/projection.js

@@ -23,6 +23,11 @@ import { kindLabelOf } from './kind-label.js';
  * nesting vocabulary above, and re-exported here on the same terms (ADR 0121).
  */
 export { DEFAULT_DIRECTION } from './layout-direction.js';
+/**
+ * How a view arranges itself, and the default. Same split, same terms
+ * (ADR 0147).
+ */
+export { DEFAULT_LAYOUT, LAYOUT_MODES } from './layout-mode.js';
 import { validateProjection } from './schema-validation.js';
 export function loadProjection(source) {
     const loaded = loadSourceDocument(source, validateProjection, 'Projection');
@@ -66,6 +71,7 @@ export function canonicalProjection(projection) {
                     ...(presentation.showLifecycle === undefined ? {} : { showLifecycle: presentation.showLifecycle }),
                     ...(presentation.showEvidence === undefined ? {} : { showEvidence: presentation.showEvidence }),
                     ...(presentation.showOwnership === undefined ? {} : { showOwnership: presentation.showOwnership }),
+                    ...(presentation.showKindLabels === undefined ? {} : { showKindLabels: presentation.showKindLabels }),
                     ...(presentation.notation === undefined ? {} : { notation: presentation.notation }),
                 },
             }),
@@ -631,6 +637,9 @@ export function evaluateProjection(graph, projection, profileContext, membership
                     ...(projection.presentation.showOwnership === undefined
                         ? {}
                         : { showOwnership: projection.presentation.showOwnership }),
+                    ...(projection.presentation.showKindLabels === undefined
+                        ? {}
+                        : { showKindLabels: projection.presentation.showKindLabels }),
                     ...(projection.presentation.notation === undefined
                         ? {}
                         : { notation: projection.presentation.notation }),

package/dist/relationship-reading.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How a relationship reads as prose, kept in a module that imports nothing.
+ *
+ * One table for the brief and the canvas (ADR 0147). The brief has said
+ * "System API serves Process API" since it existed, and an edge label reading
+ * `serving` beside it was the same fact in a different voice. Every phrase
+ * here is spoken from the SOURCE: "a serves b".
+ *
+ * A canvas that layers the served element above what serves it reads the same
+ * edge from the other end, "b served by a", so the three kinds that turn for
+ * layering (`LAYERING_REVERSED_KINDS` in `./layout-mode.ts`) also carry a
+ * passive reading. Nothing else does: "b accessed by a" is not how anyone
+ * reads an access.
+ */
+export declare const RELATIONSHIP_READING: Readonly<Record<string, string>>;
+export declare const REVERSED_READING: Readonly<Record<string, string>>;
+/**
+ * `acme/p@1#applicationComponent` reads "application component" and
+ * `data-object` reads "data object": the last resort for a kind the table does
+ * not know, which is every extension kind.
+ */
+export declare const humanizeKind: (kind: string) => string;
+/**
+ * The reading of one relationship kind. `reversed` asks for the passive form
+ * and gets it only where one exists; a kind with no passive reading keeps its
+ * active one, so a caller can pass the layering's answer straight through.
+ */
+export declare const relationshipReading: (coreKind: string, reversed?: boolean) => string;

package/dist/relationship-reading.js

@@ -0,0 +1,52 @@
+/**
+ * How a relationship reads as prose, kept in a module that imports nothing.
+ *
+ * One table for the brief and the canvas (ADR 0147). The brief has said
+ * "System API serves Process API" since it existed, and an edge label reading
+ * `serving` beside it was the same fact in a different voice. Every phrase
+ * here is spoken from the SOURCE: "a serves b".
+ *
+ * A canvas that layers the served element above what serves it reads the same
+ * edge from the other end, "b served by a", so the three kinds that turn for
+ * layering (`LAYERING_REVERSED_KINDS` in `./layout-mode.ts`) also carry a
+ * passive reading. Nothing else does: "b accessed by a" is not how anyone
+ * reads an access.
+ */
+export const RELATIONSHIP_READING = {
+    serving: 'serves',
+    access: 'accesses',
+    realization: 'realizes',
+    composition: 'comprises',
+    aggregation: 'aggregates',
+    assignment: 'is assigned to',
+    triggering: 'triggers',
+    flow: 'flows to',
+    specialization: 'specializes',
+    influence: 'influences',
+    association: 'is associated with',
+};
+export const REVERSED_READING = {
+    serving: 'served by',
+    realization: 'realized by',
+    specialization: 'specialized by',
+};
+/**
+ * `acme/p@1#applicationComponent` reads "application component" and
+ * `data-object` reads "data object": the last resort for a kind the table does
+ * not know, which is every extension kind.
+ */
+export const humanizeKind = (kind) => {
+    const local = kind.slice(kind.indexOf('#') + 1);
+    return local
+        .replaceAll(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replaceAll('-', ' ')
+        .toLowerCase();
+};
+/**
+ * The reading of one relationship kind. `reversed` asks for the passive form
+ * and gets it only where one exists; a kind with no passive reading keeps its
+ * active one, so a caller can pass the layering's answer straight through.
+ */
+export const relationshipReading = (coreKind, reversed = false) => (reversed ? REVERSED_READING[coreKind] : undefined) ??
+    RELATIONSHIP_READING[coreKind] ??
+    humanizeKind(coreKind);