@gavana.ai/cli 0.2.0

package/src/canvas-agent-validation.mjs

@@ -0,0 +1,554 @@
+// Deterministic canvas graph validation and destructive-impact reporting.
+//
+// Split out of canvas-agent-guide.mjs in guide version 1.2.0: guide prose is now
+// editable markdown under ../guides/, and validation is code. The two no longer
+// share a file. Validation still cites guide topics, so it imports the guide URI
+// helpers — the dependency runs one way only (validation -> guide).
+import { GAVANA_CANVAS_GUIDE_INDEX_URI, GAVANA_CANVAS_GUIDE_VERSION, canvasGuideUriForId } from "./canvas-agent-guide.mjs";
+
+const MAX_FINDINGS_PER_CODE = 50;
+const MAX_OVERLAP_COMPARISONS = 100_000;
+const MAX_OVERLAP_GRID_CELLS_PER_NODE = 64;
+const MAX_VALIDATION_COORDINATE = 10_000_000;
+const MAX_VALIDATION_DIMENSION = 10_000;
+const OVERLAP_GRID_SIZE = 2_048;
+
+export function validateCanvasGraph(canvasValue, options = {}) {
+    const canvas = normalizeCanvas(canvasValue);
+    const graph = graphFindings(canvas, options);
+    const combined = dedupeAndLimitFindings([...(Array.isArray(options.additionalFindings) ? options.additionalFindings : []), ...graph.findings], graph.truncatedCodes);
+    const sorted = combined.findings;
+    const summary = {
+        errors: sorted.filter((finding) => finding.severity === "error").length,
+        warnings: sorted.filter((finding) => finding.severity === "warning").length,
+        info: sorted.filter((finding) => finding.severity === "info").length,
+        truncated: combined.truncatedCodes.length > 0,
+        ...(combined.truncatedCodes.length ? { truncatedCodes: combined.truncatedCodes } : {}),
+    };
+    return {
+        guideVersion: GAVANA_CANVAS_GUIDE_VERSION,
+        scope: options.scope === "proposed" ? "proposed" : "current",
+        canvas: {
+            handle: String(canvas.handle || canvas.id || ""),
+            revision: String(canvas.revision || ""),
+            nodeCount: canvas.nodes.length,
+            connectionCount: canvas.connections.length,
+        },
+        summary: { ...summary, passed: summary.errors === 0, reviewRequired: summary.errors > 0 || summary.warnings > 0 || summary.truncated },
+        findings: sorted,
+        completionReview: buildCompletionReview(canvas, sorted),
+    };
+}
+
+export function canvasDestructiveImpact(canvasValue, appliedValue = {}) {
+    const canvas = normalizeCanvas(canvasValue);
+    const nodesById = new Map(canvas.nodes.map((node) => [cleanId(node.id), node]));
+    const connectionsById = new Map(canvas.connections.map((connection) => [cleanId(connection.id), connection]));
+    const deletedNodeIds = Array.isArray(appliedValue.deletedNodeIds) ? appliedValue.deletedNodeIds.map(cleanId).filter((id) => nodesById.has(id)) : [];
+    const deletedConnectionIds = Array.isArray(appliedValue.deletedConnectionIds) ? appliedValue.deletedConnectionIds.map(cleanId).filter((id) => connectionsById.has(id)) : [];
+    const findings = [];
+    const coveredConnections = new Set();
+
+    for (const nodeId of deletedNodeIds) {
+        const node = nodesById.get(nodeId);
+        const attached = deletedConnectionIds.filter((connectionId) => {
+            const connection = connectionsById.get(connectionId);
+            return connection?.fromNodeId === nodeId || connection?.toNodeId === nodeId;
+        });
+        attached.forEach((connectionId) => coveredConnections.add(connectionId));
+        findings.push(
+            makeFinding("proposed_destructive_change", "warning", `The proposed batch deletes ${nodeHandle(nodeId)}${node?.title ? ` (${node.title})` : ""} and ${attached.length} attached connection(s). Apply only after explicit user intent.`, {
+                nodeIds: [nodeId],
+                connectionIds: attached,
+                guideId: "existing-canvases",
+            }),
+        );
+    }
+    for (const connectionId of deletedConnectionIds.filter((id) => !coveredConnections.has(id))) {
+        findings.push(
+            makeFinding("proposed_destructive_change", "warning", `The proposed batch deletes ${connectionHandle(connectionId)}. Apply only after explicit user intent.`, {
+                connectionIds: [connectionId],
+                guideId: "existing-canvases",
+            }),
+        );
+    }
+
+    return {
+        deletedNodeHandles: deletedNodeIds.map(nodeHandle),
+        deletedConnectionHandles: deletedConnectionIds.map(connectionHandle),
+        mediaNodeHandles: deletedNodeIds.filter((id) => nodesById.get(id)?.type === "image" || nodesById.get(id)?.type === "video").map(nodeHandle),
+        generatedNodeHandles: deletedNodeIds
+            .filter((id) => {
+                const node = nodesById.get(id);
+                return Boolean(node?.metadata?.generationRunId || node?.metadata?.aiJobId || node?.metadata?.actionId || node?.metadata?.variationSourceId);
+            })
+            .map(nodeHandle),
+        findings,
+    };
+}
+
+
+function normalizeCanvas(value) {
+    const source = isRecord(value?.canvas) ? value.canvas : isRecord(value) ? value : {};
+    return {
+        ...source,
+        nodes: Array.isArray(source.nodes) ? source.nodes.filter(isRecord).map(cloneRecord) : [],
+        connections: Array.isArray(source.connections) ? source.connections.filter(isRecord).map(cloneRecord) : [],
+    };
+}
+
+function graphFindings(canvas, validationOptions = {}) {
+    const findings = [];
+    const truncatedCodes = new Set();
+    const nodesById = new Map(canvas.nodes.map((node) => [cleanId(node.id), node]));
+    const incoming = new Map();
+    const outgoing = new Map();
+    const frameConnections = new Map();
+    const finding = (code, severity, message, options = {}) => {
+        const nodeIds = options.nodeIds || [];
+        const connectionIds = options.connectionIds || [];
+        const blocksWrite = proposedFindingTouchesEnforcedWork(validationOptions, nodeIds, connectionIds) && (severity === "error" || code === "node_overlap" || code === "section_content_overflow");
+        const blocksCompletion = nodeIds.some((id) => agentOwnsNode(nodesById.get(cleanId(id)))) || blocksWrite;
+        return makeFinding(code, blocksWrite ? "error" : severity, message, {
+            ...options,
+            ...(blocksWrite ? { blocksWrite: true } : {}),
+            ...(blocksCompletion ? { blocksCompletion: true } : {}),
+        });
+    };
+
+    for (const node of canvas.nodes) {
+        if (isBox(node)) continue;
+        const id = cleanId(node.id);
+        findings.push(
+            finding(
+                "invalid_node_geometry",
+                "error",
+                `${nodeHandle(id)} has invalid or oversized geometry. Positions must be finite within ${MAX_VALIDATION_COORDINATE} canvas units, and dimensions must be finite, positive, and no larger than ${MAX_VALIDATION_DIMENSION}.`,
+                {
+                    nodeIds: [id],
+                    guideId: "sections-layout",
+                },
+            ),
+        );
+    }
+
+    for (const connection of canvas.connections) {
+        const id = cleanId(connection.id);
+        const fromId = cleanId(connection.fromNodeId || connection.from);
+        const toId = cleanId(connection.toNodeId || connection.to);
+        const from = nodesById.get(fromId);
+        const to = nodesById.get(toId);
+        if (!from || !to) {
+            findings.push(
+                finding("broken_connection", "error", `${connectionHandle(id)} points to a missing node.`, {
+                    nodeIds: [fromId, toId].filter(Boolean),
+                    connectionIds: id ? [id] : [],
+                    guideId: "connections",
+                }),
+            );
+            continue;
+        }
+        if (fromId === toId) findings.push(finding("unclear_connection", "error", `${connectionHandle(id)} connects a node to itself.`, { nodeIds: [fromId], connectionIds: [id], guideId: "connections" }));
+        if (!connection.hidden) {
+            incoming.set(toId, (incoming.get(toId) || 0) + 1);
+            outgoing.set(fromId, (outgoing.get(fromId) || 0) + 1);
+        }
+        if (from.metadata?.isSection === true || to.metadata?.isSection === true) {
+            findings.push(finding("unclear_connection", "warning", `${connectionHandle(id)} uses a Section as a workflow endpoint.`, { nodeIds: [fromId, toId], connectionIds: [id], guideId: "connections" }));
+        }
+        const mode = connection.mode;
+        if (mode === "list" && from.metadata?.isList !== true && to.metadata?.isList !== true) {
+            findings.push(finding("unclear_connection", "warning", `${connectionHandle(id)} is a list edge but neither endpoint is a List.`, { nodeIds: [fromId, toId], connectionIds: [id], guideId: "connections" }));
+        }
+        if (mode === "reference" && from.type !== "image") {
+            findings.push(finding("unclear_connection", "warning", `${connectionHandle(id)} is a reference edge whose source is not an image.`, { nodeIds: [fromId, toId], connectionIds: [id], guideId: "connections" }));
+        }
+        if ((mode === "first-frame" || mode === "last-frame") && (from.type !== "image" || to.type !== "video")) {
+            findings.push(finding("unclear_connection", "error", `${connectionHandle(id)} uses ${mode} but must connect an image to a video.`, { nodeIds: [fromId, toId], connectionIds: [id], guideId: "connections" }));
+        }
+        // Hidden prompt edges are provider plumbing the server ignores when it
+        // resolves a prompt, so they take part in neither the endpoint check
+        // nor the one-prompt-per-target rule.
+        if (mode === "prompt" && !connection.hidden && (!(from.type === "text" || from.type === "sticky") || to.type !== "image")) {
+            findings.push(finding("unclear_connection", "error", `${connectionHandle(id)} uses prompt but must connect a text or sticky note to an image node.`, { nodeIds: [fromId, toId], connectionIds: [id], guideId: "connections" }));
+        }
+        if (mode === "first-frame" || mode === "last-frame" || (mode === "prompt" && !connection.hidden)) {
+            const key = `${toId}:${mode}`;
+            const ids = frameConnections.get(key) || [];
+            ids.push(id);
+            frameConnections.set(key, ids);
+        }
+        if (!mode && (from.type === "image" || from.type === "video") && (to.type === "image" || to.type === "video")) {
+            findings.push(
+                finding("unclear_connection", "info", `${connectionHandle(id)} connects media without a reference or frame mode. Confirm that normal transformation flow is intended.`, {
+                    nodeIds: [fromId, toId],
+                    connectionIds: [id],
+                    guideId: "connections",
+                }),
+            );
+        }
+    }
+
+    const connectionKeys = new Map();
+    for (const connection of canvas.connections.filter((entry) => !entry.hidden)) {
+        const key = `${cleanId(connection.fromNodeId || connection.from)}:${cleanId(connection.toNodeId || connection.to)}:${String(connection.mode || "normal")}`;
+        const ids = connectionKeys.get(key) || [];
+        ids.push(cleanId(connection.id));
+        connectionKeys.set(key, ids);
+    }
+    for (const ids of connectionKeys.values()) {
+        if (ids.length > 1) findings.push(finding("duplicate_connection", "warning", `Duplicate directed connections: ${ids.map(connectionHandle).join(", ")}.`, { connectionIds: ids, guideId: "connections" }));
+    }
+    for (const [key, ids] of frameConnections.entries()) {
+        if (ids.length < 2) continue;
+        const [targetId, mode] = key.split(":");
+        findings.push(finding("unclear_connection", "error", `${nodeHandle(targetId)} has more than one ${mode} connection.`, { nodeIds: [targetId], connectionIds: ids, guideId: "connections" }));
+    }
+
+    const ordinaryNodes = canvas.nodes.filter((node) => node.metadata?.isSection !== true && !intentionalOverlay(node) && isBox(node));
+    const overlapBuckets = new Map();
+    let overlapFindingCount = 0;
+    let overlapComparisonCount = 0;
+    overlapSearch: for (const node of ordinaryNodes) {
+        const cells = boxGridCells(node);
+        if (!cells) {
+            truncatedCodes.add("node_overlap");
+            continue;
+        }
+        const candidates = new Set();
+        for (const cell of cells) {
+            for (const candidate of overlapBuckets.get(cell) || []) candidates.add(candidate);
+        }
+        for (const candidate of candidates) {
+            overlapComparisonCount += 1;
+            if (overlapComparisonCount > MAX_OVERLAP_COMPARISONS) {
+                truncatedCodes.add("node_overlap");
+                break overlapSearch;
+            }
+            if (relatedOverlay(candidate, node)) continue;
+            const overlapWidth = Math.min(candidate.position.x + candidate.width, node.position.x + node.width) - Math.max(candidate.position.x, node.position.x);
+            const overlapHeight = Math.min(candidate.position.y + candidate.height, node.position.y + node.height) - Math.max(candidate.position.y, node.position.y);
+            if (overlapWidth <= 8 || overlapHeight <= 8) continue;
+            if (overlapFindingCount >= MAX_FINDINGS_PER_CODE) {
+                truncatedCodes.add("node_overlap");
+                break overlapSearch;
+            }
+            findings.push(finding("node_overlap", "warning", `${nodeHandle(candidate.id)} overlaps ${nodeHandle(node.id)}.`, { nodeIds: [candidate.id, node.id], guideId: "sections-layout" }));
+            overlapFindingCount += 1;
+        }
+        for (const cell of cells) {
+            const bucket = overlapBuckets.get(cell) || [];
+            bucket.push(node);
+            overlapBuckets.set(cell, bucket);
+        }
+    }
+
+    const sections = canvas.nodes.filter((node) => isRecord(node.metadata) && node.metadata.isSection === true && isBox(node));
+
+    for (const node of canvas.nodes) {
+        const id = cleanId(node.id);
+        const metadata = isRecord(node.metadata) ? node.metadata : {};
+        const section = sectionOwnerFor(node, sections);
+        if (metadata.isSection === true && (node.type !== "text" || !isBox(node) || node.width < 200 || node.height < 160)) {
+            findings.push(finding("malformed_section", "error", `${nodeHandle(id)} is marked as a Section but must be a text node at least 200 by 160.`, { nodeIds: [id], guideId: "notes-text-sections" }));
+        }
+        const agentCreated = typeof metadata.agentCreatedAt === "string" && metadata.isSection !== true && !metadata.listOutputId && !metadata.batchRootId && !metadata.recipeInstance && !metadata.isVisualRecipe;
+        if (agentCreated && !section) {
+            findings.push(finding("unsectioned_node", "info", `${nodeHandle(id)} is agent-created but sits outside every Section. Group agent work in a titled Section (one task = one Section).`, { nodeIds: [id], guideId: "sections-layout" }));
+        }
+        if (metadata.isSection !== true && section && !frameIsContainedBySection(node, section)) {
+            findings.push(
+                finding("section_content_overflow", "warning", `${nodeHandle(id)} escapes its containing Section ${nodeHandle(section.id)}. Keep the full node frame inside the Section bounds.`, {
+                    nodeIds: [id, cleanId(section.id)],
+                    guideId: "sections-layout",
+                }),
+            );
+        }
+        const content = typeof metadata.content === "string" ? metadata.content.trim() : "";
+        const looksLikeHeader = node.type === "text" && metadata.isSection !== true && content.length <= 160 && ((isBox(node) && node.width >= 520 && node.height <= 180) || Number(metadata.fontSize) >= 28);
+        if (looksLikeHeader && !(incoming.get(id) || outgoing.get(id))) {
+            findings.push(finding("fake_section_header", "warning", `${nodeHandle(id)} looks like a region header but is not a Section.`, { nodeIds: [id], guideId: "notes-text-sections" }));
+        }
+        const generated = (node.type === "image" || node.type === "video") && Boolean(metadata.generationRunId || metadata.aiJobId || metadata.actionId || metadata.variationSourceId);
+        const hasParent = Boolean(metadata.batchRootId || metadata.listOutputId);
+        if (generated && !(incoming.get(id) || hasParent)) {
+            findings.push(finding("unconnected_generated_output", "warning", `${nodeHandle(id)} is a generated output without an incoming relationship or output parent.`, { nodeIds: [id], guideId: "generated-assets" }));
+        }
+        const isMedia = node.type === "image" || node.type === "video";
+        const hasMediaResult = Boolean(metadata.storageKey || metadata.content || metadata.posterUrl);
+        if (isMedia && !hasMediaResult && !(incoming.get(id) || outgoing.get(id) || hasParent)) {
+            findings.push(finding("orphan_media_placeholder", "warning", `${nodeHandle(id)} is an empty media placeholder with no relationship to a prompt, source, List, or stage.`, { nodeIds: [id], guideId: "generated-assets" }));
+        }
+        for (const [field, values] of lineageReferences(metadata)) {
+            const missing = values.filter((value) => !nodesById.has(value));
+            if (missing.length) {
+                findings.push(
+                    finding("broken_generated_lineage", "error", `${nodeHandle(id)} has missing ${field} reference(s): ${missing.map(nodeHandle).join(", ")}.`, {
+                        nodeIds: [id, ...missing],
+                        guideId: "generated-assets",
+                    }),
+                );
+            }
+        }
+    }
+    return { findings, truncatedCodes: Array.from(truncatedCodes) };
+}
+
+/**
+ * Detect the most specific candidate Section by center point so validation can
+ * diagnose a frame that visibly escapes it. Persisted section membership uses
+ * the stricter full-frame contract and therefore never accepts that overflow.
+ */
+function sectionOwnerFor(node, sections) {
+    if (!isBox(node) || node.metadata?.isSection === true) return null;
+    const centerX = node.position.x + node.width / 2;
+    const centerY = node.position.y + node.height / 2;
+    let owner = null;
+    for (const section of sections) {
+        if (cleanId(section.id) === cleanId(node.id)) continue;
+        const withinCenter = centerX >= section.position.x && centerX <= section.position.x + section.width && centerY >= section.position.y && centerY <= section.position.y + section.height;
+        if (!withinCenter) continue;
+        const area = section.width * section.height;
+        const ownerArea = owner ? owner.width * owner.height : Number.POSITIVE_INFINITY;
+        if (!owner || area < ownerArea || (area === ownerArea && cleanId(section.id) < cleanId(owner.id))) owner = section;
+    }
+    return owner;
+}
+
+function frameIsContainedBySection(node, section) {
+    return node.position.x >= section.position.x && node.position.y >= section.position.y && node.position.x + node.width <= section.position.x + section.width && node.position.y + node.height <= section.position.y + section.height;
+}
+
+function proposedFindingTouchesEnforcedWork(options, nodeIds, connectionIds) {
+    if (options.scope !== "proposed" || !isRecord(options.enforcement)) return false;
+    const enforcedNodes = new Set(Array.isArray(options.enforcement.nodeIds) ? options.enforcement.nodeIds.map(cleanId).filter(Boolean) : []);
+    const enforcedConnections = new Set(Array.isArray(options.enforcement.connectionIds) ? options.enforcement.connectionIds.map(cleanId).filter(Boolean) : []);
+    return nodeIds.some((id) => enforcedNodes.has(cleanId(id))) || connectionIds.some((id) => enforcedConnections.has(cleanId(id)));
+}
+
+function agentOwnsNode(node) {
+    return Boolean(isRecord(node?.metadata) && typeof node.metadata.agentCreatedAt === "string");
+}
+
+function buildCompletionReview(canvas, findings) {
+    const generatedOutputs = canvas.nodes.filter(isGeneratedOutput);
+    const durableOutputs = generatedOutputs.filter(hasDurableOutput);
+    const pendingOutputs = generatedOutputs.filter((node) => node.metadata?.aiJobStatus === "queued" || node.metadata?.aiJobStatus === "running" || node.metadata?.outputValidationStatus === "checking");
+    const failedOutputs = generatedOutputs.filter((node) => node.metadata?.status === "error" || node.metadata?.aiJobStatus === "failed" || node.metadata?.aiJobStatus === "canceled");
+    const overlap = reviewArea(findings, "node_overlap");
+    const containment = reviewArea(findings, "section_content_overflow", "unsectioned_node");
+    const referenceLineage = reviewArea(findings, "broken_generated_lineage", "unconnected_generated_output", "orphan_media_placeholder");
+    const productFidelity = productFidelityReview(canvas, generatedOutputs);
+    const blockingFindings = findings.filter((finding) => finding.blocksWrite === true || finding.blocksCompletion === true);
+    const blockingFindingCodes = uniqueSorted(blockingFindings.map((finding) => finding.code));
+    const advisoryFindingCodes = uniqueSorted(findings.filter((finding) => !blockingFindings.includes(finding)).map((finding) => finding.code));
+    const doneClaimAllowed = blockingFindings.length === 0 && productFidelity.status !== "needs-review";
+
+    return {
+        status: doneClaimAllowed ? "ready" : blockingFindings.length ? "blocked" : "needs-review",
+        doneClaimAllowed,
+        instruction: "Do not claim Done while blocking findings remain or product-fidelity review is needed.",
+        outputs: {
+            count: generatedOutputs.length,
+            durableCount: durableOutputs.length,
+            pendingCount: pendingOutputs.length,
+            failedCount: failedOutputs.length,
+            handles: generatedOutputs.map((node) => nodeHandle(node.id)).sort(),
+        },
+        overlap,
+        containment,
+        referenceLineage,
+        productFidelity,
+        blockingFindingCodes,
+        advisoryFindingCodes,
+    };
+}
+
+function reviewArea(findings, ...codes) {
+    const matched = findings.filter((finding) => codes.includes(finding.code));
+    const blocking = matched.some((finding) => finding.blocksWrite === true || finding.blocksCompletion === true);
+    return {
+        status: !matched.length ? "clear" : blocking ? "blocked" : "needs-review",
+        findingCodes: uniqueSorted(matched.map((finding) => finding.code)),
+        nodeHandles: uniqueSorted(matched.flatMap((finding) => finding.nodeHandles || [])),
+        connectionHandles: uniqueSorted(matched.flatMap((finding) => finding.connectionHandles || [])),
+    };
+}
+
+function productFidelityReview(canvas, generatedOutputs) {
+    const referenceTargets = generatedOutputs.filter((node) => outputHasReferenceEvidence(node, canvas.connections));
+    if (!referenceTargets.length) {
+        return {
+            status: "not-applicable",
+            reviewedOutputCount: 0,
+            needsReviewOutputHandles: [],
+            evidenceMissingOutputHandles: [],
+        };
+    }
+    const needsReview = referenceTargets.filter((node) => node.metadata?.outputValidationStatus === "needs-review" || node.metadata?.outputValidationStatus === "checking");
+    const evidenceMissing = referenceTargets.filter((node) => !node.metadata?.outputValidationStatus || node.metadata?.outputValidationStatus === "skipped");
+    return {
+        status: needsReview.length || evidenceMissing.length ? "needs-review" : "passed",
+        reviewedOutputCount: referenceTargets.length - needsReview.length - evidenceMissing.length,
+        needsReviewOutputHandles: needsReview.map((node) => nodeHandle(node.id)).sort(),
+        evidenceMissingOutputHandles: evidenceMissing.map((node) => nodeHandle(node.id)).sort(),
+        reasons: referenceTargets
+            .filter((node) => typeof node.metadata?.outputValidationReason === "string" && node.metadata.outputValidationReason)
+            .map((node) => ({ nodeHandle: nodeHandle(node.id), reason: node.metadata.outputValidationReason }))
+            .sort((left, right) => left.nodeHandle.localeCompare(right.nodeHandle)),
+    };
+}
+
+function isGeneratedOutput(node) {
+    if (node.type !== "image" && node.type !== "video") return false;
+    const metadata = isRecord(node.metadata) ? node.metadata : {};
+    return Boolean(metadata.generationRunId || metadata.aiJobId || metadata.actionId || metadata.variationSourceId);
+}
+
+function hasDurableOutput(node) {
+    const metadata = isRecord(node.metadata) ? node.metadata : {};
+    return Boolean(metadata.storageKey || metadata.content || metadata.posterUrl) && metadata.status !== "error";
+}
+
+function outputHasReferenceEvidence(node, connections) {
+    const metadata = isRecord(node.metadata) ? node.metadata : {};
+    if (Array.isArray(metadata.referenceHandles) && metadata.referenceHandles.length) return true;
+    if (Array.isArray(metadata.referenceNodeIds) && metadata.referenceNodeIds.length) return true;
+    if (Array.isArray(metadata.references) && metadata.references.length) return true;
+    return connections.some((connection) => cleanId(connection.toNodeId || connection.to) === cleanId(node.id) && connection.mode === "reference");
+}
+
+function uniqueSorted(values) {
+    return Array.from(new Set(values.filter(Boolean))).sort();
+}
+
+function lineageReferences(metadata) {
+    const result = [];
+    for (const field of ["batchRootId", "listOutputId", "firstFrameNodeId", "lastFrameNodeId", "listSourceId", "listGeneratorId", "variationSourceId", "primaryImageId"]) {
+        const value = cleanId(metadata[field]);
+        if (value) result.push([field, [value]]);
+    }
+    for (const field of ["batchChildIds", "generatedOutputChildIds", "referenceNodeIds", "listRunTargetIds"]) {
+        const values = Array.isArray(metadata[field]) ? metadata[field].map(cleanId).filter(Boolean) : [];
+        if (values.length) result.push([field, values]);
+    }
+    if (Array.isArray(metadata.listItems)) {
+        metadata.listItems.forEach((item, index) => {
+            if (!isRecord(item)) return;
+            const sourceNodeId = cleanId(item.sourceNodeId);
+            if (sourceNodeId) result.push([`listItems[${index}].sourceNodeId`, [sourceNodeId]]);
+            if (Array.isArray(item.referenceBindings)) {
+                const values = item.referenceBindings
+                    .filter(isRecord)
+                    .map((binding) => cleanId(binding.nodeId))
+                    .filter(Boolean);
+                if (values.length) result.push([`listItems[${index}].referenceBindings`, values]);
+            }
+        });
+    }
+    return result;
+}
+
+function boxGridCells(node) {
+    const startX = Math.floor(node.position.x / OVERLAP_GRID_SIZE);
+    const endX = Math.floor((node.position.x + node.width - 1) / OVERLAP_GRID_SIZE);
+    const startY = Math.floor(node.position.y / OVERLAP_GRID_SIZE);
+    const endY = Math.floor((node.position.y + node.height - 1) / OVERLAP_GRID_SIZE);
+    const columns = endX - startX + 1;
+    const rows = endY - startY + 1;
+    if (!Number.isSafeInteger(columns) || !Number.isSafeInteger(rows) || columns <= 0 || rows <= 0 || columns * rows > MAX_OVERLAP_GRID_CELLS_PER_NODE) return null;
+    const cells = [];
+    for (let x = startX; x <= endX; x += 1) {
+        for (let y = startY; y <= endY; y += 1) cells.push(`${x}:${y}`);
+    }
+    return cells;
+}
+
+function makeFinding(code, severity, message, options = {}) {
+    const guideUri = canvasGuideUriForId(options.guideId || "validation-recovery");
+    return {
+        code,
+        severity,
+        message,
+        ...(options.nodeIds?.length ? { nodeHandles: Array.from(new Set(options.nodeIds.filter(Boolean).map(nodeHandle))).sort() } : {}),
+        ...(options.connectionIds?.length ? { connectionHandles: Array.from(new Set(options.connectionIds.filter(Boolean).map(connectionHandle))).sort() } : {}),
+        ...(options.blocksWrite ? { blocksWrite: true } : {}),
+        ...(options.blocksCompletion ? { blocksCompletion: true } : {}),
+        guideUri: guideUri || GAVANA_CANVAS_GUIDE_INDEX_URI,
+    };
+}
+
+function dedupeAndLimitFindings(findings, alreadyTruncated = []) {
+    const seen = new Set();
+    const counts = new Map();
+    const truncatedCodes = new Set(alreadyTruncated);
+    // Sort by severity before applying the per-code cap so truncation only ever
+    // drops the least severe findings of a code. Otherwise fifty advisory
+    // findings could crowd an error-severity finding of the same code out of
+    // the result — and out of the apply-batch validation gate.
+    const limited = findings
+        .slice()
+        .sort((a, b) => severityRank(a.severity) - severityRank(b.severity) || a.code.localeCompare(b.code) || a.message.localeCompare(b.message))
+        .filter((entry) => {
+            const key = JSON.stringify([entry.code, entry.severity, entry.message, entry.nodeHandles, entry.connectionHandles]);
+            if (seen.has(key)) return false;
+            seen.add(key);
+            const count = counts.get(entry.code) || 0;
+            counts.set(entry.code, count + 1);
+            if (count >= MAX_FINDINGS_PER_CODE) truncatedCodes.add(entry.code);
+            return count < MAX_FINDINGS_PER_CODE;
+        });
+    return { findings: limited, truncatedCodes: Array.from(truncatedCodes).sort() };
+}
+
+function intentionalOverlay(node) {
+    return Boolean(node.metadata?.isBatchRoot || node.metadata?.isGeneratedOutputList);
+}
+
+function relatedOverlay(left, right) {
+    const leftMetadata = isRecord(left.metadata) ? left.metadata : {};
+    const rightMetadata = isRecord(right.metadata) ? right.metadata : {};
+    const relatedIds = [leftMetadata.batchRootId, leftMetadata.listOutputId, rightMetadata.batchRootId, rightMetadata.listOutputId].map(cleanId);
+    return relatedIds.includes(cleanId(left.id)) || relatedIds.includes(cleanId(right.id));
+}
+
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function cloneRecord(value) {
+    return typeof structuredClone === "function" ? structuredClone(value) : JSON.parse(JSON.stringify(value));
+}
+
+function isPoint(value) {
+    return isRecord(value) && Number.isFinite(value.x) && Math.abs(value.x) <= MAX_VALIDATION_COORDINATE && Number.isFinite(value.y) && Math.abs(value.y) <= MAX_VALIDATION_COORDINATE;
+}
+
+function isBox(value) {
+    return isPoint(value.position) && isValidationDimension(value.width) && isValidationDimension(value.height);
+}
+
+function isValidationDimension(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= MAX_VALIDATION_DIMENSION;
+}
+
+function cleanId(value) {
+    return String(value || "")
+        .trim()
+        .replace(/^(?:node|connection):/, "")
+        .slice(0, 240);
+}
+
+function nodeHandle(value) {
+    const id = cleanId(value);
+    return id ? `node:${id}` : "node:(missing)";
+}
+
+function connectionHandle(value) {
+    const id = cleanId(value);
+    return id ? `connection:${id}` : "connection:(missing)";
+}
+
+function severityRank(value) {
+    return value === "error" ? 0 : value === "warning" ? 1 : 2;
+}