@dudousxd/nestjs-catalog 0.15.0 → 0.16.0-preview.0

package/dist/catalog.pipeline.js

@@ -9,15 +9,25 @@
  * systems each believing they decide when a load runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_CALL_CONTRACT = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
+exports.REDACTED_SECRET = exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_CALL_CONTRACT = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_BRANCH_LABELS = exports.WORKFLOW_PREDICATE_KINDS = exports.WORKFLOW_ROW_GAP = exports.WORKFLOW_COLUMN_GAP = exports.WORKFLOW_NODE_HEIGHT = exports.WORKFLOW_NODE_WIDTH = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_SKIP_REASONS = exports.CODE_CONTEXT_CONTRACT = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
 exports.isConnectorKind = isConnectorKind;
 exports.isTransformLanguage = isTransformLanguage;
+exports.isWorkflowSkipReason = isWorkflowSkipReason;
 exports.isWorkflowNodeKind = isWorkflowNodeKind;
+exports.unreachableNodeKind = unreachableNodeKind;
+exports.workflowColumnX = workflowColumnX;
+exports.workflowRowY = workflowRowY;
+exports.isWorkflowPredicateKind = isWorkflowPredicateKind;
+exports.unreachablePredicateKind = unreachablePredicateKind;
+exports.isWorkflowIfPredicate = isWorkflowIfPredicate;
+exports.isWorkflowBranchLabel = isWorkflowBranchLabel;
 exports.isWorkflowStatus = isWorkflowStatus;
 exports.isWorkflowExecutionMode = isWorkflowExecutionMode;
 exports.readWorkflowCallOutput = readWorkflowCallOutput;
+exports.callableWorkflowBlock = callableWorkflowBlock;
 exports.validateWorkflow = validateWorkflow;
 exports.workflowRunOrder = workflowRunOrder;
+exports.workflowNodeRuns = workflowNodeRuns;
 exports.workflowGraphHash = workflowGraphHash;
 exports.isWorkflowNode = isWorkflowNode;
 exports.isWorkflowEdge = isWorkflowEdge;
@@ -68,6 +78,39 @@ function isTransformLanguage(value) {
     return exports.TRANSFORM_LANGUAGES.some((language) => language === value);
 }
 exports.TRANSFORM_RUNNER = Symbol('TRANSFORM_RUNNER');
+/**
+ * The number in {@link CatalogCodeContext.contract}.
+ *
+ * Its own version, separate from {@link WORKFLOW_CALL_CONTRACT}, because the
+ * two travel to different places for different reasons — a call envelope
+ * crosses to another SDK over the durable wire, a code context crosses to a
+ * child process this repository spawned — and a transform written against one
+ * has to be able to say which it read.
+ */
+exports.CODE_CONTEXT_CONTRACT = 1;
+/**
+ * Why a `skipped` node did not run, when there is more to say than "the run
+ * stopped".
+ *
+ * **One entry, and the omission is the point.** `skipped` already meant one
+ * thing before branches existed — the run failed upstream and never reached
+ * this node — and every outcome ever stored records that meaning by *not*
+ * carrying a reason. Adding `run-stopped` to this list would not describe those
+ * rows, it would leave them describing an unknown reason, so the pre-existing
+ * meaning stays the absent one and this names only the new fact: the node is on
+ * a branch an {@link WorkflowIfNode} did not take.
+ *
+ * The distinction is not cosmetic. A sink skipped by a branch **committed
+ * nothing and left the live snapshot alone**, which is a correct, successful
+ * outcome; a sink skipped by a failure is part of a load that went wrong. A run
+ * panel that rendered both as "did not run" would answer "why is there no data
+ * in X" with the same shrug in both cases.
+ */
+exports.WORKFLOW_SKIP_REASONS = ['branch-not-taken'];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowSkipReason(value) {
+    return exports.WORKFLOW_SKIP_REASONS.some((reason) => reason === value);
+}
 /* ---------------------------------------------------------------------------
  * Workflows: a graph of steps that ends in exactly one commit.
  *
@@ -108,9 +151,12 @@ exports.TRANSFORM_RUNNER = Symbol('TRANSFORM_RUNNER');
  *   It needs no new execution path, only a different body, and adding the kind
  *   would mean two ways to drop rows and two places to look when rows go
  *   missing.
- * - **branch / split** — already expressible: a node with two outbound edges is
- *   read by both successors, each of which filters differently. There is
- *   nothing for a branch node to *do*.
+ * - **branch / split (unconditional)** — already expressible, and still is: a
+ *   node with two outbound edges is read by both successors, each of which
+ *   filters differently. There is nothing for an *unconditional* split to do.
+ *   {@link WorkflowIfNode} is the conditional one, and it earns its kind by
+ *   doing something no wiring can express — deciding that one of those
+ *   successors, and everything only it feeds, does not run at all.
  * - **merge / join** — a node with several inbound edges receives its inputs
  *   concatenated in edge order (see {@link WorkflowEdge}). A keyed join is then
  *   ordinary code inside the transform, which can already see every record.
@@ -136,11 +182,38 @@ exports.WORKFLOW_NODE_KINDS = [
     'sink',
     /** Hands this position to an existing durable workflow. See {@link WorkflowCallNode}. */
     'call',
