@graph-ir/core 0.2.0 → 0.2.1

package/dist/validation/ir-validator.js

@@ -1,346 +1,533 @@
-/**
- * Graph-IR Validator
- *
- * Validates Graph-IR against schema and semantic rules:
- * 1. JSON Schema validation (structure)
- * 2. ID uniqueness
- * 3. Reference validity (edges -> nodes, ports)
- * 4. Cycle detection in hierarchy
- * 5. Semantic warnings (orphans, self-loops)
- */
-import { Ajv } from 'ajv';
-// Import schema - will be loaded at runtime
+import Ajv2020Import from 'ajv/dist/2020.js';
 import graphIRSchema from '../schemas/graph-ir.schema.json' with { type: 'json' };
-// Use draft-07 compatible schema by removing the $schema field at runtime
-const schema = { ...graphIRSchema };
-delete schema['$schema'];
+const retiredFields = new Set(['routingPoints', 'algorithmOptions', 'shape']);
+const Ajv2020 = Ajv2020Import.default ??
+    Ajv2020Import;
 export class IRValidator {
     options;
-    ajv;
     schemaValidator;
     constructor(options = {}) {
         this.options = options;
-        this.ajv = new Ajv({ allErrors: true, verbose: true, strict: false });
-        // Add formats manually since ESM import is problematic
-        this.addDateTimeFormat();
-        this.schemaValidator = this.ajv.compile(schema);
-    }
-    addDateTimeFormat() {
-        this.ajv.addFormat('date-time', {
-            type: 'string',
-            validate: (dateTimeString) => {
-                // ISO 8601 date-time format
-                const dateTimeRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?$/;
-                return dateTimeRegex.test(dateTimeString);
-            },
+        const ajv = new Ajv2020({
+            allErrors: true,
+            strict: false,
+            strictNumbers: true,
+            validateFormats: false,
         });
+        this.schemaValidator = ajv.compile(graphIRSchema);
     }
-    /**
-     * Validate from JSON string
-     */
     validateFromString(jsonString) {
-        // Parse JSON
-        let ir;
+        let value;
         try {
-            ir = JSON.parse(jsonString);
+            value = JSON.parse(jsonString);
         }
-        catch (e) {
-            return {
-                valid: false,
-                errors: [
-                    {
-                        code: 'INVALID_JSON',
-                        path: '$',
-                        message: `Invalid JSON: ${e instanceof Error ? e.message : 'Parse error'}`,
-                        severity: 'error',
-                    },
-                ],
-                warnings: [],
-                stats: { nodes: 0, edges: 0 },
-            };
+        catch (error) {
+            return this.result([
+                this.error('INVALID_JSON', '', `Invalid JSON: ${error instanceof Error ? error.message : 'Parse error'}`),
+            ]);
         }
-        return this.validate(ir);
+        return this.validate(value);
     }
-    /**
-     * Validate a Graph-IR object
-     */
-    validate(ir) {
+    validate(value) {
+        const mode = this.resolveMode();
+        if (typeof mode !== 'string')
+            return this.result([mode]);
         const errors = [];
         const warnings = [];
-        // 1. Schema validation
-        if (!this.options.skipSchema) {
-            const schemaErrors = this.validateSchema(ir);
-            if (schemaErrors.length > 0) {
-                // Schema errors are fatal - return early
-                return {
-                    valid: false,
-                    errors: schemaErrors,
-                    warnings: [],
-                    stats: { nodes: 0, edges: 0 },
-                };
+        const graph = this.isGraphShape(value) ? value : undefined;
+        const hierarchyCycle = graph ? this.findHierarchyCycle(graph.nodes) : undefined;
+        if (hierarchyCycle) {
+            return this.result([
+                this.error('CYCLIC_HIERARCHY', hierarchyCycle, 'Node children must form an acyclic containment tree'),
+            ]);
+        }
+        if (mode !== 'semantic') {
+            this.schemaValidator(value);
+            errors.push(...this.normalizeSchemaErrors(this.schemaValidator.errors ?? []));
+        }
+        if (mode !== 'schema' && graph) {
+            this.validateSemantic(graph, errors, warnings);
+        }
+        const uniqueErrors = this.dedupe(errors);
+        const uniqueWarnings = this.dedupe(warnings);
+        const finalErrors = this.options.strict
+            ? [...uniqueErrors, ...uniqueWarnings]
+            : uniqueErrors;
+        const finalWarnings = this.options.strict ? [] : uniqueWarnings;
+        return {
+            valid: finalErrors.length === 0,
+            errors: finalErrors,
+            warnings: finalWarnings,
+            stats: {
+                nodes: graph ? this.collectNodes(graph.nodes).length : 0,
+                edges: graph?.edges.length ?? 0,
+            },
+        };
+    }
+    resolveMode() {
+        const hasSkipSchema = Object.hasOwn(this.options, 'skipSchema');
+        const hasSkipSemantic = Object.hasOwn(this.options, 'skipSemantic');
+        if (this.options.mode && (hasSkipSchema || hasSkipSemantic)) {
+            return this.error('INVALID_VALIDATION_OPTIONS', '', 'Explicit mode cannot be combined with legacy skip flags');
+        }
+        if (this.options.skipSchema && this.options.skipSemantic) {
+            return this.error('INVALID_VALIDATION_OPTIONS', '', 'skipSchema and skipSemantic cannot both be true');
+        }
+        if (this.options.mode)
+            return this.options.mode;
+        if (this.options.skipSchema)
+            return 'semantic';
+        if (this.options.skipSemantic)
+            return 'schema';
+        return 'full';
+    }
+    normalizeSchemaErrors(schemaErrors) {
+        const errors = [];
+        for (const schemaError of schemaErrors) {
+            let path = schemaError.instancePath;
+            let code = 'SCHEMA_VIOLATION';
+            if (schemaError.keyword === 'required') {
+                const missing = String(schemaError.params.missingProperty);
+                path = this.joinPointer(path, missing);
+                if (path === '/version')
+                    code = 'UNSUPPORTED_SCHEMA_VERSION';
+                if (missing === 'position' && this.pathHasPinnedNode(path)) {
+                    code = 'PIN_REQUIRES_POSITION';
+                }
+            }
+            else if (schemaError.keyword === 'additionalProperties') {
+                const property = String(schemaError.params.additionalProperty);
+                path = this.joinPointer(path, property);
+                if (retiredFields.has(property))
+                    code = 'RETIRED_FIELD';
             }
+            else if (path === '/version' && schemaError.keyword === 'const') {
+                code = 'UNSUPPORTED_SCHEMA_VERSION';
+            }
+            else if (path.endsWith('/labelPlacement/offset') ||
+                path.endsWith('/labelPlacement/at')) {
+                code = 'INVALID_LABEL_PLACEMENT';
+            }
+            else if (/^\/constraints\/\d+\/subjects$/.test(path) &&
+                (schemaError.keyword === 'minItems' || schemaError.keyword === 'uniqueItems')) {
+                code = 'INVALID_ARRANGEMENT';
+            }
+            errors.push(this.error(code, path, schemaError.message ?? 'Schema violation'));
         }
-        // At this point, ir should be a valid GraphIR structure
-        const graphIR = ir;
-        // 2. Collect all nodes (including nested children)
-        const allNodes = this.collectAllNodes(graphIR.nodes);
-        const nodeIds = new Map();
-        // 3. Check node ID uniqueness
-        allNodes.forEach(({ node, path }) => {
-            if (nodeIds.has(node.id)) {
-                errors.push({
-                    code: 'DUPLICATE_NODE_ID',
-                    path: `${path}.id`,
-                    message: `Duplicate node ID: "${node.id}"`,
-                    severity: 'error',
-                });
+        return errors;
+    }
+    pathHasPinnedNode(positionPath) {
+        return /^\/nodes(?:\/\d+\/children)*\/\d+\/position$/.test(positionPath);
+    }
+    validateSemantic(graph, errors, warnings) {
+        const entries = this.collectNodes(graph.nodes);
+        const nodeById = new Map();
+        for (const entry of entries) {
+            if (typeof entry.node.id === 'string') {
+                const existing = nodeById.get(entry.node.id);
+                if (existing) {
+                    errors.push(this.error('DUPLICATE_NODE_ID', `${entry.path}/id`, `Duplicate node ID: "${entry.node.id}"`));
+                }
+                else {
+                    nodeById.set(entry.node.id, entry);
+                }
             }
-            else {
-                nodeIds.set(node.id, { node, path });
+            if (entry.parentId === undefined && entry.node.parent !== undefined) {
+                errors.push(this.error('INVALID_ROOT_PARENT', `${entry.path}/parent`, `Root node "${entry.node.id}" must not declare parent`));
             }
-        });
-        // 4. Check edge ID uniqueness and references
+            else if (entry.parentId !== undefined &&
+                entry.node.parent !== undefined &&
+                entry.node.parent !== entry.parentId) {
+                errors.push(this.error('INVALID_PARENT_REFERENCE', `${entry.path}/parent`, `Node "${entry.node.id}" parent must be "${entry.parentId}"`));
+            }
+            const ports = new Set();
+            const nodePorts = Array.isArray(entry.node.ports) ? entry.node.ports : [];
+            nodePorts.forEach((port, index) => {
+                if (!port || typeof port !== 'object')
+                    return;
+                if (ports.has(port.id)) {
+                    errors.push(this.error('DUPLICATE_PORT_ID', `${entry.path}/ports/${index}/id`, `Duplicate port ID "${port.id}" on node "${entry.node.id}"`));
+                }
+                ports.add(port.id);
+            });
+        }
         const edgeIds = new Set();
-        graphIR.edges.forEach((edge, index) => {
-            const path = `$.edges[${index}]`;
-            // Check edge ID uniqueness
+        graph.edges.forEach((edge, index) => {
+            if (!edge || typeof edge !== 'object')
+                return;
+            const path = `/edges/${index}`;
             if (edgeIds.has(edge.id)) {
-                errors.push({
-                    code: 'DUPLICATE_EDGE_ID',
-                    path: `${path}.id`,
-                    message: `Duplicate edge ID: "${edge.id}"`,
-                    severity: 'error',
-                });
+                errors.push(this.error('DUPLICATE_EDGE_ID', `${path}/id`, `Duplicate edge ID: "${edge.id}"`));
             }
             edgeIds.add(edge.id);
-            // Check source reference
-            if (!nodeIds.has(edge.source)) {
-                const suggestion = this.findSimilarId(edge.source, Array.from(nodeIds.keys()));
-                errors.push({
-                    code: 'INVALID_EDGE_SOURCE',
-                    path: `${path}.source`,
-                    message: `Edge "${edge.id}" references non-existent source node: "${edge.source}"`,
-                    severity: 'error',
-                    suggestion,
-                });
+            this.validateEdge(edge, path, nodeById, errors);
+        });
+        const constraints = Array.isArray(graph.constraints) ? graph.constraints : [];
+        this.validateConstraints(constraints, nodeById, errors);
+        this.validateDirectionalContradictions(constraints, nodeById, errors);
+        this.addWarnings(graph, entries, warnings);
+    }
+    validateEdge(edge, path, nodeById, errors) {
+        const source = typeof edge.source === 'string' ? nodeById.get(edge.source) : undefined;
+        const target = typeof edge.target === 'string' ? nodeById.get(edge.target) : undefined;
+        if (typeof edge.source === 'string' && !source) {
+            errors.push(this.error('INVALID_EDGE_SOURCE', `${path}/source`, `Edge "${edge.id}" references missing source "${edge.source}"`, this.findSimilarId(edge.source, [...nodeById.keys()])));
+        }
+        if (typeof edge.target === 'string' && !target) {
+            errors.push(this.error('INVALID_EDGE_TARGET', `${path}/target`, `Edge "${edge.id}" references missing target "${edge.target}"`, this.findSimilarId(edge.target, [...nodeById.keys()])));
+        }
+        if (edge.sourcePort && source && !this.hasPort(source.node, edge.sourcePort)) {
+            errors.push(this.error('INVALID_PORT_REFERENCE', `${path}/sourcePort`, `Missing source port "${edge.sourcePort}"`));
+        }
+        if (edge.targetPort && target && !this.hasPort(target.node, edge.targetPort)) {
+            errors.push(this.error('INVALID_PORT_REFERENCE', `${path}/targetPort`, `Missing target port "${edge.targetPort}"`));
+        }
+        const waypointIds = new Set();
+        const waypoints = Array.isArray(edge.routeIntent?.waypoints)
+            ? edge.routeIntent.waypoints
+            : [];
+        waypoints.forEach((waypoint, index) => {
+            if (!waypoint || typeof waypoint !== 'object')
+                return;
+            const waypointPath = `${path}/routeIntent/waypoints/${index}`;
+            if (waypointIds.has(waypoint.id)) {
+                errors.push(this.error('DUPLICATE_WAYPOINT_ID', `${waypointPath}/id`, `Duplicate waypoint ID "${waypoint.id}"`));
             }
-            // Check target reference
-            if (!nodeIds.has(edge.target)) {
-                const suggestion = this.findSimilarId(edge.target, Array.from(nodeIds.keys()));
-                errors.push({
-                    code: 'INVALID_EDGE_TARGET',
-                    path: `${path}.target`,
-                    message: `Edge "${edge.id}" references non-existent target node: "${edge.target}"`,
-                    severity: 'error',
-                    suggestion,
-                });
+            waypointIds.add(waypoint.id);
+            if (!waypoint.placement || typeof waypoint.placement !== 'object')
+                return;
+            if (waypoint.placement.kind !== 'relative')
+                return;
+            const anchor = waypoint.placement.anchor;
+            if (!anchor || typeof anchor !== 'object')
+                return;
+            if (anchor.kind === 'node' && !nodeById.has(anchor.nodeId)) {
+                errors.push(this.error('INVALID_ROUTE_NODE_REFERENCE', `${waypointPath}/placement/anchor/nodeId`, `Missing route anchor node "${anchor.nodeId}"`));
             }
-            // Check source port reference
-            if (edge.sourcePort && nodeIds.has(edge.source)) {
-                const sourceNode = nodeIds.get(edge.source).node;
-                if (!this.hasPort(sourceNode, edge.sourcePort)) {
-                    errors.push({
-                        code: 'INVALID_PORT_REFERENCE',
-                        path: `${path}.sourcePort`,
-                        message: `Edge "${edge.id}" references non-existent source port: "${edge.sourcePort}" on node "${edge.source}"`,
-                        severity: 'error',
-                    });
+            if (anchor.kind === 'port') {
+                const owner = nodeById.get(anchor.nodeId);
+                if (!owner) {
+                    errors.push(this.error('INVALID_ROUTE_NODE_REFERENCE', `${waypointPath}/placement/anchor/nodeId`, `Missing route anchor node "${anchor.nodeId}"`));
                 }
-            }
-            // Check target port reference
-            if (edge.targetPort && nodeIds.has(edge.target)) {
-                const targetNode = nodeIds.get(edge.target).node;
-                if (!this.hasPort(targetNode, edge.targetPort)) {
-                    errors.push({
-                        code: 'INVALID_PORT_REFERENCE',
-                        path: `${path}.targetPort`,
-                        message: `Edge "${edge.id}" references non-existent target port: "${edge.targetPort}" on node "${edge.target}"`,
-                        severity: 'error',
-                    });
+                else if (!this.hasPort(owner.node, anchor.portId)) {
+                    errors.push(this.error('INVALID_ROUTE_PORT_REFERENCE', `${waypointPath}/placement/anchor/portId`, `Missing route anchor port "${anchor.portId}"`));
                 }
             }
         });
-        // 5. Check for cycles in hierarchy
-        if (!this.options.skipSemantic) {
-            const cycleErrors = this.checkHierarchyCycles(graphIR.nodes);
-            errors.push(...cycleErrors);
-        }
-        // 6. Semantic warnings
-        if (!this.options.skipSemantic) {
-            // Check for self-loops
-            graphIR.edges.forEach((edge, index) => {
-                if (edge.source === edge.target) {
-                    warnings.push({
-                        code: 'SELF_LOOP_EDGE',
-                        path: `$.edges[${index}]`,
-                        message: `Edge "${edge.id}" connects node "${edge.source}" to itself`,
-                        severity: 'warning',
-                    });
+    }
+    validateConstraints(constraints, nodeById, errors) {
+        const ids = new Set();
+        constraints.forEach((constraint, index) => {
+            if (!constraint || typeof constraint !== 'object')
+                return;
+            const path = `/constraints/${index}`;
+            if (ids.has(constraint.id)) {
+                errors.push(this.error('DUPLICATE_CONSTRAINT_ID', `${path}/id`, `Duplicate constraint ID "${constraint.id}"`));
+            }
+            ids.add(constraint.id);
+            if (constraint.kind === 'arrangement' && Array.isArray(constraint.subjects)) {
+                const subjectIds = constraint.subjects
+                    .filter((subject) => subject && typeof subject === 'object')
+                    .map((subject) => subject.nodeId);
+                if (subjectIds.length < 2 || new Set(subjectIds).size !== subjectIds.length) {
+                    errors.push(this.error('INVALID_ARRANGEMENT', `${path}/subjects`, 'Arrangement requires at least two distinct node subjects'));
                 }
-            });
-            // Check for orphan nodes (nodes with no connections)
-            const connectedNodes = new Set();
-            graphIR.edges.forEach((edge) => {
-                connectedNodes.add(edge.source);
-                connectedNodes.add(edge.target);
-            });
-            allNodes.forEach(({ node, path }) => {
-                // Skip nodes that have children (compound nodes)
-                if (!node.children?.length && !connectedNodes.has(node.id)) {
-                    warnings.push({
-                        code: 'ORPHAN_NODE',
-                        path,
-                        message: `Node "${node.id}" has no connections`,
-                        severity: 'warning',
-                    });
+            }
+            const references = constraint.kind === 'arrangement'
+                ? (Array.isArray(constraint.subjects)
+                    ? constraint.subjects.map((subject, subjectIndex) => ({ subject, path: `${path}/subjects/${subjectIndex}/nodeId` }))
+                    : [])
+                : constraint.subject && typeof constraint.subject === 'object'
+                    ? [{ subject: constraint.subject, path: `${path}/subject/nodeId` }]
+                    : [];
+            if (constraint.kind === 'relative') {
+                if (constraint.target && typeof constraint.target === 'object') {
+                    references.push({ subject: constraint.target, path: `${path}/target/nodeId` });
                 }
-            });
-            // Check for orphan ports
-            const usedPorts = new Set();
-            graphIR.edges.forEach((edge) => {
-                if (edge.sourcePort)
-                    usedPorts.add(`${edge.source}:${edge.sourcePort}`);
-                if (edge.targetPort)
-                    usedPorts.add(`${edge.target}:${edge.targetPort}`);
-            });
-            allNodes.forEach(({ node, path }) => {
-                node.ports?.forEach((port, portIndex) => {
-                    const portKey = `${node.id}:${port.id}`;
-                    if (!usedPorts.has(portKey)) {
-                        warnings.push({
-                            code: 'ORPHAN_PORT',
-                            path: `${path}.ports[${portIndex}]`,
-                            message: `Port "${port.id}" on node "${node.id}" is never referenced`,
-                            severity: 'warning',
-                        });
-                    }
-                });
-            });
+                if (constraint.subject && typeof constraint.subject === 'object' &&
+                    constraint.target && typeof constraint.target === 'object' &&
+                    constraint.subject.nodeId === constraint.target.nodeId) {
+                    errors.push(this.error('SELF_RELATION', path, `Constraint "${constraint.id}" relates a node to itself`));
+                }
+            }
+            for (const reference of references) {
+                if (!reference.subject || typeof reference.subject !== 'object')
+                    continue;
+                if (!nodeById.has(reference.subject.nodeId)) {
+                    errors.push(this.error('INVALID_CONSTRAINT_REFERENCE', reference.path, `Missing constraint node "${reference.subject.nodeId}"`));
+                }
+            }
+            if (constraint.kind === 'boundary' &&
+                constraint.scope && typeof constraint.scope === 'object' &&
+                constraint.scope.kind === 'node' &&
+                constraint.subject && typeof constraint.subject === 'object') {
+                const subject = nodeById.get(constraint.subject.nodeId);
+                const scope = nodeById.get(constraint.scope.nodeId);
+                if (!scope) {
+                    errors.push(this.error('INVALID_CONSTRAINT_REFERENCE', `${path}/scope/nodeId`, `Missing boundary scope "${constraint.scope.nodeId}"`));
+                }
+                else if (!subject || !subject.ancestors.includes(scope.node.id)) {
+                    errors.push(this.error('INVALID_BOUNDARY_SCOPE', `${path}/scope/nodeId`, `Boundary scope "${scope.node.id}" is not an ancestor`));
+                }
+            }
+        });
+    }
+    validateDirectionalContradictions(constraints, nodeById, errors) {
+        const horizontal = [];
+        const vertical = [];
+        constraints.forEach((constraint, index) => {
+            if (!constraint || typeof constraint !== 'object')
+                return;
+            if ((constraint.strength ?? 'required') !== 'required')
+                return;
+            const path = `/constraints/${index}`;
+            if (constraint.kind === 'relative') {
+                this.addRelativeEdge(constraint, path, nodeById, horizontal, vertical);
+                this.checkPinnedRelation(constraint, path, nodeById, errors);
+            }
+            else if (constraint.kind === 'arrangement') {
+                if (!Array.isArray(constraint.subjects) ||
+                    constraint.subjects.length < 2 ||
+                    new Set(constraint.subjects.map((subject) => subject?.nodeId)).size !== constraint.subjects.length)
+                    return;
+                this.addArrangementEdges(constraint, path, nodeById, horizontal, vertical, errors);
+            }
+        });
+        for (const axisEdges of [horizontal, vertical]) {
+            const positiveInCycle = axisEdges.find((edge) => edge.weight > 0 && this.canReach(edge.to, edge.from, axisEdges));
+            if (positiveInCycle) {
+                errors.push(this.error('REQUIRED_CONTRADICTION', positiveInCycle.path, 'Required directional constraints contain a strictly positive cycle'));
+            }
         }
-        // Apply strict mode
-        const finalErrors = this.options.strict ? [...errors, ...warnings] : errors;
-        const finalWarnings = this.options.strict ? [] : warnings;
-        return {
-            valid: finalErrors.length === 0,
-            errors: finalErrors,
-            warnings: finalWarnings,
-            stats: {
-                nodes: allNodes.length,
-                edges: graphIR.edges.length,
-            },
-        };
     }
-    /**
-     * Validate against JSON Schema
-     */
-    validateSchema(ir) {
-        const valid = this.schemaValidator(ir);
-        if (valid)
-            return [];
-        const errors = [];
-        for (const error of this.schemaValidator.errors || []) {
-            errors.push({
-                code: 'SCHEMA_VIOLATION',
-                path: error.instancePath || '$',
-                message: error.message || 'Schema validation failed',
-                severity: 'error',
-            });
+    addRelativeEdge(constraint, path, nodes, horizontal, vertical) {
+        if (!constraint.subject || typeof constraint.subject !== 'object' ||
+            !constraint.target || typeof constraint.target !== 'object')
+            return;
+        const subject = nodes.get(constraint.subject.nodeId)?.node;
+        const target = nodes.get(constraint.target.nodeId)?.node;
+        if (!subject || !target)
+            return;
+        const gap = constraint.gap ?? 0;
+        if (constraint.relation === 'left-of') {
+            horizontal.push({ from: subject.id, to: target.id, weight: (subject.dimensions?.width ?? 0) + gap, path });
+        }
+        else if (constraint.relation === 'right-of') {
+            horizontal.push({ from: target.id, to: subject.id, weight: (target.dimensions?.width ?? 0) + gap, path });
+        }
+        else if (constraint.relation === 'above') {
+            vertical.push({ from: subject.id, to: target.id, weight: (subject.dimensions?.height ?? 0) + gap, path });
+        }
+        else {
+            vertical.push({ from: target.id, to: subject.id, weight: (target.dimensions?.height ?? 0) + gap, path });
         }
-        return errors;
     }
-    /**
-     * Collect all nodes including nested children
-     */
-    collectAllNodes(nodes, parentPath = '$.nodes') {
-        const result = [];
-        nodes.forEach((node, index) => {
-            const path = `${parentPath}[${index}]`;
-            result.push({ node, path });
-            if (node.children?.length) {
-                result.push(...this.collectAllNodes(node.children, `${path}.children`));
-            }
-        });
-        return result;
+    addArrangementEdges(constraint, path, nodes, horizontal, vertical, errors) {
+        for (let index = 0; index < constraint.subjects.length - 1; index += 1) {
+            const firstRef = constraint.subjects[index];
+            const secondRef = constraint.subjects[index + 1];
+            if (!firstRef || typeof firstRef !== 'object' ||
+                !secondRef || typeof secondRef !== 'object')
+                continue;
+            const first = nodes.get(firstRef.nodeId)?.node;
+            const second = nodes.get(secondRef.nodeId)?.node;
+            if (!first || !second)
+                continue;
+            const reverse = (constraint.direction ?? 'forward') === 'reverse';
+            const from = reverse ? second : first;
+            const to = reverse ? first : second;
+            const dimension = constraint.axis === 'row'
+                ? from.dimensions?.width ?? 0
+                : from.dimensions?.height ?? 0;
+            const edge = { from: from.id, to: to.id, weight: dimension + (constraint.gap ?? 0), path };
+            (constraint.axis === 'row' ? horizontal : vertical).push(edge);
+            this.checkPinnedPair(from, to, constraint.axis === 'row' ? 'left-of' : 'above', constraint.gap ?? 0, constraint.alignment ?? 'center', path, nodes, errors);
+        }
     }
-    /**
-     * Check if a node has a port with the given ID
-     */
-    hasPort(node, portId) {
-        return node.ports?.some((p) => p.id === portId) ?? false;
+    checkPinnedRelation(constraint, path, nodes, errors) {
+        if (!constraint.subject || typeof constraint.subject !== 'object' ||
+            !constraint.target || typeof constraint.target !== 'object')
+            return;
+        const subject = nodes.get(constraint.subject.nodeId)?.node;
+        const target = nodes.get(constraint.target.nodeId)?.node;
+        if (!subject || !target)
+            return;
+        this.checkPinnedPair(subject, target, constraint.relation, constraint.gap ?? 0, constraint.alignment ?? 'center', path, nodes, errors);
     }
-    /**
-     * Check for cycles in the node hierarchy
-     */
-    checkHierarchyCycles(nodes) {
-        const errors = [];
+    checkPinnedPair(subject, target, relation, gap, alignment, path, nodes, errors) {
+        const subjectEntry = nodes.get(subject.id);
+        const targetEntry = nodes.get(target.id);
+        if (!subject.pinned || !target.pinned ||
+            !subject.position || !target.position ||
+            !subject.dimensions || !target.dimensions ||
+            subjectEntry?.parentId !== targetEntry?.parentId)
+            return;
+        const s = { ...subject.position, ...subject.dimensions };
+        const t = { ...target.position, ...target.dimensions };
+        const relationHolds = relation === 'above' ? s.y + s.height + gap <= t.y :
+            relation === 'below' ? s.y >= t.y + t.height + gap :
+                relation === 'left-of' ? s.x + s.width + gap <= t.x :
+                    s.x >= t.x + t.width + gap;
+        const horizontalRelation = relation === 'above' || relation === 'below';
+        const aligned = alignment === 'start'
+            ? (horizontalRelation ? s.x === t.x : s.y === t.y)
+            : alignment === 'center'
+                ? (horizontalRelation
+                    ? s.x + s.width / 2 === t.x + t.width / 2
+                    : s.y + s.height / 2 === t.y + t.height / 2)
+                : (horizontalRelation
+                    ? s.x + s.width === t.x + t.width
+                    : s.y + s.height === t.y + t.height);
+        if (!relationHolds || !aligned) {
+            errors.push(this.error('REQUIRED_CONTRADICTION', path, 'Required relation conflicts with pinned geometry in one coordinate frame'));
+        }
+    }
+    canReach(start, target, edges) {
+        const adjacency = new Map();
+        for (const edge of edges) {
+            const next = adjacency.get(edge.from) ?? [];
+            next.push(edge.to);
+            adjacency.set(edge.from, next);
+        }
+        const stack = [start];
         const visited = new Set();
-        const recursionStack = new Set();
-        const dfs = (node, path) => {
-            if (recursionStack.has(node.id)) {
-                // Found a cycle
-                const cycleStart = path.indexOf(node.id);
-                const cyclePath = path.slice(cycleStart).concat(node.id);
-                errors.push({
-                    code: 'CYCLIC_HIERARCHY',
-                    path: '$.nodes',
-                    message: `Cyclic hierarchy detected: ${cyclePath.join(' -> ')}`,
-                    severity: 'error',
-                });
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (current === target)
                 return true;
+            if (visited.has(current))
+                continue;
+            visited.add(current);
+            stack.push(...(adjacency.get(current) ?? []));
+        }
+        return false;
+    }
+    addWarnings(graph, entries, warnings) {
+        const connected = new Set();
+        const usedPorts = new Set();
+        graph.edges.forEach((edge, index) => {
+            if (!edge || typeof edge !== 'object')
+                return;
+            connected.add(edge.source);
+            connected.add(edge.target);
+            if (edge.sourcePort)
+                usedPorts.add(this.portIdentity(edge.source, edge.sourcePort));
+            if (edge.targetPort)
+                usedPorts.add(this.portIdentity(edge.target, edge.targetPort));
+            if (edge.source === edge.target) {
+                warnings.push(this.warning('SELF_LOOP_EDGE', `/edges/${index}`, `Edge "${edge.id}" is a self-loop`));
             }
-            if (visited.has(node.id)) {
-                return false;
+        });
+        entries.forEach((entry) => {
+            if (!entry.node.children?.length && !connected.has(entry.node.id)) {
+                warnings.push(this.warning('ORPHAN_NODE', entry.path, `Node "${entry.node.id}" has no connections`));
             }
-            visited.add(node.id);
-            recursionStack.add(node.id);
-            for (const child of node.children || []) {
-                if (dfs(child, [...path, node.id])) {
-                    return true;
+            const ports = Array.isArray(entry.node.ports) ? entry.node.ports : [];
+            ports.forEach((port, index) => {
+                if (!port || typeof port !== 'object')
+                    return;
+                if (!usedPorts.has(this.portIdentity(entry.node.id, port.id))) {
+                    warnings.push(this.warning('ORPHAN_PORT', `${entry.path}/ports/${index}`, `Port "${port.id}" is never referenced`));
                 }
+            });
+        });
+    }
+    collectNodes(nodes, base = '/nodes', parentId, ancestors = []) {
+        const entries = [];
+        nodes.forEach((node, index) => {
+            if (!node || typeof node !== 'object')
+                return;
+            const path = `${base}/${index}`;
+            entries.push({ node, path, parentId, ancestors });
+            if (Array.isArray(node.children)) {
+                entries.push(...this.collectNodes(node.children, `${path}/children`, node.id, [...ancestors, node.id]));
             }
-            recursionStack.delete(node.id);
-            return false;
+        });
+        return entries;
+    }
+    findHierarchyCycle(nodes, base = '/nodes') {
+        const active = new WeakSet();
+        const visit = (values, path) => {
+            for (let index = 0; index < values.length; index += 1) {
+                const node = values[index];
+                if (!node || typeof node !== 'object' || Array.isArray(node))
+                    continue;
+                const nodePath = `${path}/${index}`;
+                if (active.has(node))
+                    return nodePath;
+                active.add(node);
+                const children = node.children;
+                if (Array.isArray(children)) {
+                    const cycle = visit(children, `${nodePath}/children`);
+                    if (cycle)
+                        return cycle;
+                }
+                active.delete(node);
+            }
+            return undefined;
         };
-        for (const node of nodes) {
-            dfs(node, []);
-        }
-        return errors;
+        return visit(nodes, base);
     }
-    /**
-     * Find a similar ID for suggestions
-     */
-    findSimilarId(target, candidates) {
-        const targetLower = target.toLowerCase();
-        let bestMatch;
-        let bestScore = Infinity;
+    isGraphShape(value) {
+        if (!value || typeof value !== 'object')
+            return false;
+        const record = value;
+        return Array.isArray(record.nodes) && Array.isArray(record.edges);
+    }
+    hasPort(node, portId) {
+        if (!Array.isArray(node.ports))
+            return false;
+        return node.ports.some((port) => Boolean(port && typeof port === 'object' && port.id === portId));
+    }
+    portIdentity(nodeId, portId) {
+        return JSON.stringify([nodeId, portId]);
+    }
+    joinPointer(base, token) {
+        const escaped = token.replace(/~/g, '~0').replace(/\//g, '~1');
+        return `${base}/${escaped}`;
+    }
+    error(code, path, message, suggestion) {
+        return { code, path, message, severity: 'error', suggestion };
+    }
+    warning(code, path, message) {
+        return { code, path, message, severity: 'warning' };
+    }
+    result(errors) {
+        return { valid: false, errors, warnings: [], stats: { nodes: 0, edges: 0 } };
+    }
+    dedupe(values) {
+        const seen = new Set();
+        return values.filter((value) => {
+            const key = `${value.code}\0${value.path}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    }
+    findSimilarId(input, candidates) {
+        if (typeof input !== 'string')
+            return undefined;
+        let best;
+        let distance = Number.POSITIVE_INFINITY;
         for (const candidate of candidates) {
-            const distance = this.levenshteinDistance(targetLower, candidate.toLowerCase());
-            if (distance < bestScore && distance <= 3) {
-                bestScore = distance;
-                bestMatch = candidate;
+            if (typeof candidate !== 'string')
+                continue;
+            const next = this.levenshtein(input, candidate);
+            if (next < distance && next <= Math.max(2, Math.floor(input.length / 3))) {
+                best = candidate;
+                distance = next;
             }
         }
-        return bestMatch ? `Did you mean "${bestMatch}"?` : undefined;
+        return best ? `Did you mean "${best}"?` : undefined;
     }
-    /**
-     * Calculate Levenshtein distance for similarity
-     */
-    levenshteinDistance(a, b) {
-        const matrix = [];
-        for (let i = 0; i <= b.length; i++) {
-            matrix[i] = [i];
-        }
-        for (let j = 0; j <= a.length; j++) {
-            matrix[0][j] = j;
-        }
-        for (let i = 1; i <= b.length; i++) {
-            for (let j = 1; j <= a.length; j++) {
-                if (b.charAt(i - 1) === a.charAt(j - 1)) {
-                    matrix[i][j] = matrix[i - 1][j - 1];
-                }
-                else {
-                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
-                }
+    levenshtein(a, b) {
+        const matrix = Array.from({ length: b.length + 1 }, (_, row) => Array.from({ length: a.length + 1 }, (_, column) => row === 0 ? column : column === 0 ? row : 0));
+        for (let row = 1; row <= b.length; row += 1) {
+            for (let column = 1; column <= a.length; column += 1) {
+                matrix[row][column] = b[row - 1] === a[column - 1]
+                    ? matrix[row - 1][column - 1]
+                    : Math.min(matrix[row - 1][column - 1] + 1, matrix[row][column - 1] + 1, matrix[row - 1][column] + 1);
             }
         }
         return matrix[b.length][a.length];