@dudousxd/nestjs-catalog 0.3.1 → 0.4.1

package/dist/catalog.environment.js

@@ -324,12 +324,46 @@ exports.PROMOTION_AUDIT_EVENT = 'promotion.applied';
  */
 function planPromotion(input) {
     const { from, to, source, target } = input;
-    const changes = [];
-    const blockers = [];
-    const withheld = [];
     const selected = (kind, id) => input.select === undefined || input.select.includes(`${kind}:${id}`);
-    // --- The model -------------------------------------------------------------
+    // The order changes are listed in is the order they must be applied. Workflows
+    // come before connectors deliberately: a connector arriving before the graph it
+    // runs would point at nothing for as long as the apply takes.
+    const changes = [
+        ...planObjectTypes(source, target, selected),
+        ...planTransforms(source, target, selected),
+        ...planWorkflows(source, target, to, selected),
+    ];
+    // Connectors last, and given what came before: whether a connector's transform
+    // or workflow is acceptable depends on what this same promotion is carrying.
+    const connectors = planConnectors({ source, target, from, to, selected, earlier: changes });
+    changes.push(...connectors.changes);
+    const createdAt = (input.now?.() ?? new Date()).toISOString();
+    return {
+        from,
+        to,
+        createdAt,
+        changes,
+        blockers: connectors.blockers,
+        withheld: connectors.withheld,
+        fingerprint: fingerprintOf(from, to, changes, connectors.blockers),
+    };
+}
+/**
+ * What a promotion does to one thing: creates it, updates it, or nothing.
+ *
+ * One definition rather than four copies of the same nested ternary, because
+ * "unchanged" is what the summary counts and the fingerprint filters on, and
+ * the four kinds disagreeing about it would be invisible until it mattered.
+ */
+function actionFor(existing, fields) {
+    if (!existing)
+        return 'create';
+    return fields.length ? 'update' : 'unchanged';
+}
+/** The model. A created type brings its table, and never its rows. */
+function planObjectTypes(source, target, selected) {
     const targetTypes = new Map(target.objectTypes.map((t) => [t.name, t]));
+    const changes = [];
     for (const type of source.objectTypes) {
         if (!selected('objectType', type.name))
             continue;
@@ -339,7 +373,7 @@ function planPromotion(input) {
             kind: 'objectType',
             id: type.name,
             name: type.displayName,
-            action: existing ? (fields.length ? 'update' : 'unchanged') : 'create',
+            action: actionFor(existing, fields),
             fields,
             notes: existing
                 ? []
@@ -350,8 +384,12 @@ function planPromotion(input) {
                 ],
         });
     }
