@neoloopy/cld-canvas 0.1.3 → 0.1.7

package/dist/engine/quantCanvasLoops.js

@@ -0,0 +1,694 @@
+/**
+ * Conservative, renderer-facing resolution of qualitative and quantitative loops.
+ *
+ * This is deliberately not a simulation or dominance implementation. It only
+ * enriches a declared qualitative cycle independently when every authored leg
+ * maps to one exact visible connector or material pipe. It admits a synthesized
+ * static scalar cycle only when every equation dependency and material effect
+ * is equally exact. Incomplete quantitative analysis returns no synthesized
+ * prefix but never strips an independently resolved qualitative path.
+ */
+import { CanvasLoopPath, DetectedLoop, LoopType, canonicalDirectedCycle, } from "./types";
+import { flowOf, isCloud, resolveFlowSpec, validateFlowEndpoints, } from "./sfd";
+export const USER_FACING_CANVAS_LOOP_LIMITS = Object.freeze({
+    maxLoops: 2048,
+    maxEdgeVisits: 100000,
+    maxDepth: 512,
+});
+const UNSUPPORTED_STATEFUL_FUNCTIONS = new Set([
+    "delay",
+    "delay1",
+    "delay3",
+    "delay_fixed",
+    "delay_information",
+    "delay_material",
+    "smooth",
+    "smooth3",
+    "smoothi",
+    "smooth3i",
+    "trend",
+    "forecast",
+    "npv",
+]);
+const SUPPORTED_SCALAR_FUNCTIONS = new Set([
+    "abs",
+    "acos",
+    "asin",
+    "atan",
+    "ceil",
+    "ceiling",
+    "cos",
+    "exp",
+    "floor",
+    "if_then_else",
+    "integer",
+    "ln",
+    "log",
+    "max",
+    "min",
+    "mod",
+    "power",
+    "pulse",
+    "pulse_train",
+    "ramp",
+    "round",
+    "sin",
+    "sqrt",
+    "step",
+    "tan",
+]);
+const SCALAR_NAMES = new Set(["false", "pi", "time", "true"]);
+const ARRAY_KEYS = new Set([
+    "cell",
+    "cells",
+    "dimension",
+    "dimensions",
+    "dims",
+    "element",
+    "elements",
+    "flattened",
+    "subscript",
+    "subscriptinstance",
+    "subscripts",
+]);
+const COMPOSITION_KEYS = new Set([
+    "binding",
+    "bindings",
+    "composed",
+    "composedfrom",
+    "composition",
+    "inputbinding",
+    "inputbindings",
+    "subsystem",
+    "subsystems",
+]);
+const NODE_HIERARCHY_KEYS = new Set([
+    "composedfrom",
+    "inputbinding",
+    "inputbindings",
+    "subsystem",
+    "subsystems",
+]);
+function objectMap(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonEmpty(value) {
+    if (value === null || value === undefined || value === false)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === "object")
+        return Object.keys(value).length > 0;
+    return true;
+}
+function containsMarkedKey(value, keys) {
+    const map = objectMap(value);
+    if (!map)
+        return false;
+    for (const [rawKey, nested] of Object.entries(map)) {
+        const key = rawKey.toLowerCase().replace(/_/g, "");
+        if (keys.has(key) && nonEmpty(nested))
+            return true;
+        if (containsMarkedKey(nested, keys))
+            return true;
+    }
+    return false;
+}
+function scalarText(value) {
+    if (typeof value === "string" || typeof value === "number") {
+        const text = String(value).trim();
+        return text.length > 0 ? text : null;
+    }
+    return null;
+}
+function incomplete(reason, limits) {
+    return `quant-loop-analysis-incomplete: ${reason} ` +
+        `(maxLoops=${limits.maxLoops}, maxEdgeVisits=${limits.maxEdgeVisits}, ` +
+        `maxDepth=${limits.maxDepth}); repair or simplify the model and retry`;
+}
+function pairKey(from, to) {
+    return `${from.length}:${from}>${to.length}:${to}`;
+}
+/** Stable first-class SFD pipe-leg identity. */
+export function materialPipeLegId(flowId, stockId) {
+    return pairKey(flowId, stockId);
+}
+/** Stable base id for a non-persistent CLD projection of a material effect. */
+export function materialProjectionEdgeId(flowId, stockId) {
+    return `__cld_material_projection__${flowId.length}:${flowId}:` +
+        `${stockId.length}:${stockId}`;
+}
+function uniqueProjectionId(flowId, stockId, persistedIds) {
+    const base = materialProjectionEdgeId(flowId, stockId);
+    if (!persistedIds.has(base))
+        return base;
+    let suffix = 1;
+    while (persistedIds.has(`${base}:${suffix}`))
+        suffix++;
+    return `${base}:${suffix}`;
+}
+function isWord(ch) {
+    return ch.length > 0 && /[A-Za-z0-9_]/.test(ch);
+}
+/**
+ * Parse only enough scalar expression syntax to prove exact model references.
+ * Unknown identifiers, stateful functions, arrays, and malformed token order
+ * fail closed. Polarity still comes from the declared connector, not algebraic
+ * inference.
+ */
+function parseScalarEquation(source, labelsByLongest) {
+    if (/[[\]{};"'`]/.test(source)) {
+        return { ok: false, reason: "unsupported scalar equation syntax" };
+    }
+    const refs = [];
+    const seenRefs = new Set();
+    const parens = [];
+    let i = 0;
+    let expectValue = true;
+    let pendingFunction = false;
+    const nextNonSpaceIndex = (at) => {
+        let cursor = at;
+        while (cursor < source.length && /\s/.test(source[cursor]))
+            cursor++;
+        return cursor;
+    };
+    const addRef = (id) => {
+        if (seenRefs.add(id))
+            refs.push(id);
+    };
+    while (i < source.length) {
+        if (/\s/.test(source[i])) {
+            i++;
+            continue;
+        }
+        let matchedLabel;
+        for (const candidate of labelsByLongest) {
+            const end = i + candidate.label.length;
+            if (source.slice(i, end).toLowerCase() !== candidate.label.toLowerCase())
+                continue;
+            const before = i > 0 ? source[i - 1] : "";
+            const after = end < source.length ? source[end] : "";
+            if (isWord(before) || isWord(after))
+                continue;
+            if (source[nextNonSpaceIndex(end)] === "(")
+                continue;
+            matchedLabel = candidate;
+            break;
+        }
+        if (matchedLabel) {
+            if (!expectValue)
+                return { ok: false, reason: "malformed equation token order" };
+            addRef(matchedLabel.id);
+            i += matchedLabel.label.length;
+            expectValue = false;
+            pendingFunction = false;
+            continue;
+        }
+        const rest = source.slice(i);
+        const number = /^(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?/.exec(rest);
+        if (number) {
+            if (!expectValue)
+                return { ok: false, reason: "malformed equation token order" };
+            i += number[0].length;
+            expectValue = false;
+            pendingFunction = false;
+            continue;
+        }
+        const multiFunction = /^(IF\s+THEN\s+ELSE|PULSE\s+TRAIN)\b/i.exec(rest);
+        const identifier = multiFunction ?? /^[A-Za-z_][A-Za-z0-9_]*/.exec(rest);
+        if (identifier) {
+            const raw = identifier[0];
+            const normalized = raw.trim().toLowerCase().replace(/\s+/g, "_");
+            const next = nextNonSpaceIndex(i + raw.length);
+            const called = source[next] === "(";
+            if (called) {
+                if (!expectValue)
+                    return { ok: false, reason: "malformed equation token order" };
+                if (UNSUPPORTED_STATEFUL_FUNCTIONS.has(normalized)) {
+                    return { ok: false, reason: `unsupported stateful function ${raw.trim()}` };
+                }
+                if (!SUPPORTED_SCALAR_FUNCTIONS.has(normalized)) {
+                    return { ok: false, reason: `unsupported function ${raw.trim()}` };
+                }
+                pendingFunction = true;
+                i += raw.length;
+                continue;
+            }
+            if (normalized === "not") {
+                if (!expectValue)
+                    return { ok: false, reason: "malformed equation token order" };
+                i += raw.length;
+                continue;
+            }
+            if (normalized === "and" || normalized === "or") {
+                if (expectValue)
+                    return { ok: false, reason: "malformed equation token order" };
+                expectValue = true;
+                i += raw.length;
+                continue;
+            }
+            if (!SCALAR_NAMES.has(normalized)) {
+                return { ok: false, reason: `unknown equation identifier ${raw}` };
+            }
+            if (!expectValue)
+                return { ok: false, reason: "malformed equation token order" };
+            expectValue = false;
+            pendingFunction = false;
+            i += raw.length;
+            continue;
+        }
+        if (source[i] === "(") {
+            if (!expectValue && !pendingFunction) {
+                return { ok: false, reason: "malformed equation token order" };
+            }
+            parens.push(pendingFunction ? "function" : "group");
+            pendingFunction = false;
+            expectValue = true;
+            i++;
+            continue;
+        }
+        if (source[i] === ")") {
+            if (expectValue || parens.length === 0) {
+                return { ok: false, reason: "unbalanced or empty parentheses" };
+            }
+            parens.pop();
+            expectValue = false;
+            pendingFunction = false;
+            i++;
+            continue;
+        }
+        if (source[i] === ",") {
+            if (expectValue || parens[parens.length - 1] !== "function") {
+                return { ok: false, reason: "malformed function arguments" };
+            }
+            expectValue = true;
+            pendingFunction = false;
+            i++;
+            continue;
+        }
+        const operator = /^(<=|>=|<>|==|!=|&&|\|\||[+\-*/^%<>=!])/.exec(rest);
+        if (operator) {
+            const unary = expectValue && ["+", "-", "!"].includes(operator[0]);
+            if (expectValue && !unary) {
+                return { ok: false, reason: "malformed equation token order" };
+            }
+            expectValue = true;
+            pendingFunction = false;
+            i += operator[0].length;
+            continue;
+        }
+        return { ok: false, reason: `unsupported equation token ${source[i]}` };
+    }
+    if (pendingFunction || expectValue || parens.length > 0) {
+        return { ok: false, reason: "incomplete or unbalanced equation" };
+    }
+    return { ok: true, references: refs };
+}
+function resolveQualitativeCanvasPath(nodes, loop) {
+    const byId = new Map();
+    for (const node of nodes) {
+        if (byId.has(node.id))
+            return null;
+        byId.set(node.id, node);
+    }
+    if (loop.nodeIds.length < 2 || new Set(loop.nodeIds).size !== loop.nodeIds.length) {
+        return null;
+    }
+    const resolvedNodes = [];
+    for (const id of loop.nodeIds) {
+        const node = byId.get(id);
+        if (!node)
+            return null;
+        resolvedNodes.push(node);
+    }
+    const legs = [];
+    let polarityProduct = 1;
+    for (let index = 0; index < resolvedNodes.length; index++) {
+        const from = resolvedNodes[index];
+        const to = resolvedNodes[(index + 1) % resolvedNodes.length];
+        const candidates = from.links.filter((link) => link.to === to.id);
+        if (candidates.length !== 1)
+            return null;
+        const link = candidates[0];
+        if (link.indirect || (link.polarity !== "+" && link.polarity !== "-")) {
+            return null;
+        }
+        const declaredPolarity = link.polarity === "-" ? -1 : 1;
+        if (from.type === "flow" && to.type === "stock") {
+            const spec = resolveFlowSpec(from, byId);
+            if (!spec)
+                return null;
+            const drains = spec.from === to.id;
+            const fills = spec.to === to.id;
+            if (drains && fills)
+                return null;
+            if (drains || fills) {
+                const materialPolarity = fills ? 1 : -1;
+                if (declaredPolarity !== materialPolarity)
+                    return null;
+                legs.push({
+                    kind: "material",
+                    fromNodeId: from.id,
+                    toNodeId: to.id,
+                    flowId: from.id,
+                    stockId: to.id,
+                    cldEdgeId: `${from.id}__${to.id}`,
+                    polarity: materialPolarity,
+                });
+                polarityProduct *= materialPolarity;
+                continue;
+            }
+        }
+        legs.push({
+            kind: "causal",
+            fromNodeId: from.id,
+            toNodeId: to.id,
+            edgeId: `${from.id}__${to.id}`,
+            polarity: declaredPolarity,
+        });
+        polarityProduct *= declaredPolarity;
+    }
+    const resolvedType = polarityProduct === 1
+        ? LoopType.reinforcing
+        : LoopType.balancing;
+    if (resolvedType !== loop.type)
+        return null;
+    return new DetectedLoop(loop.nodeIds, loop.type, new CanvasLoopPath(legs), loop.identityMode, loop.exactRouteAmbiguous);
+}
+function qualitativeOnly(nodes, qualitativeLoops, analysisError) {
+    const grouped = new Map();
+    for (const loop of qualitativeLoops) {
+        const existing = grouped.get(loop.key);
+        if (!existing) {
+            grouped.set(loop.key, {
+                retained: loop,
+                exactKeys: new Set([loop.exactKey]),
+                ambiguous: loop.exactRouteAmbiguous,
+            });
+            continue;
+        }
+        existing.exactKeys.add(loop.exactKey);
+        existing.ambiguous = existing.ambiguous ||
+            loop.exactRouteAmbiguous ||
+            existing.exactKeys.size > 1;
+    }
+    const loops = [...grouped.values()].map(({ retained, ambiguous }) => {
+        if (ambiguous) {
+            return new DetectedLoop(retained.nodeIds, retained.type, undefined, retained.identityMode, true);
+        }
+        return resolveQualitativeCanvasPath(nodes, retained) ??
+            (retained.canvasPath === undefined
+                ? retained
+                : new DetectedLoop(retained.nodeIds, retained.type, undefined, retained.identityMode, retained.exactRouteAmbiguous));
+    });
+    return { loops, analysisError };
+}
+/**
+ * Discover complete canvas-resolvable quantitative cycles and merge them with
+ * exact qualitative counterparts. Declared loops are first resolved from their
+ * own authored topology, so a quantitative error never suppresses their honest
+ * CLD/SFD representation.
+ */
+export function discoverCanvasLoops(nodes, qualitativeLoops, options = {}) {
+    const limits = options.limits ?? USER_FACING_CANVAS_LOOP_LIMITS;
+    const fail = (reason) => qualitativeOnly(nodes, qualitativeLoops, incomplete(reason, limits));
+    if (limits.maxLoops < 1 || limits.maxEdgeVisits < 1 || limits.maxDepth < 2) {
+        return fail("invalid discovery limits");
+    }
+    const manifestQuant = options.manifest?.extra["mode"] === "quantitative" ||
+        objectMap(options.manifest?.extra["quantitative"]) !== null;
+    const nodeQuant = nodes.some((node) => objectMap(node.extra["quant"]) !== null);
+    if (!manifestQuant && !nodeQuant) {
+        return qualitativeOnly(nodes, qualitativeLoops, null);
+    }
+    if (containsMarkedKey(options.manifest?.extra["quantitative"], ARRAY_KEYS) ||
+        nodes.some((node) => containsMarkedKey(node.extra["quant"], ARRAY_KEYS))) {
+        return fail("arrayed or flattened quantitative topology is not canvas-resolvable");
+    }
+    if (containsMarkedKey(options.manifest?.extra, COMPOSITION_KEYS) ||
+        nodes.some((node) => (node.subsystem ?? "").trim().length > 0 ||
+            containsMarkedKey(node.extra["quant"], NODE_HIERARCHY_KEYS))) {
+        return fail("subsystem or composed quantitative topology is not canvas-resolvable");
+    }
+    const byId = new Map();
+    const byLabel = new Map();
+    for (const node of nodes) {
+        if (byId.has(node.id))
+            return fail(`duplicate variable id ${node.id}`);
+        byId.set(node.id, node);
+        const label = node.label.trim();
+        if (label.length === 0)
+            return fail(`missing variable label for ${node.id}`);
+        const folded = label.toLowerCase();
+        if (byLabel.has(folded))
+            return fail(`duplicate variable label ${label}`);
+        byLabel.set(folded, node);
+    }
+    const labelsByLongest = [...nodes]
+        .map((node) => ({ id: node.id, label: node.label.trim() }))
+        .sort((a, b) => b.label.length - a.label.length || a.label.localeCompare(b.label));
+    let edgeVisits = 0;
+    const workLimitReached = () => ++edgeVisits > limits.maxEdgeVisits;
+    const displayed = new Map();
+    const persistedEdgeIds = new Set();
+    for (const source of nodes) {
+        for (let index = 0; index < source.links.length; index++) {
+            if (workLimitReached())
+                return fail("loop discovery exceeded its work limit");
+            const link = source.links[index];
+            if (!byId.has(link.to))
+                continue;
+            const key = pairKey(source.id, link.to);
+            const entries = displayed.get(key) ?? [];
+            entries.push({ node: source, index });
+            displayed.set(key, entries);
+            persistedEdgeIds.add(`${source.id}__${link.to}`);
+        }
+    }
+    const edges = [];
+    const executablePairs = new Set();
+    const addEdge = (edge) => {
+        const key = pairKey(edge.from, edge.to);
+        if (!executablePairs.add(key))
+            return fail(`duplicate executable leg ${edge.from} -> ${edge.to}`);
+        edges.push(edge);
+        return null;
+    };
+    for (const target of nodes) {
+        const quant = objectMap(target.extra["quant"]);
+        if (!quant)
+            return fail(`missing quantitative definition for ${target.label}`);
+        if (target.type === "stock") {
+            const initial = scalarText(quant["initial"]);
+            if (initial === null || initial.includes(":")) {
+                return fail(`missing or unsupported scalar initial for ${target.label}`);
+            }
+            const parsedInitial = parseScalarEquation(initial, labelsByLongest);
+            if (!parsedInitial.ok) {
+                return fail(`${parsedInitial.reason} in initial for ${target.label}`);
+            }
+            continue;
+        }
+        const equation = scalarText(quant["equation"]);
+        if (equation === null)
+            return fail(`missing equation for ${target.label}`);
+        const parsed = parseScalarEquation(equation, labelsByLongest);
+        if (!parsed.ok)
+            return fail(`${parsed.reason} in ${target.label}`);
+        for (const sourceId of parsed.references) {
+            if (workLimitReached())
+                return fail("loop discovery exceeded its work limit");
+            const candidates = displayed.get(pairKey(sourceId, target.id)) ?? [];
+            if (candidates.length !== 1) {
+                return fail(`equation dependency ${sourceId} -> ${target.id} has ` +
+                    `${candidates.length} displayed connectors`);
+            }
+            const entry = candidates[0];
+            const link = entry.node.links[entry.index];
+            if (link.indirect)
+                return fail(`equation dependency ${sourceId} -> ${target.id} is dashed`);
+            if (link.polarity !== "+" && link.polarity !== "-") {
+                return fail(`equation dependency ${sourceId} -> ${target.id} has unknown polarity`);
+            }
+            const polarity = link.polarity === "-" ? -1 : 1;
+            const failed = addEdge({
+                from: sourceId,
+                to: target.id,
+                polarity,
+                leg: {
+                    kind: "causal",
+                    fromNodeId: sourceId,
+                    toNodeId: target.id,
+                    edgeId: `${sourceId}__${target.id}`,
+                    polarity,
+                },
+            });
+            if (failed)
+                return failed;
+        }
+    }
+    for (const flow of nodes) {
+        if (flow.type !== "flow")
+            continue;
+        const hasExplicitFlow = Object.prototype.hasOwnProperty.call(flow.extra, "flow");
+        const explicitSpec = flowOf(flow);
+        if (hasExplicitFlow && !explicitSpec) {
+            return fail(`flow ${flow.label} has malformed explicit material endpoints`);
+        }
+        if (!hasExplicitFlow) {
+            for (const link of flow.links) {
+                if (byId.get(link.to)?.type !== "stock")
+                    continue;
+                if (link.indirect) {
+                    return fail(`legacy material candidate ${flow.id} -> ${link.to} is dashed`);
+                }
+                if (link.polarity !== "+" && link.polarity !== "-") {
+                    return fail(`legacy material candidate ${flow.id} -> ${link.to} has unknown polarity`);
+                }
+            }
+        }
+        // Use the same canonical endpoint resolution as SFD painting. This keeps
+        // older, supported flow->stock material links resolvable without inventing
+        // topology, while resolveFlowSpec still rejects ambiguous legacy shapes.
+        const spec = explicitSpec ?? resolveFlowSpec(flow, byId);
+        if (!spec)
+            return fail(`flow ${flow.label} lacks resolvable material endpoints`);
+        const validation = validateFlowEndpoints(spec.from, spec.to, byId);
+        if (!validation.ok)
+            return fail(`invalid material endpoints for ${flow.label}: ${validation.error}`);
+        const touches = [];
+        if (!isCloud(spec.from))
+            touches.push({ stockId: spec.from, polarity: -1 });
+        if (!isCloud(spec.to))
+            touches.push({ stockId: spec.to, polarity: 1 });
+        for (const touch of touches) {
+            if (workLimitReached())
+                return fail("loop discovery exceeded its work limit");
+            const candidates = displayed.get(pairKey(flow.id, touch.stockId)) ?? [];
+            let cldEdgeId;
+            if (candidates.length === 0) {
+                cldEdgeId = uniqueProjectionId(flow.id, touch.stockId, persistedEdgeIds);
+            }
+            else if (candidates.length === 1) {
+                const entry = candidates[0];
+                const link = entry.node.links[entry.index];
+                const declared = link.polarity === "-" ? -1 : link.polarity === "+" ? 1 : 0;
+                if (link.indirect || declared !== touch.polarity) {
+                    return fail(`material leg ${flow.id} -> ${touch.stockId} has a ` +
+                        "dashed, conflicting, or unknown displayed connector");
+                }
+                cldEdgeId = `${flow.id}__${touch.stockId}`;
+            }
+            else {
+                return fail(`material leg ${flow.id} -> ${touch.stockId} has duplicate displayed connectors`);
+            }
+            const failed = addEdge({
+                from: flow.id,
+                to: touch.stockId,
+                polarity: touch.polarity,
+                leg: {
+                    kind: "material",
+                    fromNodeId: flow.id,
+                    toNodeId: touch.stockId,
+                    flowId: flow.id,
+                    stockId: touch.stockId,
+                    cldEdgeId,
+                    polarity: touch.polarity,
+                },
+            });
+            if (failed)
+                return failed;
+        }
+    }
+    const adjacency = new Map();
+    for (const id of byId.keys())
+        adjacency.set(id, []);
+    for (const edge of edges)
+        adjacency.get(edge.from)?.push(edge);
+    for (const outgoing of adjacency.values()) {
+        outgoing.sort((a, b) => a.to.localeCompare(b.to) || a.leg.kind.localeCompare(b.leg.kind));
+    }
+    const quantByKey = new Map();
+    const orderedIds = [...byId.keys()].sort();
+    for (const start of orderedIds) {
+        const nodeStack = [start];
+        const legStack = [];
+        const onPath = new Set([start]);
+        let discoveryFailure = null;
+        const dfs = (current, product) => {
+            if (discoveryFailure)
+                return;
+            for (const edge of adjacency.get(current) ?? []) {
+                if (workLimitReached()) {
+                    discoveryFailure = "loop discovery exceeded its work limit";
+                    return;
+                }
+                if (edge.to === start) {
+                    if (nodeStack.length < 2)
+                        continue;
+                    const canonicalNodes = canonicalDirectedCycle(nodeStack);
+                    const shift = nodeStack.indexOf(canonicalNodes[0]);
+                    const cycleLegs = [...legStack, edge.leg];
+                    const canonicalLegs = [...cycleLegs.slice(shift), ...cycleLegs.slice(0, shift)];
+                    const type = product * edge.polarity === 1
+                        ? LoopType.reinforcing
+                        : LoopType.balancing;
+                    const loop = new DetectedLoop(canonicalNodes, type, new CanvasLoopPath(canonicalLegs), "quantitative");
+                    if (quantByKey.has(loop.exactKey)) {
+                        discoveryFailure = `duplicate directed cycle ${loop.exactKey}`;
+                        return;
+                    }
+                    if (quantByKey.size >= limits.maxLoops) {
+                        discoveryFailure = "loop discovery exceeded its output limit";
+                        return;
+                    }
+                    quantByKey.set(loop.exactKey, loop);
+                    continue;
+                }
+                if (edge.to < start || onPath.has(edge.to))
+                    continue;
+                if (nodeStack.length >= limits.maxDepth) {
+                    discoveryFailure = "loop discovery exceeded its depth limit";
+                    return;
+                }
+                nodeStack.push(edge.to);
+                legStack.push(edge.leg);
+                onPath.add(edge.to);
+                dfs(edge.to, product * edge.polarity);
+                onPath.delete(edge.to);
+                legStack.pop();
+                nodeStack.pop();
+                if (discoveryFailure)
+                    return;
+            }
+        };
+        dfs(start, 1);
+        if (discoveryFailure)
+            return fail(discoveryFailure);
+    }
+    const qualitative = qualitativeOnly(nodes, qualitativeLoops, null).loops;
+    const merged = [...qualitative];
+    const ambiguousQualitativeKeys = new Set(qualitative
+        .filter((loop) => loop.exactRouteAmbiguous)
+        .map((loop) => loop.key));
+    const qualitativeIndex = new Map(merged.map((loop, index) => [loop.exactKey, index]));
+    for (const quant of [...quantByKey.values()].sort((a, b) => a.nodeIds.length - b.nodeIds.length || a.exactKey.localeCompare(b.exactKey))) {
+        const compatibilityKey = new DetectedLoop(quant.nodeIds, quant.type).key;
+        if (ambiguousQualitativeKeys.has(compatibilityKey))
+            continue;
+        const index = qualitativeIndex.get(quant.exactKey);
+        if (index === undefined) {
+            qualitativeIndex.set(quant.exactKey, merged.length);
+            merged.push(quant);
+        }
+        else {
+            const existing = merged[index];
+            merged[index] = new DetectedLoop(existing.nodeIds, existing.type, quant.canvasPath, "qualitative");
+        }
+    }
+    return { loops: merged, analysisError: null };
+}