@peter.prib/renderengine 0.13.0 → 0.15.0

package/src/charting/charts/TreemapChart.js

@@ -5,18 +5,22 @@ import { HierarchyChart } from './HierarchyChart.js';
 /**
  * TreemapChart — rectangles nested/sized proportional to value (squarified
  * layout), the standard chart for "composition of a whole across a hierarchy".
+ * Supports breadcrumb drill-down.
  */
 export class TreemapChart extends HierarchyChart {
     static chartType = 'treemap';
 
     _render() {
-        const data = this.data;
-        const options = this.options;
+        const data = this._activeData();
+        const options = this.options || {};
         const box = ChartBox.fromRenderer(this.renderer);
-        const { x = box.x, y = box.y, width = box.width, height = box.height, title } = options;
-        const plotBox = { x, y, width, height };
+        let { x = box.x, y = box.y, width = box.width, height = box.height, title } = options;
 
-        new ChartLabels({ title }).draw(this.renderer, plotBox);
+        new ChartLabels({ title }).draw(this.renderer, { x, y, width, height });
+
+        const crumbH = this._drawBreadcrumbs(this.renderer, { x, y, width });
+        y += crumbH;
+        height -= crumbH;
 
         const layout = Hierarchy.treemapLayout(data, x, y, width, height, 0, null, TreemapChart.HEADER_H);
         const textAnchor = this.renderer.centerTextAnchor;
@@ -27,20 +31,36 @@ export class TreemapChart extends HierarchyChart {
             const textColor = this._textColorForNode(topAncestor, depth);
 
             if (isLeaf) {
-                this.renderer.rect(rx, ry, Math.max(0, rw), Math.max(0, rh), color, { color: '#fff', width: 1 }, {
+                this._datum(this.renderer.rect(rx, ry, Math.max(0, rw), Math.max(0, rh), color, { color: '#fff', width: 1 }, {
                     tooltip: `${node.label}: ${this._formatNodeValue(node)}`,
-                });
+                }), { label: node.label });
                 if (rw > 30 && rh > 14) {
-                    this.renderer.text(node.label, rx + rw / 2, ry + rh / 2, {
+                    const showVals = options.showValues && rh > 28;
+                    const valText = typeof options.format === 'function' ? options.format(node.value) : this._formatNodeValue(node);
+                    this.renderer.text(node.label, rx + rw / 2, ry + (showVals ? rh / 2 - 6 : rh / 2), {
                         textAnchor, verticalAlign: 'middle', fontSize: '10px', fill: textColor, 'pointer-events': 'none',
                     });
+                    if (showVals) {
+                        this.renderer.text(valText, rx + rw / 2, ry + rh / 2 + 6, {
+                            textAnchor, verticalAlign: 'middle', fontSize: '9px', fill: textColor, opacity: 0.9, 'pointer-events': 'none',
+                        });
+                    }
                 }
             } else {
                 const headerH = Math.min(rh, TreemapChart.HEADER_H);
                 this.renderer.rect(rx, ry, Math.max(0, rw), Math.max(0, rh), 'rgba(0,0,0,0.03)', { color: '#ddd', width: 1 });
-                this.renderer.rect(rx, ry, Math.max(0, rw), headerH, color, null, {
-                    tooltip: `${node.label}: ${this._formatNodeValue(node)}`,
-                });
+                const headerRect = this._datum(this.renderer.rect(rx, ry, Math.max(0, rw), headerH, color, null, {
+                    cursor: options.drilldown !== false ? 'pointer' : 'default',
+                    tooltip: `${node.label}: ${this._formatNodeValue(node)} (Click to drill down)`,
+                }), { label: node.label });
+
+                if (options.drilldown !== false && typeof headerRect?.addEventListener === 'function') {
+                    headerRect.addEventListener('click', (e) => {
+                        e.stopPropagation();
+                        this.drillTo(node);
+                    });
+                }
+
                 if (rw > 30) {
                     this.renderer.text(node.label, rx + 4, ry + headerH / 2, {
                         textAnchor: 'start', verticalAlign: 'middle', fontSize: '9px', fontWeight: 'bold', fill: textColor, 'pointer-events': 'none',

package/src/charting/charts/ViolinChart.js

@@ -18,6 +18,24 @@ export class ViolinChart extends GroupedDistributionChart {
         const color = this._palette.colorAt(i);
         const curve = Statistics.kernelDensityEstimate(d.values, { min: this._domain.vMin, max: this._domain.vMax });
         const maxDensity = Math.max(...curve.map(p => p.density)) || 1;
+
+        if (this._isHorizontal()) {
+            const cy = cx;
+            const slotHeight = slotWidth;
+            const halfHeight = slotHeight * 0.4;
+            const topPts = curve.map(p => ({ px: this._toX(p.x), py: cy - (p.density / maxDensity) * halfHeight }));
+            const bottomPts = curve.map(p => ({ px: this._toX(p.x), py: cy + (p.density / maxDensity) * halfHeight }));
+            const path = 'M' + topPts.map(p => `${p.px},${p.py}`).join(' L')
+                + ' L' + [...bottomPts].reverse().map(p => `${p.px},${p.py}`).join(' L') + ' Z';
+            this._datum(this.renderer.path(path, color, { color: '#333', width: 1 }, {
+                tooltip: `${d.label}: n=${d.values.length}`,
+            }), { label: d.label, series: d.label });
+
+            const median = Statistics.quantile([...d.values].sort((a, b) => a - b), 0.5);
+            this.renderer.path(`M${this._toX(median)},${cy - halfHeight} L${this._toX(median)},${cy + halfHeight}`, 'none', { color: '#fff', width: 2 });
+            return;
+        }
+
         const halfWidth = slotWidth * 0.4;
 
         // Mirrored silhouette: right edge low-to-high value, then left
@@ -27,9 +45,9 @@ export class ViolinChart extends GroupedDistributionChart {
         const leftPts = curve.map(p => ({ px: cx - (p.density / maxDensity) * halfWidth, py: this._toY(p.x) }));
         const path = 'M' + rightPts.map(p => `${p.px},${p.py}`).join(' L')
             + ' L' + [...leftPts].reverse().map(p => `${p.px},${p.py}`).join(' L') + ' Z';
-        this.renderer.path(path, color, { color: '#333', width: 1 }, {
+        this._datum(this.renderer.path(path, color, { color: '#333', width: 1 }, {
             tooltip: `${d.label}: n=${d.values.length}`,
-        });
+        }), { label: d.label, series: d.label });
 
         const median = Statistics.quantile([...d.values].sort((a, b) => a - b), 0.5);
         this.renderer.path(`M${cx - halfWidth},${this._toY(median)} L${cx + halfWidth},${this._toY(median)}`, 'none', { color: '#fff', width: 2 });

package/src/charting/charts/WaterfallChart.js

@@ -58,9 +58,9 @@ export class WaterfallChart extends Chart {
             const top = toY(Math.max(band.from, band.to));
             const bottom = toY(Math.min(band.from, band.to));
             const color = band.isTotal ? totalColor : (band.to >= band.from ? upColor : downColor);
-            this.renderer.rect(barX, top, barWidth, Math.max(1, bottom - top), color, null, {
+            this._datum(this.renderer.rect(barX, top, barWidth, Math.max(1, bottom - top), color, null, {
                 tooltip: `${d.label}: ${band.isTotal ? band.to : (d.value >= 0 ? '+' : '') + d.value} (total: ${Axis.formatValue(band.to)})`,
-            });
+            }), { label: d.label });
             if (i % labelStep === 0) this.renderer.text(d.label, barX + barWidth / 2, y + height + 20, { textAnchor, fontSize: '10px' });
         });
     }

package/src/charting/charts/WordCloudChart.js

@@ -66,10 +66,10 @@ export class WordCloudChart extends Chart {
             if (!pos) return; // Could not place; skip.
             placed.push({ x: pos.x, y: pos.y, w: box.w, h: box.h });
             const color = palette.colorAt(i);
-            this.renderer.text(d.text, pos.x, pos.y + fontSize * 0.35, {
+            this._datum(this.renderer.text(d.text, pos.x, pos.y + fontSize * 0.35, {
                 textAnchor, fontSize: `${fontSize}px`, fill: color, fontFamily,
                 tooltip: `${d.text}: ${d.value}`,
-            });
+            }), { label: d.text });
         });
     }
 

package/src/charting/datamodel/ArchimateDataLink.js

@@ -0,0 +1,70 @@
+/**
+ * ArchimateDataLink — connects data model concepts to ArchiMate model elements.
+ * Aligns with DMBOK2's Data Architecture and TOGAF/ArchiMate standards:
+ * - Conceptual concepts realise ArchiMate Business Objects (Business Layer)
+ * - Logical and physical entities realise ArchiMate Data Objects (Application Layer) or Artifacts (Technology Layer)
+ * - Service domains link to ArchiMate Business Services or Application Services
+ */
+export class ArchimateDataLink {
+    /**
+     * @param {Object} spec
+     * @param {string} spec.dataModelEntityId - Entity id in DataModel
+     * @param {'conceptual'|'logical'|'physical'} [spec.level='conceptual']
+     * @param {string} spec.archimateElementId - ArchiMate element id
+     * @param {string} [spec.archimateType='business-object'] - 'business-object', 'data-object', 'artifact', etc.
+     * @param {string} [spec.archimateModelId]
+     * @param {string} [spec.notes]
+     */
+    constructor({
+        dataModelEntityId,
+        level = 'conceptual',
+        archimateElementId,
+        archimateType = 'business-object',
+        archimateModelId = null,
+        notes = '',
+    } = {}) {
+        if (!dataModelEntityId || !archimateElementId) {
+            throw new TypeError('ArchimateDataLink requires dataModelEntityId and archimateElementId');
+        }
+        this.dataModelEntityId = dataModelEntityId;
+        this.level = level;
+        this.archimateElementId = archimateElementId;
+        this.archimateType = archimateType;
+        this.archimateModelId = archimateModelId;
+        this.notes = notes;
+    }
+
+    /**
+     * Validates whether the ArchiMate type aligns with DMBOK2 layer expectations.
+     * Conceptual entities should realise Business Objects;
+     * Logical and physical entities should realise Data Objects or Artifacts.
+     * @returns {{ valid: boolean, recommendation?: string }}
+     */
+    validateLayerAlignment() {
+        if (this.level === 'conceptual' && this.archimateType !== 'business-object') {
+            return {
+                valid: false,
+                recommendation: 'Conceptual data model concepts should realise ArchiMate Business Objects in the Business layer.',
+            };
+        }
+        if ((this.level === 'logical' || this.level === 'physical') &&
+            !['data-object', 'artifact'].includes(this.archimateType)) {
+            return {
+                valid: false,
+                recommendation: `${this.level} data entities should realise ArchiMate Data Objects (Application layer) or Artifacts (Technology layer).`,
+            };
+        }
+        return { valid: true };
+    }
+
+    toJSON() {
+        return {
+            dataModelEntityId: this.dataModelEntityId,
+            level: this.level,
+            archimateElementId: this.archimateElementId,
+            archimateType: this.archimateType,
+            archimateModelId: this.archimateModelId,
+            notes: this.notes,
+        };
+    }
+}

package/src/charting/datamodel/DataLineage.js

@@ -0,0 +1,150 @@
+/**
+ * DataLineage — end-to-end data lineage and impact analysis across models and levels.
+ * Traces source-to-target provenance forward and backward (DMBOK2 Integration & Interoperability).
+ */
+export class DataLineage {
+    /**
+     * @param {Object} [options]
+     * @param {Array<ModelMapping>} [options.modelMappings]
+     * @param {Array<LevelMapping>} [options.levelMappings]
+     */
+    constructor({ modelMappings = [], levelMappings = [] } = {}) {
+        this.modelMappings = [...modelMappings];
+        this.levelMappings = [...levelMappings];
+    }
+
+    addModelMapping(mapping) {
+        this.modelMappings.push(mapping);
+    }
+
+    /**
+     * Trace upstream lineage of a target attribute back to its source attributes.
+     * Traverses multi-hop transformations across models.
+     * @param {string} targetEntityId
+     * @param {string} [targetAttribute]
+     * @returns {Array<Object>} Chain of lineage hops with transformations
+     */
+    traceLineage(targetEntityId, targetAttribute = null) {
+        const chain = [];
+        const visited = new Set();
+        const queue = [{ entity: targetEntityId, attribute: targetAttribute, depth: 0 }];
+
+        while (queue.length) {
+            const current = queue.shift();
+            const key = `${current.entity}:${current.attribute || '*'}`;
+            if (visited.has(key)) continue;
+            visited.add(key);
+
+            for (const map of this.modelMappings) {
+                for (const attrMap of map.attributeMappings) {
+                    if (attrMap.targetEntityId === current.entity &&
+                        (!current.attribute || attrMap.targetAttribute === current.attribute)) {
+                        const step = {
+                            sourceModel: map.sourceModel,
+                            targetModel: map.targetModel,
+                            sourceEntityId: attrMap.sourceEntityId,
+                            sourceAttribute: attrMap.sourceAttribute,
+                            targetEntityId: attrMap.targetEntityId,
+                            targetAttribute: attrMap.targetAttribute,
+                            transformation: attrMap.transformation,
+                            rule: attrMap.rule,
+                            depth: current.depth + 1,
+                        };
+                        chain.push(step);
+                        queue.push({
+                            entity: attrMap.sourceEntityId,
+                            attribute: attrMap.sourceAttribute,
+                            depth: current.depth + 1,
+                        });
+                    }
+                }
+            }
+        }
+        return chain;
+    }
+
+    /**
+     * Trace downstream impact of changing a source attribute forward to targets.
+     * Traverses multi-hop dependencies across models.
+     * @param {string} sourceEntityId
+     * @param {string} [sourceAttribute]
+     * @returns {Array<Object>} Affected downstream entities and attributes
+     */
+    traceImpact(sourceEntityId, sourceAttribute = null) {
+        const impacts = [];
+        const visited = new Set();
+        const queue = [{ entity: sourceEntityId, attribute: sourceAttribute, depth: 0 }];
+
+        while (queue.length) {
+            const current = queue.shift();
+            const key = `${current.entity}:${current.attribute || '*'}`;
+            if (visited.has(key)) continue;
+            visited.add(key);
+
+            for (const map of this.modelMappings) {
+                for (const attrMap of map.attributeMappings) {
+                    if (attrMap.sourceEntityId === current.entity &&
+                        (!current.attribute || attrMap.sourceAttribute === current.attribute)) {
+                        const step = {
+                            sourceModel: map.sourceModel,
+                            targetModel: map.targetModel,
+                            sourceEntityId: attrMap.sourceEntityId,
+                            sourceAttribute: attrMap.sourceAttribute,
+                            targetEntityId: attrMap.targetEntityId,
+                            targetAttribute: attrMap.targetAttribute,
+                            transformation: attrMap.transformation,
+                            rule: attrMap.rule,
+                            depth: current.depth + 1,
+                        };
+                        impacts.push(step);
+                        queue.push({
+                            entity: attrMap.targetEntityId,
+                            attribute: attrMap.targetAttribute,
+                            depth: current.depth + 1,
+                        });
+                    }
+                }
+            }
+        }
+        return impacts;
+    }
+
+    /**
+     * Generates a graph representation of the lineage suitable for diagramming or export.
+     * @returns {{ nodes: Array<{id: string, entity: string, attribute: string, model: string}>, edges: Array<{source: string, target: string, transformation: string, rule: string}> }}
+     */
+    toGraph() {
+        const nodes = new Map();
+        const edges = [];
+
+        for (const map of this.modelMappings) {
+            for (const m of map.attributeMappings) {
+                const srcId = `${map.sourceModel || 'source'}:${m.sourceEntityId}.${m.sourceAttribute}`;
+                const tgtId = `${map.targetModel || 'target'}:${m.targetEntityId}.${m.targetAttribute}`;
+                if (!nodes.has(srcId)) {
+                    nodes.set(srcId, {
+                        id: srcId,
+                        model: map.sourceModel || 'source',
+                        entity: m.sourceEntityId,
+                        attribute: m.sourceAttribute,
+                    });
+                }
+                if (!nodes.has(tgtId)) {
+                    nodes.set(tgtId, {
+                        id: tgtId,
+                        model: map.targetModel || 'target',
+                        entity: m.targetEntityId,
+                        attribute: m.targetAttribute,
+                    });
+                }
+                edges.push({
+                    source: srcId,
+                    target: tgtId,
+                    transformation: m.transformation,
+                    rule: m.rule,
+                });
+            }
+        }
+        return { nodes: [...nodes.values()], edges };
+    }
+}

package/src/charting/datamodel/DataModel.js

@@ -15,6 +15,9 @@ import { NamingStandard } from './naming/NamingStandard.js';
 import { ClassificationScheme } from './ClassificationScheme.js';
 import { ModelScorecard } from './scorecard/ModelScorecard.js';
 import { ServiceLandscape } from './ServiceLandscape.js';
+import { ModelMapping } from './ModelMapping.js';
+import { DataLineage } from './DataLineage.js';
+import { ArchimateDataLink } from './ArchimateDataLink.js';
 import {
     LevelEntitiesCompared, LevelRelationshipsCompared, MappingsCompared, ContextsCompared, PerspectivesCompared, DataTypesCompared,
 } from './DataModelCompared.js';
@@ -44,7 +47,7 @@ const LEVELS = Object.freeze(['conceptual', 'logical', 'physical']);
  */
 export class DataModel extends EditableModel {
     /** What a snapshot puts back (EditableModel#restore). */
-    static STATE = Object.freeze(['name', 'levels', 'mappings', 'mappingLayout', 'noteLayout', 'perspectives', 'contexts', 'dataTypes', 'namingStandard', 'classificationScheme', 'scorecard']);
+    static STATE = Object.freeze(['name', 'levels', 'mappings', 'mappingLayout', 'noteLayout', 'perspectives', 'contexts', 'dataTypes', 'namingStandard', 'classificationScheme', 'scorecard', 'modelMappings', 'archimateLinks']);
 
     /** The levels, outermost first. */
     static LEVELS = LEVELS;
@@ -149,6 +152,8 @@ export class DataModel extends EditableModel {
         this.classificationScheme = spec.classificationScheme instanceof ClassificationScheme ? spec.classificationScheme : new ClassificationScheme(spec.classificationScheme ?? {});
         /** What a reviewer said on the Scorecard, and the weights reviewed by (ModelScorecard), or null. */
         this.scorecard = spec.scorecard ? JSON.parse(JSON.stringify(spec.scorecard)) : null;
+        this.modelMappings = (spec.modelMappings ?? []).map(m => m instanceof ModelMapping ? m : new ModelMapping(m));
+        this.archimateLinks = (spec.archimateLinks ?? []).map(l => l instanceof ArchimateDataLink ? l : new ArchimateDataLink(l));
     }
 
     /** The model scored on the Data Model Scorecard (ModelScorecard). */
@@ -919,6 +924,83 @@ ${theirs}` : theirs;
             ...(this.namingStandard && { namingStandard: this.namingStandard.toJSON() }),
             ...(!this.classificationScheme.isDefault && { classificationScheme: this.classificationScheme.toJSON() }),
             ...(this.scorecard && { scorecard: JSON.parse(JSON.stringify(this.scorecard)) }),
+            ...(this.modelMappings.length && { modelMappings: this.modelMappings.map(m => m.toJSON()) }),
+            ...(this.archimateLinks.length && { archimateLinks: this.archimateLinks.map(l => l.toJSON()) }),
         };
     }
+
+    /** Add a cross-model mapping (DMBOK2 Integration & Interoperability). */
+    addModelMapping(mapping) {
+        const m = mapping instanceof ModelMapping ? mapping : new ModelMapping(mapping);
+        this.modelMappings.push(m);
+        return m;
+    }
+
+    /** End-to-end data lineage across models and internal level mappings (DMBOK2). */
+    crossModelLineage() {
+        return new DataLineage({ modelMappings: this.modelMappings, levelMappings: this.mappings });
+    }
+
+    /** Link a data model concept to an ArchiMate model element (DMBOK2 Data Architecture). */
+    linkToArchimate({ entityId, level = 'conceptual', archimateElementId, archimateType = 'business-object', archimateModelId = null, notes = '' }) {
+        this.unlinkFromArchimate(entityId, archimateElementId);
+        const link = new ArchimateDataLink({
+            dataModelEntityId: entityId,
+            level,
+            archimateElementId,
+            archimateType,
+            archimateModelId,
+            notes,
+        });
+        this.archimateLinks.push(link);
+        return link;
+    }
+
+    /** Remove a link to an ArchiMate element. */
+    unlinkFromArchimate(entityId, archimateElementId) {
+        this.archimateLinks = this.archimateLinks.filter(l => !(l.dataModelEntityId === entityId && l.archimateElementId === archimateElementId));
+    }
+
+    /** Links for a specific data model entity. */
+    archimateLinksFor(entityId) {
+        return this.archimateLinks.filter(l => l.dataModelEntityId === entityId);
+    }
+
+    /**
+     * Validate linked ArchiMate elements against an ArchiMate model (DMBOK2 Data Architecture).
+     * Verifies existence, element type and layer alignment.
+     * @param {ArchimateModel} archimateModel
+     * @returns {Array<{ link: ArchimateDataLink, valid: boolean, errors: Array<string> }>}
+     */
+    validateArchimateRealization(archimateModel) {
+        const results = [];
+        for (const link of this.archimateLinks) {
+            const errors = [];
+            const el = typeof archimateModel.getElement === 'function' ? archimateModel.getElement(link.archimateElementId) : null;
+            if (!el) {
+                errors.push(`Referenced ArchiMate element "${link.archimateElementId}" not found in ArchiMate model`);
+            } else if (el.type !== link.archimateType) {
+                errors.push(`Type mismatch: link specifies "${link.archimateType}" but model element is "${el.type}"`);
+            }
+            const layerCheck = link.validateLayerAlignment();
+            if (!layerCheck.valid) {
+                errors.push(layerCheck.recommendation);
+            }
+            results.push({ link, valid: errors.length === 0, errors });
+        }
+        return results;
+    }
+
+    /**
+     * Create an ArchiMate realization view on the given ArchiMate model showing the data architecture realization.
+     * @param {ArchimateModel} archimateModel
+     * @param {string} [viewTitle='Data Architecture Realization']
+     * @returns {ArchimateView}
+     */
+    createArchimateRealizationView(archimateModel, viewTitle = 'Data Architecture Realization') {
+        const elementIds = [...new Set(this.archimateLinks.map(l => l.archimateElementId))];
+        const view = archimateModel.createView(viewTitle);
+        view.elementIds = elementIds;
+        return view;
+    }
 }

package/src/charting/datamodel/ModelMapping.js

@@ -0,0 +1,87 @@
+/**
+ * ModelMapping — mappings between distinct data models (DMBOK2 Integration & Interoperability).
+ * Maps source model entities and attributes to target model entities and attributes,
+ * with transformation rules and expressions.
+ */
+export class ModelMapping {
+    /**
+     * @param {Object} spec
+     * @param {string} [spec.id]
+     * @param {string} [spec.name]
+     * @param {string} [spec.sourceModel] - Name or identifier of the source data model
+     * @param {string} [spec.targetModel] - Name or identifier of the target data model
+     * @param {Array<Object>} [spec.entityMappings]
+     * @param {Array<Object>} [spec.attributeMappings]
+     * @param {string} [spec.documentation]
+     */
+    constructor({
+        id,
+        name = 'Cross-Model Mapping',
+        sourceModel = '',
+        targetModel = '',
+        entityMappings = [],
+        attributeMappings = [],
+        documentation = '',
+    } = {}) {
+        this.id = id || `mapping-${Date.now().toString(36)}`;
+        this.name = name;
+        this.sourceModel = sourceModel;
+        this.targetModel = targetModel;
+        this.documentation = documentation;
+        this.entityMappings = entityMappings.map(e => ({ ...e }));
+        this.attributeMappings = attributeMappings.map(a => ({ ...a }));
+    }
+
+    /**
+     * Add an entity-level mapping between source and target entities.
+     */
+    addEntityMapping({ sourceEntityId, targetEntityId, name = '', description = '' } = {}) {
+        if (!sourceEntityId || !targetEntityId) {
+            throw new TypeError('Entity mapping requires sourceEntityId and targetEntityId');
+        }
+        if (!this.entityMappings.some(m => m.sourceEntityId === sourceEntityId && m.targetEntityId === targetEntityId)) {
+            this.entityMappings.push({ sourceEntityId, targetEntityId, name, description });
+        }
+    }
+
+    /**
+     * Add an attribute-level field mapping with transformation rule.
+     */
+    addAttributeMapping({ sourceEntityId, sourceAttribute, targetEntityId, targetAttribute, transformation = 'direct', rule = '' } = {}) {
+        if (!sourceEntityId || !sourceAttribute || !targetEntityId || !targetAttribute) {
+            throw new TypeError('Attribute mapping requires sourceEntityId, sourceAttribute, targetEntityId, and targetAttribute');
+        }
+        const existing = this.attributeMappings.find(m =>
+            m.sourceEntityId === sourceEntityId && m.sourceAttribute === sourceAttribute &&
+            m.targetEntityId === targetEntityId && m.targetAttribute === targetAttribute
+        );
+        if (existing) {
+            existing.transformation = transformation;
+            existing.rule = rule;
+        } else {
+            this.attributeMappings.push({ sourceEntityId, sourceAttribute, targetEntityId, targetAttribute, transformation, rule });
+        }
+    }
+
+    /** All attribute mappings targeting an entity. */
+    attributesTargeting(entityId) {
+        return this.attributeMappings.filter(m => m.targetEntityId === entityId);
+    }
+
+    /** All attribute mappings sourced from an entity. */
+    attributesSourcedFrom(entityId) {
+        return this.attributeMappings.filter(m => m.sourceEntityId === entityId);
+    }
+
+    toJSON() {
+        return {
+            id: this.id,
+            name: this.name,
+            sourceModel: this.sourceModel,
+            targetModel: this.targetModel,
+            documentation: this.documentation,
+            entityMappings: this.entityMappings.map(e => ({ ...e })),
+            attributeMappings: this.attributeMappings.map(a => ({ ...a })),
+        };
+    }
+}