+    /** Sends the rows down one of its outbound branches. See {@link WorkflowIfNode}. */
+    'if',
 ];
 /** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
 function isWorkflowNodeKind(value) {
     return exports.WORKFLOW_NODE_KINDS.some((kind) => kind === value);
 }
+/**
+ * The kind that never compiles quietly.
+ *
+ * Every place that decides something *per kind* ends in a call to this, so a
+ * kind added to {@link WORKFLOW_NODE_KINDS} without a branch there is a type
+ * error naming the file rather than a graph that saves, validates, draws and
+ * then does the wrong thing. This codebase has been bitten by exactly that
+ * shape — a `toGraph` branch forgetting a field, a node-kind map missing a kind
+ * — and the fix each time was to make the omission impossible rather than to
+ * remember harder.
+ *
+ * It throws as well as failing to compile, because the narrowing that reaches
+ * it is over data that arrives as JSON: a node whose `kind` passed
+ * {@link isWorkflowNodeKind} in an older build and reaches a newer one is
+ * possible, and returning a default for it would be the silent path this exists
+ * to close.
+ */
+function unreachableNodeKind(node, where) {
+    // Takes either the node or its kind, because the call sites differ: a
+    // narrowing chain over a union hands it the node, while one over the kind
+    // string — which is what a boundary reading JSON has before it has a node —
+    // hands it the string.
+    const kind = typeof node === 'string' ? node : Reflect.get(Object(node), 'kind');
+    throw new Error(`${where} does not handle a workflow node of kind ${JSON.stringify(kind)}. The kind list and every decision made per kind are meant to move together.`);
+}
 /**
  * The longest a node id may be, and the alphabet it may use.
  *
@@ -152,6 +225,160 @@ function isWorkflowNodeKind(value) {
  * separator would let one node read another's rows.
  */
 exports.WORKFLOW_NODE_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * How big a node is on the canvas, and therefore how far apart two of them have