-    // --- Transforms ------------------------------------------------------------
+    return changes;
+}
+/** Transforms. The target bumps its own version; see the note on `planPromotion`. */
+function planTransforms(source, target, selected) {
     const targetTransforms = new Map(target.transforms.map((t) => [t.id, t]));
+    const changes = [];
     for (const transform of source.transforms) {
         if (!selected('transform', transform.id))
             continue;
@@ -361,7 +399,7 @@ function planPromotion(input) {
             kind: 'transform',
             id: transform.id,
             name: transform.name,
-            action: existing ? (fields.length ? 'update' : 'unchanged') : 'create',
+            action: actionFor(existing, fields),
             fields,
             notes: existing && fields.length
                 ? [
@@ -370,18 +408,21 @@ function planPromotion(input) {
                 : [],
         });
     }
-    // --- Workflows -------------------------------------------------------------
-    // Before connectors, deliberately: the order changes are listed is the order
-    // they must be applied, and a connector arriving before the graph it runs
-    // would point at nothing for as long as the apply takes.
+    return changes;
+}
+/**
+ * Workflows, compared on the graph hash rather than field by field.
+ *
+ * Node positions and names are in the record but not in the hash, so moving a
+ * box on a canvas is correctly reported as nothing to release.
+ */
+function planWorkflows(source, target, to, selected) {
     const targetWorkflows = new Map((target.workflows ?? []).map((workflow) => [workflow.id, workflow]));
+    const changes = [];
     for (const workflow of source.workflows ?? []) {
         if (!selected('workflow', workflow.id))
             continue;
         const existing = targetWorkflows.get(workflow.id);
-        // Compared on the hash, not field by field: node positions and names are in
-        // the record but not in the hash, so moving a box on a canvas is correctly
-        // reported as nothing to release.
         const fields = diffFields(existing, workflow, [
             'name',
             'description',
@@ -392,7 +433,7 @@ function planPromotion(input) {
             kind: 'workflow',
             id: workflow.id,
             name: workflow.name,
-            action: existing ? (fields.length ? 'update' : 'unchanged') : 'create',
+            action: actionFor(existing, fields),
             fields,
             notes: existing && existing.graphHash !== workflow.graphHash
                 ? [
@@ -401,13 +442,24 @@ function planPromotion(input) {
                 : [],
         });
     }
-    // --- Connectors ------------------------------------------------------------
+    return changes;
+}
+/**
+ * Connectors, and everything that refuses one.
+ *
+ * The only section that produces blockers and withheld entries, because it is
+ * the only one whose subject points at other things: a connection that must
+ * already exist in the target, and code that must either be there or be in this
+ * same promotion. `earlier` is what the promotion is already carrying.
+ */
+function planConnectors(input) {
+    const { source, target, from, to, selected, earlier } = input;
     const targetConnectors = new Map(target.connectors.map((c) => [c.id, c]));
     const targetConnections = new Map(target.connections.map((c) => [c.id, c]));
-    const targetTransformIds = new Set(target.transforms.map((t) => t.id));
-    const promotedTransformIds = new Set(changes.filter((change) => change.kind === 'transform').map((change) => change.id));
-    const targetWorkflowIds = new Set((target.workflows ?? []).map((workflow) => workflow.id));
-    const promotedWorkflowIds = new Set(changes.filter((change) => change.kind === 'workflow').map((change) => change.id));
+    const known = knownCodeIds(target, earlier);
+    const changes = [];
+    const blockers = [];
+    const withheld = [];
     for (const connector of source.connectors) {
         if (!selected('connector', connector.id))
             continue;
@@ -425,79 +477,18 @@ function planPromotion(input) {
             'mode',
         ]);
         const notes = [];
-        // A connector reads through a connection, and the connection is the one
-        // thing that is genuinely per-environment. Requiring it to pre-exist is
-        // what stops a promotion from silently repointing the target at the
-        // source's database.
-        if (connector.connectionId) {
-            const match = targetConnections.get(connector.connectionId);
-            if (!match) {
-                const sourceConnection = source.connections.find((candidate) => candidate.id === connector.connectionId);
-                blockers.push({
-                    kind: 'connection',
-                    id: connector.connectionId,
-                    name: sourceConnection?.name ?? connector.connectionId,
-                    reason: `"${connector.name}" reads through connection ${connector.connectionId}, which does not exist in ${to}. Create it there, pointed at ${to}'s own system and with ${to}'s own credential, and run the preview again. A promotion will not create it: a connection is an address and a credential reference, and copying ${from}'s would point ${to} at ${from}'s data.`,
-                });
-            }
-            else {
-                withheld.push({
-                    kind: 'connection',
-                    id: match.id,
-                    name: match.name,
-                    fields: exports.PROMOTION_WITHHELD_CONNECTION_FIELDS,
-                    why: `Matched by id to ${to}'s own "${match.name}". Its address and credential stay exactly as ${to} has them.`,
-                });
-                if (match.kind !== connector.kind) {
-                    blockers.push({
-                        kind: 'connection',
-                        id: match.id,
-                        name: match.name,
-                        reason: `${to}'s connection "${match.name}" is a ${match.kind} connection, but "${connector.name}" expects a ${connector.kind} one. Same id, different kind of system — the load would fail on its first run, or worse, read something that happens to parse.`,
-                    });
-                }
-            }
-        }
-        else {
-            notes.push(`Carries its own source configuration rather than reading through a connection, so whatever address is in its config is being promoted verbatim. Check it names something ${to} should be reading.`);
-        }
-        // A connector pointing at code that is not there is a load that fails on
-        // its first scheduled run, at night, in the target — the worst place to
-        // discover it. Caught here, where somebody is looking.
-        if (connector.transformId &&
-            !targetTransformIds.has(connector.transformId) &&
-            !promotedTransformIds.has(connector.transformId)) {
-            blockers.push({
-                kind: 'connector',
-                id: connector.id,
-                name: connector.name,
-                reason: `"${connector.name}" runs transform ${connector.transformId}, which is neither in ${to} nor included in this promotion. Add it to the selection, or the connector would arrive pointing at code that does not exist.`,
-            });
-        }
-        // The same hole, one level up. A workflow is a graph of transforms, so a
-        // connector arriving without it is worse than one arriving without a
-        // transform: nothing about the load is defined at all.
-        if (connector.workflowId &&
-            !targetWorkflowIds.has(connector.workflowId) &&
-            !promotedWorkflowIds.has(connector.workflowId)) {
-            blockers.push({
-                kind: 'connector',
-                id: connector.id,
-                name: connector.name,
-                reason: `"${connector.name}" runs workflow ${connector.workflowId}, which is neither in ${to} nor included in this promotion. Promote the workflow first, or the connector would arrive pointing at a graph that does not exist.`,
-            });
-        }
-        withheld.push({
-            kind: 'connector',
-            id: connector.id,
-            name: connector.name,
-            fields: existing
-                ? exports.PROMOTION_WITHHELD_CONNECTOR_FIELDS.filter((field) => field !== 'enabled')
-                : exports.PROMOTION_WITHHELD_CONNECTOR_FIELDS,
-            why: existing
-                ? `${to} keeps its own watermark, its own run history, its own credential reference and its own enabled/disabled switch.`
-                : `Arrives disabled, with no watermark and no credential reference. Point it at ${to}'s secret and enable it when somebody is watching.`,
+        checkConnectorConnection({
+            connector,
+            source,
+            targetConnections,
+            from,
+            to,
+            blockers,
+            withheld,
+            notes,
         });
+        checkConnectorCode({ connector, known, to, blockers });
+        withheld.push(connectorWithheld(connector, existing !== undefined, to));
         if (!existing) {
             notes.push('Arrives disabled. Enable it in the target once its connection has been checked.');
         }
@@ -505,20 +496,107 @@ function planPromotion(input) {
             kind: 'connector',
             id: connector.id,
             name: connector.name,
-            action: existing ? (fields.length ? 'update' : 'unchanged') : 'create',
+            action: actionFor(existing, fields),
             fields,
             notes,
         });
     }
-    const createdAt = (input.now?.() ?? new Date()).toISOString();
+    return { changes, blockers, withheld };
+}
+/**
+ * That the connector's connection exists in the target, and is the same kind.
+ *
+ * A connector reads through a connection, and the connection is the one thing
+ * that is genuinely per-environment. Requiring it to pre-exist is what stops a
+ * promotion from silently repointing the target at the source's database.
+ */
+function checkConnectorConnection(input) {
+    const { connector, source, targetConnections, from, to, blockers, withheld, notes } = input;
+    if (!connector.connectionId) {
+        notes.push(`Carries its own source configuration rather than reading through a connection, so whatever address is in its config is being promoted verbatim. Check it names something ${to} should be reading.`);
+        return;
+    }
+    const match = targetConnections.get(connector.connectionId);
+    if (!match) {
+        const sourceConnection = source.connections.find((candidate) => candidate.id === connector.connectionId);
+        blockers.push({
+            kind: 'connection',
+            id: connector.connectionId,
+            name: sourceConnection?.name ?? connector.connectionId,
+            reason: `"${connector.name}" reads through connection ${connector.connectionId}, which does not exist in ${to}. Create it there, pointed at ${to}'s own system and with ${to}'s own credential, and run the preview again. A promotion will not create it: a connection is an address and a credential reference, and copying ${from}'s would point ${to} at ${from}'s data.`,
+        });
+        return;
+    }
+    withheld.push({
+        kind: 'connection',
+        id: match.id,
+        name: match.name,
+        fields: exports.PROMOTION_WITHHELD_CONNECTION_FIELDS,
+        why: `Matched by id to ${to}'s own "${match.name}". Its address and credential stay exactly as ${to} has them.`,
+    });
+    if (match.kind !== connector.kind) {
+        blockers.push({
+            kind: 'connection',
+            id: match.id,
+            name: match.name,
+            reason: `${to}'s connection "${match.name}" is a ${match.kind} connection, but "${connector.name}" expects a ${connector.kind} one. Same id, different kind of system — the load would fail on its first run, or worse, read something that happens to parse.`,
+        });
+    }
+}
+/**
+ * That the code a connector runs will be there when it arrives.
+ *
+ * A connector pointing at code that is not there is a load that fails on its
+ * first scheduled run, at night, in the target — the worst place to discover it.
+ * Caught here, where somebody is looking. Either the target already has it, or
+ * this promotion is carrying it.
+ */
+function checkConnectorCode(input) {
+    const { connector, known, to, blockers } = input;
+    const { transformId, workflowId } = connector;
+    if (transformId &&
+        !known.transforms.has(transformId) &&
+        !known.arrivingTransforms.has(transformId)) {
+        blockers.push({
+            kind: 'connector',
+            id: connector.id,
+            name: connector.name,
+            reason: `"${connector.name}" runs transform ${transformId}, which is neither in ${to} nor included in this promotion. Add it to the selection, or the connector would arrive pointing at code that does not exist.`,
+        });
+    }
+    // The same hole, one level up. A workflow is a graph of transforms, so a
+    // connector arriving without it is worse than one arriving without a
+    // transform: nothing about the load is defined at all.
+    if (workflowId && !known.workflows.has(workflowId) && !known.arrivingWorkflows.has(workflowId)) {
+        blockers.push({
+            kind: 'connector',
+            id: connector.id,
+            name: connector.name,
+            reason: `"${connector.name}" runs workflow ${workflowId}, which is neither in ${to} nor included in this promotion. Promote the workflow first, or the connector would arrive pointing at a graph that does not exist.`,
+        });
+    }
+}
+function knownCodeIds(target, earlier) {
+    const arriving = (kind) => new Set(earlier.filter((change) => change.kind === kind).map((change) => change.id));
     return {
-        from,
-        to,
-        createdAt,
-        changes,
-        blockers,
-        withheld,
-        fingerprint: fingerprintOf(from, to, changes, blockers),
+        transforms: new Set(target.transforms.map((t) => t.id)),
+        arrivingTransforms: arriving('transform'),
+        workflows: new Set((target.workflows ?? []).map((workflow) => workflow.id)),
+        arrivingWorkflows: arriving('workflow'),
+    };
+}
+/** What the target keeps for itself when a connector lands on it. */
+function connectorWithheld(connector, exists, to) {
+    return {
+        kind: 'connector',
+        id: connector.id,
+        name: connector.name,
+        fields: exists
+            ? exports.PROMOTION_WITHHELD_CONNECTOR_FIELDS.filter((field) => field !== 'enabled')
+            : exports.PROMOTION_WITHHELD_CONNECTOR_FIELDS,
+        why: exists
+            ? `${to} keeps its own watermark, its own run history, its own credential reference and its own enabled/disabled switch.`
+            : `Arrives disabled, with no watermark and no credential reference. Point it at ${to}'s secret and enable it when somebody is watching.`,
     };
 }
 /** Whether a plan may be applied at all. */
@@ -568,7 +646,7 @@ function fingerprintOf(from, to, changes, blockers) {
  */
 function stable(value) {
     if (value === undefined)
-        return 'undefined';
+        return '\u0000undefined';
     if (value === null)
         return 'null';
     if (Array.isArray(value))

package/dist/catalog.pipeline.js

@@ -208,6 +208,40 @@ function validateWorkflow(graph) {
             },
         ];
     }
+    const byId = collectNodesById(nodes, issues);
+    checkEdges(edges, byId, issues);
+    // Reachability and cycles are only meaningful once the graph is structurally
+    // sound. See the note on this function.
+    if (issues.length > 0)
+        return issues;
+    const { outgoing, incoming } = buildAdjacency(nodes, edges);
+    const sources = nodes.filter((node) => node.kind === 'source');
+    const sinks = nodes.filter((node) => node.kind === 'sink');
+    checkNodeWiring(nodes, incoming, outgoing, issues);
+    checkEndpoints(sources, sinks, issues);
+    const looped = findCycle(nodes, incoming, outgoing);
+    if (looped) {
+        issues.push({
+            code: 'cycle',
+            nodeIds: looped,
+            message: `These nodes form a cycle: ${looped.join(' → ')}. A graph that loops has no order to run in and no point at which the load is finished, so it is refused rather than run until something times out.`,
+        });
+        // Reachability over a cyclic graph reports nodes as unreachable that are
+        // only unreachable *because* of the cycle, which points at the wrong boxes.
+        return issues;
+    }
+    checkReachability(nodes, sources, sinks, incoming, outgoing, issues);
+    return issues;
+}
+/**
+ * Index the nodes by id, reporting the ids that cannot be used as one.
+ *
+ * A node with an unusable id is still indexed, deliberately. Leaving it out
+ * would make every edge touching it report a *missing node* as well, which
+ * sends the reader looking for a node they can see on the canvas. One problem,
+ * one message.
+ */
+function collectNodesById(nodes, issues) {
     const byId = new Map();
     for (const node of nodes) {
         if (!exports.WORKFLOW_NODE_ID_PATTERN.test(node.id)) {
@@ -216,9 +250,6 @@ function validateWorkflow(graph) {
                 nodeIds: [node.id],
                 message: `Node id "${node.id}" is not usable. Ids may be 1-64 characters of letters, digits, underscore or hyphen: the id becomes a durable step name and part of the key its staged rows are stored under, and neither can carry arbitrary text safely.`,
             });
-            // Registered anyway, deliberately. Leaving it out would make every edge
-            // touching it report a *missing node* as well, which sends the reader
-            // looking for a node they can see on the canvas. One problem, one message.
         }
         if (byId.has(node.id)) {
             issues.push({
@@ -230,6 +261,10 @@ function validateWorkflow(graph) {
         }
         byId.set(node.id, node);
     }
+    return byId;
+}
+/** Wires that name a node which is not there, loop back on themselves, or repeat. */
+function checkEdges(edges, byId, issues) {
     const seenEdges = new Set();
     for (const edge of edges) {
         if (!byId.has(edge.from) || !byId.has(edge.to)) {
@@ -260,10 +295,9 @@ function validateWorkflow(graph) {
         }
         seenEdges.add(key);
     }
-    // Reachability and cycles are only meaningful once the graph is structurally
-    // sound. See the note on this function.
-    if (issues.length > 0)
-        return issues;
+}
+/** Both directions of the edge list, with an entry for every node. */
+function buildAdjacency(nodes, edges) {
     const outgoing = new Map();
     const incoming = new Map();
     for (const node of nodes) {
@@ -274,13 +308,11 @@ function validateWorkflow(graph) {
         outgoing.get(edge.from)?.push(edge.to);
         incoming.get(edge.to)?.push(edge.from);
     }
-    const sources = [];
-    const sinks = [];
+    return { outgoing, incoming };
+}
+/** What each kind of node may and may not have wired to it. */
+function checkNodeWiring(nodes, incoming, outgoing, issues) {
     for (const node of nodes) {
-        if (node.kind === 'source')
-            sources.push(node);
-        if (node.kind === 'sink')
-            sinks.push(node);
         if (node.kind === 'source' && (incoming.get(node.id)?.length ?? 0) > 0) {
             issues.push({
                 code: 'source-has-input',
@@ -303,6 +335,20 @@ function validateWorkflow(graph) {
             });
         }
     }
+}
+/**
+ * That the graph has both ends, and that no two sinks claim the same type.
+ *
+ * Several sinks are allowed, and the reason is the point of having a graph at
+ * all: one expensive read feeding several outputs. Forbidding it would mean
+ * pulling the same ten million rows twice to derive two types from them.
+ *
+ * What is refused is two sinks writing the *same* type. Each sink commits its
+ * own type independently — there is no distributed transaction here and the
+ * model does not pretend otherwise — but two snapshots of one type in one run
+ * leaves nothing to say which of them the readers should get.
+ */
+function checkEndpoints(sources, sinks, issues) {
     if (sources.length === 0) {
         issues.push({
             code: 'no-source',
@@ -317,14 +363,6 @@ function validateWorkflow(graph) {
             message: 'This workflow has no sink node. A workflow ends at a sink, because the sink is what writes and commits — without one the graph computes rows and throws them away.',
         });
     }
-    // Several sinks are allowed, and the reason is the point of having a graph at
-    // all: one expensive read feeding several outputs. Forbidding it would mean
-    // pulling the same ten million rows twice to derive two types from them.
-    //
-    // What is refused is two sinks writing the *same* type. Each sink commits its
-    // own type independently — there is no distributed transaction here and the
-    // model does not pretend otherwise — but two snapshots of one type in one run
-    // leaves nothing to say which of them the readers should get.
     const byTargetType = new Map();
     for (const sink of sinks) {
         const sharing = byTargetType.get(sink.targetType) ?? [];
@@ -342,8 +380,14 @@ function validateWorkflow(graph) {
                 .join(' and ')} both commit ${targetType}. Two snapshots of one type in a single run leaves nothing to say which one readers should get — wire these branches into one sink, or send them to different types.`,
         });
     }
-    // Cycles, by Kahn's algorithm: whatever is left with a non-zero in-degree
-    // after the queue drains is on one.
+}
+/**
+ * The nodes actually on a cycle, or nothing if the graph is acyclic.
+ *
+ * Kahn's algorithm: whatever is left with a non-zero in-degree after the queue
+ * drains is on one.
+ */
+function findCycle(nodes, incoming, outgoing) {
     const indegree = new Map();
     for (const node of nodes) {
         indegree.set(node.id, incoming.get(node.id)?.length ?? 0);
@@ -362,35 +406,38 @@ function validateWorkflow(graph) {
                 queue.push(next);
         }
     }
-    if (ordered.length !== nodes.length) {
-        // What Kahn's algorithm leaves behind is the cycle *plus* everything
-        // downstream of it, because those never had their in-degree resolved
-        // either. Naming all of it would point at nodes that are perfectly well
-        // wired and merely stuck behind the loop, and a message that names the
-        // wrong node is worse than a vague one. Peeling off nodes with no outgoing
-        // edge inside the leftover set, repeatedly, strips exactly those tails and
-        // leaves the nodes actually on the loop.
-        const stuck = new Set(nodes.filter((node) => !ordered.includes(node.id)).map((node) => node.id));
-        for (let peeled = true; peeled;) {
-            peeled = false;
-            for (const id of stuck) {
-                const continues = (outgoing.get(id) ?? []).some((next) => stuck.has(next));
-                if (continues)
-                    continue;
-                stuck.delete(id);
-                peeled = true;
-            }
+    if (ordered.length === nodes.length)
+        return undefined;
+    const leftover = new Set(nodes.filter((node) => !ordered.includes(node.id)).map((node) => node.id));
+    return [...peelTails(leftover, outgoing)];
+}
+/**
+ * Strip the nodes that are merely stuck behind a loop, leaving the loop itself.
+ *
+ * What Kahn's algorithm leaves behind is the cycle *plus* everything downstream
+ * of it, because those never had their in-degree resolved either. Naming all of
+ * it would point at nodes that are perfectly well wired and merely waiting on
+ * the loop, and a message that names the wrong node is worse than a vague one.
+ * Removing nodes with no outgoing edge *inside the set*, repeatedly, strips
+ * exactly those tails: a node on the cycle always has one.
+ *
+ * Mutates and returns the set it was given, which is a local built for this.
+ */
+function peelTails(leftover, outgoing) {
+    for (let peeled = true; peeled;) {
+        peeled = false;
+        for (const id of leftover) {
+            const continues = (outgoing.get(id) ?? []).some((next) => leftover.has(next));
+            if (continues)
+                continue;
+            leftover.delete(id);
+            peeled = true;
         }
-        const looped = [...stuck];
-        issues.push({
-            code: 'cycle',
-            nodeIds: looped,
-            message: `These nodes form a cycle: ${looped.join(' → ')}. A graph that loops has no order to run in and no point at which the load is finished, so it is refused rather than run until something times out.`,
-        });
-        // Reachability over a cyclic graph reports nodes as unreachable that are
-        // only unreachable *because* of the cycle, which points at the wrong boxes.
-        return issues;
     }
+    return leftover;
+}
+/** Nodes that no source reaches, and nodes that reach no sink. */
+function checkReachability(nodes, sources, sinks, incoming, outgoing, issues) {
     const reachableFromSources = walk(sources.map((node) => node.id), outgoing);
     const reachesASink = walk(sinks.map((sink) => sink.id), incoming);
     for (const node of nodes) {
@@ -410,7 +457,6 @@ function validateWorkflow(graph) {
             });
         }
     }
-    return issues;
 }
 /** Breadth-first reachability over one adjacency map. */
 function walk(roots, adjacency) {
@@ -447,16 +493,11 @@ function workflowRunOrder(graph) {
         throw new Error(`Refusing to order an invalid workflow: ${issues.map((issue) => issue.message).join(' ')}`);
     }
     const byId = new Map(graph.nodes.map((node) => [node.id, node]));
-    const indegree = new Map();
-    const outgoing = new Map();
-    for (const node of graph.nodes) {
-        indegree.set(node.id, 0);
-        outgoing.set(node.id, []);
-    }
-    for (const edge of graph.edges) {
-        indegree.set(edge.to, (indegree.get(edge.to) ?? 0) + 1);
-        outgoing.get(edge.from)?.push(edge.to);
-    }
+    // The same adjacency the validator walks, from the same builder. Two copies of
+    // "what is wired into what" is exactly how a graph that validated comes out
+    // executing differently, which is the thing this function's contract rules out.
+    const { outgoing, incoming } = buildAdjacency(graph.nodes, graph.edges);
+    const indegree = new Map(graph.nodes.map((node) => [node.id, incoming.get(node.id)?.length ?? 0]));
     const ready = graph.nodes.filter((node) => indegree.get(node.id) === 0).map((node) => node.id);
     const order = [];
     while (ready.length > 0) {
@@ -468,9 +509,9 @@ function workflowRunOrder(graph) {
             continue;
         // Edge order, not node order: this is the array a merge reads its inputs
         // from, and it is part of the fingerprint precisely because it is visible in
-        // the output.
-        const inputs = graph.edges.filter((edge) => edge.to === id).map((edge) => edge.from);
-        order.push({ node, inputs });
+        // the output. `buildAdjacency` fills `incoming` by walking the edges in
+        // order, so that is what this already is.
+        order.push({ node, inputs: [...(incoming.get(id) ?? [])] });
         for (const next of outgoing.get(id) ?? []) {
             const remaining = (indegree.get(next) ?? 0) - 1;
             indegree.set(next, remaining);

package/dist/catalog.registry.js

@@ -296,10 +296,7 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
                 return;
             const fromDecorator = declaredProps[prop.name];
             const fromOverlay = overlayProps[prop.name];
-            const displayName = fromOverlay?.displayName ?? fromDecorator?.displayName ?? humanize(prop.name);
-            const description = fromOverlay?.description ?? fromDecorator?.description;
-            const hidden = fromOverlay?.hidden ?? fromDecorator?.hidden ?? false;
-            const order = fromOverlay?.order ?? fromDecorator?.order ?? index;
+            const { displayName, description, hidden, order } = resolveFieldPresentation(prop.name, index, fromDecorator, fromOverlay);
             if (isRelationKind(prop.kind)) {
                 relations.push({
                     name: prop.name,
@@ -357,3 +354,19 @@ exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry = MikroOrmCatalogRegis
     __param(2, (0, common_1.Inject)(catalog_overlay_store_token_1.CATALOG_OVERLAY_STORE)),
     __metadata("design:paramtypes", [core_1.MikroORM, Object, Object])
 ], MikroOrmCatalogRegistry);
+/**
+ * How one field is presented, resolved across the tiers.
+ *
+ * Overlay beats decorator beats a derived default, the same precedence the
+ * type-level fields use. Split out of `buildType` because it is the one job in
+ * that loop which is identical whether the field turns out to be a scalar or a
+ * relation — both branches consume exactly this.
+ */
+function resolveFieldPresentation(name, index, fromDecorator, fromOverlay) {
+    return {
+        displayName: fromOverlay?.displayName ?? fromDecorator?.displayName ?? humanize(name),
+        description: fromOverlay?.description ?? fromDecorator?.description,
+        hidden: fromOverlay?.hidden ?? fromDecorator?.hidden ?? false,
+        order: fromOverlay?.order ?? fromDecorator?.order ?? index,
+    };
+}

package/dist/catalog.types.d.ts

@@ -23,7 +23,20 @@ export interface CatalogPropertyDef {
     name: string;
     /** Human label. Tier 0: editable at runtime, no migration. */
     displayName: string;
-    /** What this field means in the business. Tier 0. */
+    /**
+     * What this field means in the business. Tier 0.
+     *
+     * **Markdown**, since the console started editing it as rich text. Plain text
+     * is still valid markdown, so anything written before — or declared by a
+     * decorator — is unchanged and renders as itself.
+     *
+     * Consumers that print it raw keep working: the worst they will see is
+     * `**bold**`, which reads. That is the whole reason it is not HTML — `<strong>`
+     * in a tooltip is noise, and a consumer that decided to render it as HTML
+     * would have an injection point. Render it with a markdown renderer if you
+     * want the formatting; `RichTextView` in `@dudousxd/nestjs-catalog-react` is
+     * the one this console uses.
+     */
     description?: string;
     type: ScalarType;
     /** The physical column. Derived from the ORM; shown so engineers can trace it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-catalog",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "A metadata registry for NestJS: object types, properties and relations, derived from your ORM and enriched with decorators.",
   "license": "MIT",
   "author": "Davide Carvalho",