+ * to be.
+ *
+ * ## Why the server owns a number about pixels
+ *
+ * Because the server *writes positions*. `adoptConnector` lays a connector out
+ * as a graph, and anything else that mints a graph without a person drawing it —
+ * a promotion, a template, a script — has the same job. A writer that does not
+ * know how wide a node is can only guess, and the guess was wrong: adoption used
+ * to place columns 220 apart against a node 224 wide, so every adopted graph
+ * drew each box overlapping the next by four pixels. Nothing was stacked and
+ * nothing was missing, so it read as boxes glued together rather than as a bug,
+ * and it survived until somebody opened thirteen of them.
+ *
+ * The fix is not a bigger number. 220 was not too small, it was **derived from
+ * nothing** — it had no relationship to the width it was supposed to clear, so
+ * it was only ever correct by luck and would go wrong again the next time the
+ * node's styling changed. These constants are the relationship, stated once, in
+ * the one package both the writer and the canvas already depend on.
+ *
+ * ## What pins them to the drawing
+ *
+ * {@link WORKFLOW_NODE_WIDTH} is not a description of the node — it is the
+ * *source of* the node's width. `WorkflowNodeBody` in
+ * `@dudousxd/nestjs-catalog-react` sets its own width from this constant rather
+ * than from a Tailwind class, so the two cannot drift: changing this changes the
+ * box, and there is no second number to forget.
+ */
+exports.WORKFLOW_NODE_WIDTH = 224;
+/** How tall a node is. The other half of {@link WORKFLOW_NODE_WIDTH}'s contract. */
+exports.WORKFLOW_NODE_HEIGHT = 80;
+/**
+ * Clear space between one column and the next, on top of the node's own width.
+ *
+ * Wide enough for the edge between two nodes to be read as a line with a
+ * direction rather than as a join. This is the part that is taste; the width it
+ * is added to is not.
+ */
+exports.WORKFLOW_COLUMN_GAP = 96;
+/** Clear space between two nodes sharing a column. */
+exports.WORKFLOW_ROW_GAP = 32;
+/**
+ * The x of the nth column, counting from zero.
+ *
+ * Every generator of a layout goes through this rather than multiplying by a
+ * literal, which is what makes "columns never overlap" a property of one
+ * function instead of a coincidence repeated at each call site.
+ */
+function workflowColumnX(column) {
+    return column * (exports.WORKFLOW_NODE_WIDTH + exports.WORKFLOW_COLUMN_GAP);
+}
+/** The y of the nth row within a column, counting from zero. */
+function workflowRowY(row) {
+    return row * (exports.WORKFLOW_NODE_HEIGHT + exports.WORKFLOW_ROW_GAP);
+}
+/**
+ * The kinds of test an {@link WorkflowIfNode} can make.
+ *
+ * A second predicate shape was always going to arrive — the note on
+ * {@link WorkflowIfNode} says so about `code` — and the shape it arrives into is
+ * the decision worth arguing about, because the alternative was to keep both
+ * tests' fields flat on the node and mark them optional. That version types a
+ * gate as "an env var, maybe, and a threshold, maybe": a node carrying both is
+ * representable, a node carrying neither is representable, and every reader has
+ * to invent its own rule for which one wins. It is the same mistake the note on
+ * {@link WorkflowNode} refuses for node kinds, one level down.
+ *
+ * So the predicate is a union with a discriminant of its own, and every decision
+ * made per predicate kind ends in {@link unreachablePredicateKind} — a third
+ * shape is then a build failure listing the files that have to answer for it,
+ * rather than a gate that saves, draws, and quietly always takes the `else`.
+ */
+exports.WORKFLOW_PREDICATE_KINDS = [
+    /** Reads a variable where the load runs. See {@link WorkflowEnvPredicate}. */
+    'env',
+    /** Counts the rows handed to the gate. See {@link WorkflowRowCountPredicate}. */
+    'rowCount',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowPredicateKind(value) {
+    return exports.WORKFLOW_PREDICATE_KINDS.some((kind) => kind === value);
+}
+/**
+ * {@link unreachableNodeKind}, one level down, and for the identical reason.
+ *
+ * Every branch over {@link WorkflowIfPredicate} ends here, so a predicate kind
+ * added to the list without a rule for hashing it, validating it or evaluating
+ * it is a type error naming the file — not a graph that runs and decides
+ * something nobody authored. It throws as well, because predicates arrive as
+ * JSON out of a column and a build older than the data is a thing that happens.
+ */
+function unreachablePredicateKind(predicate, where) {
+    const kind = typeof predicate === 'string' ? predicate : Reflect.get(Object(predicate), 'kind');
+    throw new Error(`${where} does not handle an if-node predicate of kind ${JSON.stringify(kind)}. The predicate kinds and every decision made per kind are meant to move together.`);
+}
+/**
+ * Narrow a stored predicate, for the same reason {@link isWorkflowNode} narrows
+ * a stored node: it arrives as JSON out of a column, and a gate read back
+ * without its test is a gate that has to invent one.
+ *
+ * A row count that is not a whole number — `NaN` from a JSON round trip of an
+ * unparsed field, an `Infinity` that serialised as `null` — is refused rather
+ * than kept, because every comparison against it is false and the symptom is a
+ * `then` branch that silently never runs again.
+ */
+function isWorkflowIfPredicate(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const kind = Reflect.get(value, 'kind');
+    if (!isWorkflowPredicateKind(kind))
+        return false;
+    if (kind === 'env') {
+        // The variable name is required and its expected value is not, exactly as
+        // the type says: an absent `equals` is the "is it set at all" test, so a
+        // stored predicate without one is complete rather than half-narrowed.
+        const equals = Reflect.get(value, 'equals');
+        return (typeof Reflect.get(value, 'envVar') === 'string' &&
+            (equals === undefined || typeof equals === 'string'));
+    }
+    if (kind === 'rowCount') {
+        const atLeast = Reflect.get(value, 'atLeast');
+        return typeof atLeast === 'number' && Number.isInteger(atLeast) && atLeast >= 0;
+    }
+    return isWorkflowPredicateKindUnhandled(kind);
+}
+/** The narrowing counterpart of {@link unreachablePredicateKind}. */
+function isWorkflowPredicateKindUnhandled(kind) {
+    void kind;
+    return false;
+}
+/**
+ * Which side of an {@link WorkflowIfNode} a wire leaves by.
+ *
+ * **Two closed values rather than free-form labels**, which was the other design
+ * and is worse in the one way that matters here: an unlabelled branch is a
+ * branch that never runs, and a *misspelled* branch is one too. With a free
+ * string, `thn` is a subtree that silently never executes and a graph that
+ * validates perfectly; with these, it is refused at the boundary and is a type
+ * error in the console. The failure a branch introduces is "nothing loaded and
+ * nothing complained", so the vocabulary is the place to make it impossible.
+ *
+ * An N-way `switch` node was considered and is deliberately not this: it would
+ * have to carry its own case list plus a default, the cases would have to be
+ * validated against the labels, and an unmatched value would need a rule. That
+ * is a different node, and it can be added later without changing this one —
+ * because a boolean question is what a predicate answers, and an `if` is exactly
+ * the shape of a boolean question.
+ */
+exports.WORKFLOW_BRANCH_LABELS = ['then', 'else'];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowBranchLabel(value) {
+    return exports.WORKFLOW_BRANCH_LABELS.some((label) => label === value);
+}
 /**
  * An authored graph of steps ending in one commit.
  *
@@ -299,6 +526,23 @@ function isCount(value) {
 function describeCount(value) {
     return value === undefined ? 'nothing' : JSON.stringify(value);
 }
+function callableWorkflowBlock(ref) {
+    const version = typeof ref.version === 'string' ? ref.version.trim() : '';
+    if (version.length === 0) {
+        return {
+            code: 'no-version',
+            message: `A live worker announces "${ref.name}" without saying which version it runs, which is what a worker announces before it has been upgraded to publish its registrations in full. A name with no version cannot be pinned, so this cannot be chosen — type the name and the version you mean.`,
+        };
+    }
+    const groups = ref.disagreements?.find((entry) => entry.axis === 'group')?.values ?? [];
+    if (groups.length > 1) {
+        return {
+            code: 'ambiguous-group',
+            message: `Live workers announce ${ref.name}@${version} from ${groups.length} different groups (${groups.join(', ')}), so nothing can say which queue a run would be dispatched to — or whether the two are even the same code. This cannot be chosen until the deployment stops claiming it twice.`,
+        };
+    }
+    return undefined;
+}
 /** Every way a graph can be refused. Exported so a canvas can key off the code. */
 exports.WORKFLOW_ISSUE_CODES = [
     'empty',
@@ -317,6 +561,11 @@ exports.WORKFLOW_ISSUE_CODES = [
     'dead-end',
     'transform-not-named',
     'call-not-named',
+    'if-not-named',
+    'if-threshold-invalid',
+    'if-needs-one-input',
+    'branch-not-labelled',
+    'branch-on-plain-edge',
 ];
 /**
  * Everything that makes a graph unrunnable, in one pure function.
@@ -359,6 +608,7 @@ function validateWorkflow(graph) {
     const sinks = nodes.filter((node) => node.kind === 'sink');
     checkNodeWiring(nodes, incoming, outgoing, issues);
     checkEndpoints(originators, sinks, issues);
+    checkBranches(edges, byId, issues);
     const looped = findCycle(nodes, incoming, outgoing);
     if (looped) {
         issues.push({
@@ -485,11 +735,59 @@ function checkNodeWiring(nodes, incoming, outgoing, issues) {
                 message: `Sink "${node.name}" (${node.id}) has an outbound edge. The sink commits the snapshot, so nothing can run after it.`,
             });
         }
+        // Exactly one, not "at least one". A gate hands its successors the ref of
+        // the stage it was given rather than staging a copy — see `WorkflowIfNode`
+        // — and one output ref cannot name two inputs, so a second inbound edge
+        // would be silently dropped. Zero is caught by `unreachable` instead, which
+        // points at the same fix with the better message.
+        if (node.kind === 'if' && (incoming.get(node.id)?.length ?? 0) > 1) {
+            issues.push({
+                code: 'if-needs-one-input',
+                nodeIds: [node.id],
+                message: `If "${node.name}" (${node.id}) has ${incoming.get(node.id)?.length} inbound edges, and it can only carry one through. An if node is a gate: it passes the rows it is given straight down whichever branch it takes, so it has one output to hand on and cannot merge. Wire those inputs into a transform and gate the transform instead.`,
+            });
+        }
         const unconfigured = nodeIsUnconfigured(node);
         if (unconfigured)
             issues.push(unconfigured);
     }
 }
+/**
+ * Every wire out of an `if` names a branch, and no other wire does.
+ *
+ * Both halves, because the two failures are opposite and both are silent. An
+ * unlabelled wire out of an `if` belongs to no branch, so nothing would ever
+ * take it and the subtree behind it would be skipped on every run of every
+ * deployment — a graph that draws correctly and quietly does half its work. A
+ * label on a wire whose source does not branch is the reverse: a decision
+ * somebody wrote down that nothing reads, which is worse than no decision
+ * because the canvas draws it.
+ *
+ * Run after the structural checks, so `byId` has every endpoint and this cannot
+ * report a wire whose real problem is that it points at a node that was deleted.
+ */
+function checkBranches(edges, byId, issues) {
+    for (const edge of edges) {
+        const from = byId.get(edge.from);
+        if (!from)
+            continue;
+        if (from.kind === 'if' && edge.branch === undefined) {
+            issues.push({
+                code: 'branch-not-labelled',
+                nodeIds: [edge.from, edge.to],
+                message: `The wire from "${from.name}" (${from.id}) to "${byId.get(edge.to)?.name ?? edge.to}" does not say which branch it is on. Every wire out of an if node belongs to "then" or to "else", because that is what decides whether it runs — an unlabelled one would never be taken, and everything only it feeds would be skipped on every run with nothing to say why.`,
+            });
+            continue;
+        }
+        if (from.kind !== 'if' && edge.branch !== undefined) {
+            issues.push({
+                code: 'branch-on-plain-edge',
+                nodeIds: [edge.from, edge.to],
+                message: `The wire from "${from.name}" (${from.id}) is labelled "${edge.branch}", but "${from.name}" is a ${from.kind} node and does not branch. A label nothing decides on is a decision that is drawn and never read; remove it, or put an if node where the choice is meant to be made.`,
+            });
+        }
+    }
+}
 /**
  * A node that names none of the thing it exists to run.
  *
@@ -508,8 +806,46 @@ function nodeIsUnconfigured(node) {
     }
     if (node.kind === 'call')
         return callIsUnnamed(node);
+    if (node.kind === 'if')
+        return ifIsUnconfigured(node);
     return undefined;
 }
+/**
+ * A gate whose test cannot decide anything.
+ *
+ * The third of the same mistake {@link nodeIsUnconfigured} describes, once per
+ * predicate kind, because "unconfigured" means something different for each and
+ * a single check would have to pick one. Both refusals exist for one reason: a
+ * gate that cannot really choose still picks a branch, and whichever it picks is
+ * a decision the graph appears to make and nobody authored — with half the
+ * pipeline silently not running as the only symptom.
+ */
+function ifIsUnconfigured(node) {
+    const predicate = node.predicate;
+    if (predicate.kind === 'env') {
+        if (predicate.envVar.trim().length > 0)
+            return undefined;
+        return {
+            code: 'if-not-named',
+            nodeIds: [node.id],
+            message: `If "${node.name}" (${node.id}) names no environment variable, so there is nothing for it to decide on. It reads the *name* of a variable on the machine that runs the load — that is how a graph tells a deployment with a ClickHouse apart from one without.`,
+        };
+    }
+    if (predicate.kind === 'rowCount') {
+        // At least one, so both answers are reachable. A threshold of zero is
+        // satisfied by every run including an empty one, so the `else` subtree would
+        // never execute on any deployment — the silent half-graph, arrived at by
+        // typing a number rather than by mislabelling a wire.
+        if (Number.isInteger(predicate.atLeast) && predicate.atLeast >= 1)
+            return undefined;
+        return {
+            code: 'if-threshold-invalid',
+            nodeIds: [node.id],
+            message: `If "${node.name}" (${node.id}) branches on a row count of ${JSON.stringify(predicate.atLeast)}, and a threshold has to be a whole number of at least 1. "At least 1" is the "did anything arrive at all" test; 0 would be satisfied by every run, so the else branch — and everything only it feeds — would never run on any deployment.`,
+        };
+    }
+    return unreachablePredicateKind(predicate, 'validateWorkflow');
+}
 /**
  * A call that names half of what it needs, or nothing at all.
  *
@@ -684,6 +1020,7 @@ 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 labels = branchLabels(graph.edges);
     // 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.
@@ -702,7 +1039,8 @@ function workflowRunOrder(graph) {
         // from, and it is part of the fingerprint precisely because it is visible in
         // 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) ?? [])] });
+        const inputs = [...(incoming.get(id) ?? [])];
+        order.push({ node, inputs, inputBranches: labelsInto(id, inputs, labels) });
         for (const next of outgoing.get(id) ?? []) {
             const remaining = (indegree.get(next) ?? 0) - 1;
             indegree.set(next, remaining);
@@ -712,6 +1050,81 @@ function workflowRunOrder(graph) {
     }
     return order;
 }
+/** Every labelled wire, keyed by the pair it joins. */
+function branchLabels(edges) {
+    const labels = new Map();
+    for (const edge of edges) {
+        if (edge.branch === undefined)
+            continue;
+        labels.set(`${edge.from}\0${edge.to}`, edge.branch);
+    }
+    return labels;
+}
+/** The labels on the wires into one node, with the unlabelled ones left out. */
+function labelsInto(to, inputs, labels) {
+    const into = {};
+    for (const from of inputs) {
+        const label = labels.get(`${from}\0${to}`);
+        if (label !== undefined)
+            into[from] = label;
+    }
+    return into;
+}
+/**
+ * Whether a node runs, given what the nodes before it did.
+ *
+ * ## The rule
+ *
+ * A node runs when **at least one wire into it is live**, where a wire is live
+ * if its source ran and — when the wire carries a branch label — the source is
+ * an `if` that took that branch. A node with no inbound wires always runs, which
+ * is every source and every originating call.
+ *
+ * ## Why the obvious rule is wrong
+ *
+ * The naive version is "mark everything downstream of the untaken edge as
+ * skipped", and it is wrong on the shape branches are most often drawn in:
+ *
+ * ```
+ *      ┌ then → A ┐
+ * if ──┤          ├→ C → sink
+ *      └ else → B ┘
+ * ```
+ *
+ * `C` is downstream of `B`. Take the `then` branch and the naive rule walks from
+ * the untaken `else` edge, reaches `B`, reaches `C`, and skips it — so the sink
+ * never runs and the load silently commits nothing, on a graph whose whole
+ * purpose was that both branches converge. Reachability from the **taken** edges
+ * gets it right: `C` is reached through `A`, so it runs, and `B` — reached only
+ * through the untaken edge — does not. `C` then sees an empty stage ref for `B`,
+ * which is exactly what `stageRefsFor` already does for an upstream that
+ * produced nothing, so the positions a merge reads stay aligned with the wires
+ * that were drawn.
+ *
+ * It is evaluated incrementally rather than as a graph walk because the answers
+ * arrive as the run goes: `workflowRunOrder` is topological, so by the time a
+ * node is reached every node feeding it has an outcome. That also means this
+ * reads **only** what was recorded — no predicate is re-evaluated here, which is
+ * the property the whole branch feature rests on.
+ */
+function workflowNodeRuns(entry, outcomes) {
+    if (entry.inputs.length === 0)
+        return true;
+    return entry.inputs.some((from) => {
+        const upstream = outcomes[from];
+        // Anything other than a clean success means this wire carried nothing: a
+        // skipped upstream is not on a live path, and a failed one aborts the run
+        // before this is ever asked.
+        if (upstream?.status !== 'succeeded')
+            return false;
+        const label = entry.inputBranches?.[from];
+        // A plain wire. Live because its source ran, which is what every graph
+        // drawn before branches existed relies on.
+        if (label === undefined)
+            return true;
+        return upstream.branch === label;
+    });
+}
 /**
  * A stable fingerprint of what a graph *does*.
  *
@@ -737,7 +1150,12 @@ function workflowGraphHash(graph) {
     const nodes = [...graph.nodes]
         .sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0))
         .map((node) => canonicalNode(node));
-    const edges = graph.edges.map((edge) => `${edge.from}>${edge.to}`);
+    // The branch is appended only when there is one, so every edge drawn before
+    // branches existed hashes to exactly the string it always did. Adding a graph
+    // to this file must not renumber the versions of graphs that did not change.
+    const edges = graph.edges.map((edge) => edge.branch === undefined
+        ? `${edge.from}>${edge.to}`
+        : `${edge.from}>${edge.to}:${edge.branch}`);
     const canonical = JSON.stringify({ nodes, edges });
     return `${fnv1a(canonical, 0x811c9dc5)}${fnv1a(canonical, 0x01000193)}`;
 }
@@ -779,7 +1197,34 @@ function canonicalNode(node) {
             sortedEntries(node.config),
         ]);
     }
-    return JSON.stringify([node.id, node.kind, node.targetType, node.mode ?? 'full']);
+    if (node.kind === 'if') {
+        return JSON.stringify([node.id, node.kind, ...canonicalPredicate(node.predicate)]);
+    }
+    if (node.kind === 'sink') {
+        return JSON.stringify([node.id, node.kind, node.targetType, node.mode ?? 'full']);
+    }
+    return unreachableNodeKind(node, 'workflowGraphHash');
+}
+/**
+ * The parts of a predicate that decide which branch runs.
+ *
+ * The kind leads, so the two tests can never canonicalise to the same string —
+ * a gate switched from "is CLICKHOUSE_URL set" to "did 1 row arrive" is a
+ * different pipeline on every deployment, and a hash that missed it would leave
+ * two runs claiming the same graph version while having taken different halves
+ * of it.
+ */
+function canonicalPredicate(predicate) {
+    if (predicate.kind === 'env') {
+        // Both halves, because both decide which branch runs. `equals` being absent
+        // is a *different* test from `equals` being the empty string — "set to
+        // anything" against "set to nothing" — so the two must not fold together.
+        return [predicate.kind, predicate.envVar, predicate.equals ?? null];
+    }
+    if (predicate.kind === 'rowCount') {
+        return [predicate.kind, predicate.atLeast];
+    }
+    return unreachablePredicateKind(predicate, 'workflowGraphHash');
 }
 function sortedEntries(config) {
     return Object.keys(config)
@@ -835,13 +1280,42 @@ function isWorkflowNode(value) {
             config !== null &&
             !Array.isArray(config));
     }
-    const sourceKind = Reflect.get(value, 'sourceKind');
-    const config = Reflect.get(value, 'config');
-    return isConnectorKind(sourceKind) && typeof config === 'object' && config !== null;
+    if (kind === 'if') {
+        // The predicate in full, refused rather than defaulted: a gate read back
+        // without a test it recognises would have to invent one, and inventing one
+        // means half the graph runs on a decision nobody made.
+        return isWorkflowIfPredicate(Reflect.get(value, 'predicate'));
+    }
+    if (kind === 'source') {
+        const sourceKind = Reflect.get(value, 'sourceKind');
+        const config = Reflect.get(value, 'config');
+        return isConnectorKind(sourceKind) && typeof config === 'object' && config !== null;
+    }
+    return isWorkflowNodeKindUnhandled(kind);
+}
+/**
+ * The narrowing counterpart of {@link unreachableNodeKind}.
+ *
+ * A guard cannot take a `never` — `kind` here is a string that
+ * {@link isWorkflowNodeKind} already accepted — so exhaustiveness is bought by
+ * assigning it to one, which is the compile error a new kind has to answer, and
+ * refusing the value at run time, which is what a build that skipped this file
+ * would do to a node it has no rule for.
+ */
+function isWorkflowNodeKindUnhandled(kind) {
+    void kind;
+    return false;
 }
 function isWorkflowEdge(value) {
     if (typeof value !== 'object' || value === null)
         return false;
+    // A `branch` that is present and unrecognised is refused rather than dropped,
+    // for the reason `isWorkflowNode` refuses an unknown node: an edge silently
+    // read back without its label is a wire that stops belonging to a branch, and
+    // everything behind it stops running with nothing to point at.
+    const branch = Reflect.get(value, 'branch');
+    if (branch !== undefined && !isWorkflowBranchLabel(branch))
+        return false;
     return (typeof Reflect.get(value, 'from') === 'string' && typeof Reflect.get(value, 'to') === 'string');
 }
 /**
@@ -909,3 +1383,24 @@ function isPipelineStore(store) {
         store !== null &&
         typeof Reflect.get(store, 'listConnectors') === 'function');
 }
+/**
+ * What a redacted password reads as, on the wire.
+ *
+ * Declared here rather than in `@dudousxd/nestjs-catalog-pipeline`, where the
+ * redaction itself lives, because this literal is not an implementation detail
+ * of the redaction: it is part of what `GET pipeline/connections` answers, and
+ * a browser is the audience it was invented for. A form that lets somebody
+ * paste an address has to be able to recognise the string it was shown — a
+ * `url` whose password is exactly this came out of a read, and posting it back
+ * as a NEW connection stores the word "REDACTED" as the password. There is no
+ * stored row behind a create for `restoreRedactedSecrets` to put the real one
+ * back from, so nothing downstream can catch it: the row saves, and the failure
+ * arrives at the first scheduled load as an authentication error against a
+ * password nobody typed.
+ *
+ * The pipeline package re-exports this rather than declaring its own, so the
+ * two halves cannot drift. A fixed literal rather than a run of asterisks, so
+ * it is greppable in a bug report and cannot be mistaken for a password
+ * somebody actually chose.
+ */
+exports.REDACTED_SECRET = 'REDACTED';