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

package/dist/catalog.pipeline.d.ts

@@ -406,12 +406,18 @@ export interface CatalogTransform {
     description?: string;
     language: TransformLanguage;
     /**
-     * The body of a function over one batch. It receives `records` and returns
-     * the rows to store.
+     * The body of a function over one batch. It receives `records` and
+     * `context`, and returns the rows to store.
      *
      * A batch rather than a record at a time: a transform that needs to look up,
      * deduplicate or aggregate cannot do it one row at a time, and paying one
      * process spawn per record would make any real load unusable.
+     *
+     * `context` is a {@link CatalogCodeContext} — the run, the node, the counts
+     * of what fed it, and the environment variables this deployment admits.
+     * Second rather than first, so that every transform written before it existed
+     * still runs: the harness supplies the parameter, and code that never names
+     * it is unaffected.
      */
     code: string;
     version: number;
@@ -460,6 +466,7 @@ export interface TransformResult {
 export interface TransformRunner {
     run(transform: Pick<CatalogTransform, 'language' | 'code'>, records: unknown[], options?: {
         timeoutMs?: number;
+        context?: CatalogCodeContext;
     }): Promise<TransformResult>;
     /** Languages this runner can actually execute in this environment. */
     available(): Promise<TransformLanguage[]>;
@@ -473,6 +480,123 @@ export interface TransformRunner {
     pythonPackages?(): Promise<string[]>;
 }
 export declare const TRANSFORM_RUNNER: unique symbol;
+/**
+ * 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.
+ */
+export declare const CODE_CONTEXT_CONTRACT = 1;
+/**
+ * The second argument every code-bearing node's code is handed.
+ *
+ * ## Why this exists at all
+ *
+ * A transform is a function over a batch, and a batch is not the whole of what
+ * the code needs to know. It needs the credential for the API it enriches
+ * against; it needs to say which run it belongs to when it logs; and — the case
+ * that motivated this — a conditional node's predicate has no `records` at all
+ * and still has to answer "did the source return anything", which is the guard
+ * that stops an empty snapshot being committed over live data.
+ *
+ * ## Why it is not `process.env`
+ *
+ * The obvious answer to "code needs environment variables" is to stop trimming
+ * the child's environment. It is the wrong one, and this repository has already
+ * argued the case in `secret-env-allowlist.ts`: a `secretEnvVar` is chosen by
+ * whoever writes the connector, so `process.env[name]` with nothing in between
+ * let anyone holding `catalog:write` on one narrow object type read the host
+ * application's own `DATABASE_URL`. Transform code is *the same principal by a
+ * shorter route* — it is a string that principal saved, and it can print
+ * whatever it reads into `logs`, which land in the run record and are served at
+ * `catalog:read`.
+ *
+ * So {@link env} is the allow-listed environment and nothing else: the same
+ * policy, the same two levers, the same boot warning. One rule across the
+ * product rather than a second one that quietly undoes the first. What the
+ * child's *own* `process.env` holds is unchanged — still `{PATH, NODE_ENV}` —
+ * and the admitted values arrive as data on stdin instead.
+ *
+ * ## Replay
+ *
+ * Everything here is plain JSON, and everything except {@link env} and
+ * {@link environment} is derived from a durable step's checkpointed input: the
+ * run id, the node, the graph's version and the stage handles are byte-
+ * identical on every attempt and on every replay. Those two are reads of
+ * pod-local state, which for a transform is harmless — a transform runs inside
+ * a step whose *output* is checkpointed, so replay returns the answer rather
+ * than re-running the code — and for a predicate evaluated in a workflow body
+ * is not. A caller in that position must resolve the context inside a step and
+ * let the checkpoint carry it, so that a redeploy between the original run and
+ * the replay cannot move the branch. The shape is JSON precisely so that it can
+ * be.
+ */
+export interface CatalogCodeContext {
+    /** {@link CODE_CONTEXT_CONTRACT} at the time the code ran. */
+    contract: number;
+    /**
+     * The run this code belongs to, which is also the snapshot id.
+     *
+     * Absent means there is no run: the editor's try pane executes code against
+     * sample records and stores nothing. Anything derived from this — an
+     * idempotency key, a filename — should refuse rather than invent one, and the
+     * absence is the signal that lets it.
+     */
+    runId?: string;
+    /** The graph, when the code is a node in one. Absent for a connector's single transform. */
+    workflow?: {
+        id: string;
+        name: string;
+        version: number;
+    };
+    /** The node, when the code is a node. Absent for a connector's single transform. */
+    node?: {
+        id: string;
+        name: string;
+    };
+    /** The connector, when the code runs as a connector's transform rather than in a graph. */
+    connectorId?: string;
+    /**
+     * The host's name for this copy of the world — `dev`, `prod` — when the host
+     * declared one.
+     *
+     * Nothing in the catalog can work this out for itself: a process may serve
+     * several environments and the choice arrives per request, so the only
+     * honest source is the host saying so. Present because branching on a named
+     * environment is legible in a way that sniffing a variable is not, and absent
+     * whenever the host stayed silent, which is a different thing from `dev`.
+     */
+    environment?: string;
+    /**
+     * How many records reached this code.
+     *
+     * Redundant with `records.length` for a transform and the whole payload for a
+     * predicate, which has no records. Stated as one number because the line a
+     * predicate is written to hold is "did anything arrive", and making that a
+     * sum over {@link inputs} invites `inputs[0].rowCount`, which is wrong the
+     * moment somebody draws a second edge.
+     */
+    rowCount: number;
+    /**
+     * Per inbound edge, in edge order — handles and counts, never the rows.
+     *
+     * The same {@link WorkflowStageRef} the call node hands a callee, deliberately
+     * rather than a second vocabulary for the same fact. Empty outside a graph.
+     */
+    inputs: WorkflowStageRef[];
+    /**
+     * The environment variables this deployment admits, and only those.
+     *
+     * Filtered by the credential allow-list — see `secret-env-allowlist.ts` — so
+     * a name nobody admitted is not here, and an empty object is the ordinary
+     * answer on a deployment that has declared no policy. The run's logs say
+     * which it was.
+     */
+    env: Record<string, string>;
+}
 export interface ConnectorRun {
     id: string;
     connectorId: string;
@@ -539,18 +663,60 @@ export interface ConnectorRun {
      */
     nodeOutcomes?: Record<string, WorkflowNodeOutcome>;
 }
+/**
+ * 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.
+ */
+export declare const WORKFLOW_SKIP_REASONS: readonly ["branch-not-taken"];
+export type WorkflowSkipReason = (typeof WORKFLOW_SKIP_REASONS)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowSkipReason(value: unknown): value is WorkflowSkipReason;
 /** What one node did during a run. Small by construction — counters, not rows. */
 export interface WorkflowNodeOutcome {
     /**
      * `skipped` exists for the nodes downstream of a failure. Without it, a
      * ten-node graph that died at node seven records three nodes with no entry at
      * all, which reads the same as three nodes nobody has looked at yet.
+     *
+     * It now carries a second, legitimate meaning as well — a node on the branch
+     * an `if` did not take — and {@link skippedBecause} is what tells the two
+     * apart.
      */
     status: 'succeeded' | 'failed' | 'skipped';
     /** Rows this node produced, or committed if it is the sink. */
     rows: number;
     /** For a transform node: which version of its code ran. */
     transformVersion?: number;
+    /**
+     * For an {@link WorkflowIfNode}: the branch this run took.
+     *
+     * **Written once, on the first evaluation, and read back on every replay.**
+     * This is the record the durable path replays from rather than re-evaluating:
+     * a predicate reads the environment, and an environment is pod-local, so a
+     * replay landing on another pod could otherwise take the other branch halfway
+     * through a run and load through a shape nobody chose. See
+     * `WorkflowRunnerService.runIf`.
+     *
+     * It is also the answer to "why did nothing load into X", which is the
+     * question a branch makes askable and nothing else on a run can answer.
+     */
+    branch?: WorkflowBranchLabel;
+    /** See {@link WORKFLOW_SKIP_REASONS}. Absent means the run stopped short. */
+    skippedBecause?: WorkflowSkipReason;
     elapsedMs?: number;
     error?: string;
 }
@@ -572,9 +738,12 @@ export interface WorkflowNodeOutcome {
  *   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.
@@ -591,10 +760,28 @@ export interface WorkflowNodeOutcome {
  *   outside a run, which is why `call` names one and not a step. If a step is
  *   what you want, the thing to call is a one-step workflow wrapping it.
  */
-export declare const WORKFLOW_NODE_KINDS: readonly ["source", "transform", "sink", "call"];
+export declare const WORKFLOW_NODE_KINDS: readonly ["source", "transform", "sink", "call", "if"];
 export type WorkflowNodeKind = (typeof WORKFLOW_NODE_KINDS)[number];
 /** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
 export declare function isWorkflowNodeKind(value: unknown): value is WorkflowNodeKind;
+/**
+ * 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.
+ */
+export declare function unreachableNodeKind(node: never, where: string): never;
 /**
  * The longest a node id may be, and the alphabet it may use.
  *
@@ -618,12 +805,68 @@ interface WorkflowNodeBase {
      * a person arranged and the server then forgot is a canvas that loses work.
      * Excluded from the graph fingerprint for the same reason a rename is: moving
      * a box is not a new version of the graph.
+     *
+     * A position is in the units {@link WORKFLOW_NODE_WIDTH} is measured in, and
+     * anything **generating** one should space it with {@link workflowColumnX} and
+     * {@link workflowRowY} rather than by picking a number.
      */
     position?: {
         x: number;
         y: number;
     };
 }
+/**
+ * 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.
+ */
+export declare const WORKFLOW_NODE_WIDTH = 224;
+/** How tall a node is. The other half of {@link WORKFLOW_NODE_WIDTH}'s contract. */
+export declare const 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.
+ */
+export declare const WORKFLOW_COLUMN_GAP = 96;
+/** Clear space between two nodes sharing a column. */
+export declare const 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.
+ */
+export declare function workflowColumnX(column: number): number;
+/** The y of the nth row within a column, counting from zero. */
+export declare function workflowRowY(row: number): number;
 /**
  * Reads records out of a system.
  *
@@ -743,13 +986,229 @@ export interface WorkflowCallNode extends WorkflowNodeBase {
     /** Parameters the author typed, handed to the child under `input`. */
     config: Record<string, unknown>;
 }
+/**
+ * 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`.
+ */
+export declare const WORKFLOW_PREDICATE_KINDS: readonly ["env", "rowCount"];
+export type WorkflowPredicateKind = (typeof WORKFLOW_PREDICATE_KINDS)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowPredicateKind(value: unknown): value is WorkflowPredicateKind;
+/**
+ * {@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.
+ */
+export declare function unreachablePredicateKind(predicate: never, where: string): never;
+/**
+ * Tests a variable on the machine that runs the load.
+ *
+ * The original predicate, and the one the node was built for: a deployment that
+ * has a ClickHouse has its URL and one that does not has nothing. It names the
+ * variable and never its value — see the note on {@link WorkflowIfNode} for why
+ * that is a safety property rather than a convenience.
+ */
+export interface WorkflowEnvPredicate {
+    kind: 'env';
+    /**
+     * The name of the environment variable to read on the machine that runs the
+     * node. **The name, never the value** — nothing about a credential is stored
+     * in a catalog.
+     */
+    envVar: string;
+    /**
+     * What it has to equal for the `then` branch to be taken.
+     *
+     * Absent means "is it set to anything non-empty", which is the ClickHouse
+     * case: a deployment that has one has the URL, a deployment that does not has
+     * nothing. Present means an exact string comparison, which is the
+     * `DEPLOY_ENV = local` case.
+     */
+    equals?: string;
+}
+/**
+ * Tests how many rows reached the gate.
+ *
+ * ## The case
+ *
+ * "Only run the sink if the source returned anything." A nightly export that
+ * comes back empty because the upstream system is mid-maintenance is not a
+ * failure — nothing is broken, there is simply nothing to load — but committing
+ * it repoints the live view of a type at an empty snapshot, and the run reports
+ * success while doing it. A gate in front of the sink turns that into a skip,
+ * and a skipped node is never executed, so nothing commits. That is the same
+ * guarantee the `else` branch already gives, pointed at the case that actually
+ * happens.
+ *
+ * ## Which rows
+ *
+ * The ones on the single inbound edge. `validateWorkflow` refuses a gate with
+ * more than one (`if-needs-one-input`) and refuses one with none as unreachable,
+ * so "how many rows" has exactly one answer — and it is the count on the very
+ * {@link WorkflowStageRef} the gate hands on, so the number tested and the rows
+ * carried cannot disagree.
+ *
+ * ## Where the number comes from, which is the replay argument
+ *
+ * `WorkflowStageRef.rowCount`, off {@link WorkflowNodeStepInput.inputs}, which
+ * is part of the step's checkpointed input and was itself produced by an
+ * upstream step's checkpointed output. Nothing counts rows at evaluation time
+ * and nothing reads the stage store: a resumed run on another pod sees the same
+ * number the first attempt saw, and the branch it produced is read back off
+ * {@link WorkflowNodeStepOutput.branch} anyway.
+ *
+ * ## Why a threshold and not "greater than zero"
+ *
+ * `atLeast: 1` *is* "did anything arrive", so the common case costs nothing to
+ * express — and "a full export is never under ten thousand rows, so treat a
+ * hundred as a broken upstream rather than as data" is the next thing anybody
+ * asks for, and it would otherwise need a second predicate kind for one integer.
+ *
+ * One comparison and one direction, deliberately. `atMost`, `equals` and a
+ * chosen operator were all considered and are all the same mistake the node's
+ * own `negate` flag would have been: the inverse test is already expressible by
+ * swapping which successor is on `then` and which is on `else`, and two ways to
+ * say one thing is two places to look when a load takes the branch nobody
+ * expected.
+ */
+export interface WorkflowRowCountPredicate {
+    kind: 'rowCount';
+    /**
+     * How many rows have to reach the gate for the `then` branch to be taken.
+     *
+     * A whole number of at least one, and `validateWorkflow` says so. Zero is
+     * refused rather than treated as "always" because it is a gate that can only
+     * ever answer one way — the `else` subtree would never run on any deployment,
+     * which is the silent half-graph this node's whole design is arranged against.
+     */
+    atLeast: number;
+}
+/**
+ * What an `if` node tests. See {@link WORKFLOW_PREDICATE_KINDS}.
+ */
+export type WorkflowIfPredicate = WorkflowEnvPredicate | WorkflowRowCountPredicate;
+/**
+ * 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.
+ */
+export declare function isWorkflowIfPredicate(value: unknown): value is WorkflowIfPredicate;
+/**
+ * Sends the rows down one of its two outbound branches, and skips the other.
+ *
+ * The node the maintainer asked for, and the reason it is a node rather than a
+ * flag on an edge: a deployment that has a ClickHouse and a deployment that does
+ * not are the *same graph*, and the difference between them is one decision made
+ * at run time. Modelling it as two workflows means two things to keep in step;
+ * modelling it as an edge flag means the decision has nowhere to be recorded and
+ * nothing on the canvas to open.
+ *
+ * ## What it does to the rows: nothing
+ *
+ * An `if` is a gate, not a stage. It passes its input through untouched — its
+ * output ref *is* its input's ref — so a branch costs no copy of the dataset and
+ * no second write into the stage store. That is also why it takes **exactly one
+ * inbound edge**: a node hands its successors one {@link WorkflowStageRef}, so a
+ * gate fed by two inputs could only either copy the rows to merge them (paying
+ * for the whole dataset to make a decision that reads none of it) or silently
+ * drop one. Merging is what a transform is for; put one in front.
+ *
+ * That holds for {@link WorkflowRowCountPredicate} too, which is the one
+ * predicate that sounds like it reads the data and does not: the count it tests
+ * is the number already written on the {@link WorkflowStageRef} it was handed,
+ * so a gate still touches no rows — and with one inbound edge there is exactly
+ * one count for "how many rows" to mean.
+ *
+ * ## The predicate is declarative, and that is the safety property
+ *
+ * It is one of {@link WORKFLOW_PREDICATE_KINDS} — a variable's name, or a count
+ * off a checkpoint — and never a value and never code. Three reasons, in order
+ * of how much they cost to get wrong:
+ *
+ * 1. **Replay.** The durable engine replays a run, possibly on another pod. A
+ *    predicate is by definition the thing whose answer decides which half of the
+ *    graph exists, so an answer that can differ between the run and its replay
+ *    is a run that loads through a shape nobody chose — and it would show up as
+ *    a non-determinism error two nodes later, naming neither the branch nor the
+ *    variable. The outcome is therefore recorded on first evaluation
+ *    ({@link WorkflowNodeOutcome.branch}) and read back afterwards, and the
+ *    declarative form is what keeps that record small enough to be a checkpoint.
+ *    Both predicate kinds are answerable from what a step was handed:
+ *    {@link WorkflowRowCountPredicate} reads a number that arrived on the step's
+ *    own checkpointed input rather than counting anything.
+ * 2. **A predicate is not a place for a secret.** A name is stored; a value
+ *    never is. This is the same rule {@link WorkflowSourceNode.secretEnvVar}
+ *    follows and for the same reason.
+ * 3. **Code would need a context to read, and this node does not own it.** What
+ *    code-bearing nodes may see — allow-listed variables, a `catalog` object —
+ *    is a question being answered elsewhere. A `code` predicate is additive the
+ *    day it lands: it becomes another member of {@link WorkflowIfPredicate}, and
+ *    everything that reads a branch reads it off the recorded outcome exactly as
+ *    it does now.
+ *
+ * To invert the test, swap which successor is on `then` and which is on `else`.
+ * There is deliberately no `negate` flag: two ways to say one thing is two
+ * places to look when a load takes the branch you did not expect.
+ */
+export interface WorkflowIfNode extends WorkflowNodeBase {
+    kind: 'if';
+    /**
+     * What it tests. A union rather than a field per test — see
+     * {@link WORKFLOW_PREDICATE_KINDS} for why that is the whole point.
+     */
+    predicate: WorkflowIfPredicate;
+}
 /**
  * A discriminated union, so narrowing a node is `node.kind === "sink"` and
  * never a type assertion. This is why the kind list is not simply a string on
  * one node shape with every field optional: that shape lets a source node carry
  * a `transformId` and nothing catches it.
  */
-export type WorkflowNode = WorkflowSourceNode | WorkflowTransformNode | WorkflowSinkNode | WorkflowCallNode;
+export type WorkflowNode = WorkflowSourceNode | WorkflowTransformNode | WorkflowSinkNode | WorkflowCallNode | WorkflowIfNode;
+/**
+ * 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.
+ */
+export declare const WORKFLOW_BRANCH_LABELS: readonly ["then", "else"];
+export type WorkflowBranchLabel = (typeof WORKFLOW_BRANCH_LABELS)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowBranchLabel(value: unknown): value is WorkflowBranchLabel;
 /**
  * One wire.
  *
@@ -766,6 +1225,22 @@ export type WorkflowNode = WorkflowSourceNode | WorkflowTransformNode | Workflow
 export interface WorkflowEdge {
     from: string;
     to: string;
+    /**
+     * Which branch of an {@link WorkflowIfNode} this wire leaves by.
+     *
+     * **Optional, and absent on every edge that existed before branches did.** An
+     * edge with no label is a plain wire that always carries rows when its source
+     * ran — which is what every stored edge is, so nothing about an existing graph
+     * changes, including its fingerprint. The label is *required* on an edge
+     * leaving an `if` and *refused* on any other, both by `validateWorkflow`: a
+     * label on a wire nothing branches at would look like a decision and be
+     * ignored, and an unlabelled wire out of an `if` has no branch to belong to.
+     *
+     * Several wires may share a label. An `if` whose `then` side fans out to two
+     * nodes is ordinary fan-out that happens to be conditional; what is refused is
+     * two wires between the *same pair*, which was already refused as a duplicate.
+     */
+    branch?: WorkflowBranchLabel;
 }
 /** Just the executable part of a workflow, for validating a canvas draft. */
 export interface WorkflowGraph {
@@ -987,6 +1462,17 @@ export interface WorkflowNodeStepOutput {
     };
     /** Which transform version ran, for a transform node. */
     transformVersion?: number;
+    /**
+     * Which branch an `if` node took, for an `if` node.
+     *
+     * **On the step's output, which is the whole mechanism.** A step's output is
+     * what the durable engine checkpoints and hands back on replay without running
+     * the step again, so putting the evaluated branch here means the decision is
+     * made exactly once, in the run's own history, and every later turn reads the
+     * recorded one. A body that asked the predicate itself would be re-evaluating
+     * a pod-local fact on a pod that may not be the same one.
+     */
+    branch?: WorkflowBranchLabel;
     rows: number;
     elapsedMs: number;
     /**
@@ -1076,35 +1562,127 @@ export declare function readWorkflowCallOutput(value: unknown): WorkflowCallOutp
 /**
  * One workflow a call node could name.
  *
- * Declared here with nothing producing it yet, and that is deliberate rather
- * than premature: a picker needs a list, and **no such list exists**. The
- * durable engine can answer `workflowBody(name, version)` for the process
- * asking and nothing more — and a missing body is ambiguous, since it equally
- * means a body registered in another SDK through `registerRemote` or a group
- * resolved by convention against a live worker. Inferring the list from what
- * one pod happens to know would produce a picker that omits exactly the
- * cross-SDK workflows this node exists to call.
- *
- * So the node takes a name and a version as authored text today, and this is
- * the shape a canvas should be handed the day a deployment can announce its
- * registrations. One entry per **version**, never per name: a picker that
- * listed names and resolved the version for you would undo the pin.
+ * ## What this used to say, and what changed
+ *
+ * This shape was declared with nothing producing it, because a picker needs a
+ * list and no list existed. The durable engine could answer
+ * `workflowBody(name, version)` for the process asking and nothing more, and a
+ * missing body is ambiguous by construction: it equally means "not registered",
+ * "registered through `registerRemote` against another SDK", or "a group
+ * resolved by convention against a live worker". A list inferred from that
+ * would have omitted precisely the cross-SDK workflows this node exists to
+ * call, and would have omitted them silently.
+ *
+ * `@dudousxd/nestjs-durable-core` **0.65.0** closed that with
+ * `WorkflowEngine.announcedWorkflows()`: live workers publish what they can
+ * execute on the worker-descriptor keyspace, and every pod folds the same
+ * published statements, so the answer no longer depends on which replica
+ * served the request. That is what fills this shape now — see
+ * `WorkflowLauncher.callableWorkflows` in `@dudousxd/nestjs-catalog-pipeline`
+ * for the adapter, and keep three properties of the aggregate in mind, because
+ * every field below exists to carry one of them:
+ *
+ * - **It is what is runnable, not what is known about.** The announcer is
+ *   always the process that CONSUMES the queue, so a `registerRemote` entry is
+ *   never announced by the engine that declared it. An operator running bodies
+ *   inline with no queue announces nothing at all — its workflows are real and
+ *   startable, and simply not in this list.
+ * - **It is a snapshot.** An announcement lives on a descriptor key with the
+ *   worker-heartbeat TTL, so a worker that dies takes its entries with it
+ *   within about one beat. Nothing built on this should be cached past that,
+ *   and nothing should present it as authoritative-forever.
+ * - **Disagreements are kept, not merged.** Two live workers may claim the same
+ *   `name@version` from different groups. The aggregate refuses to pick a
+ *   winner, and so does this shape: see {@link disagreements}.
+ *
+ * One entry per **version**, never per name — a picker that listed names and
+ * resolved the version for you would undo the pin the call node exists for.
  */
 export interface CallableWorkflowRef {
     name: string;
-    version: string;
+    /**
+     * The version to pin, and **absent is a real answer**.
+     *
+     * A worker that has not been upgraded announces a bare name with no version
+     * and no group. Silence is not a claim, so no version is invented for it from
+     * another announcer's — and an entry without one cannot satisfy the pin, which
+     * is why {@link callableWorkflowBlock} refuses it rather than letting a picker
+     * offer a name that would run whatever is newest on the day it runs.
+     */
+    version?: string;
     /** What it does, if the deployment publishes one. Shown beside the name. */
     description?: string;
     /**
-     * The worker group its turns are dispatched to, when it has one. The signal
-     * that says "this one's body is not in this process" — a Python workflow, or
-     * a separate TS worker — which is precisely what a caller cannot otherwise
-     * tell from a missing body.
+     * The worker group its turns are dispatched to, when the live announcers
+     * agree on exactly one. The signal that says "this one's body is not in this
+     * process" — a Python workflow, or a separate TS worker — which is precisely
+     * what a caller cannot otherwise tell from a missing body.
+     *
+     * Absent means either nobody stated one or the announcers disagree, and those
+     * two are not the same: the second puts a `group` entry in
+     * {@link disagreements} and the first does not.
      */
     group?: string;
+    /**
+     * How many live workers announce it. `1` is a single point of failure, and it
+     * is never `0` — an entry exists only because somebody announced it.
+     */
+    workers?: number;
+    /**
+     * The axes the live announcers do not agree on, empty or absent when they
+     * speak with one voice. Carried rather than resolved: the registry refuses to
+     * guess and so does everything downstream of it.
+     */
+    disagreements?: CallableWorkflowDisagreement[];
+}
+/**
+ * One axis on which the live announcers of a workflow differ.
+ *
+ * Mirrors the durable engine's own `Disagreement` rather than re-deriving it,
+ * and `values` holds every distinct **declared** value: an announcer that stated
+ * nothing on the axis contributes nothing, because silence is not a claim.
+ */
+export interface CallableWorkflowDisagreement {
+    axis: 'group' | 'origin' | 'requires';
+    values: string[];
 }
+/**
+ * Why an announced entry must not be committed onto a call node, or `undefined`
+ * when it can be.
+ *
+ * Pure and exported from the browser entry point as well as this one, for the
+ * reason {@link validateWorkflow} is: the canvas that greys the option out and
+ * anything server-side that reasons about the same list must apply *the same*
+ * rule. A picker with its own copy of it is a picker that eventually offers
+ * something the rest of the system considers unusable.
+ *
+ * Two refusals, and they are refusals rather than warnings because in both cases
+ * committing the entry would write a node whose meaning nobody can state:
+ *
+ * - `no-version` — an un-upgraded worker announced a bare name. The call node's
+ *   whole point is the pin; a node holding a name and no version follows
+ *   whatever gets deployed next, which is the failure the version field exists
+ *   to prevent. The name is still perfectly typeable by hand *with* a version
+ *   the author knows, so this refuses the one-click commit and not the workflow.
+ * - `ambiguous-group` — two live workers claim this exact `name@version` from
+ *   different groups. Two groups means two queues, and nothing here can know
+ *   which one a run would land on, so the two bodies may not even be the same
+ *   code. Picking one on the author's behalf would be acting on a claim nobody
+ *   made.
+ *
+ * A disagreement on `origin` or `requires` is deliberately **not** a refusal. It
+ * is worth showing — two packages declaring one name is a mess somebody should
+ * clean up — but it does not change which queue the run goes to, and refusing on
+ * it would block a pin that is otherwise exactly determined.
+ */
+export interface CallableWorkflowBlock {
+    code: 'no-version' | 'ambiguous-group';
+    /** A full sentence, addressed to whoever is looking at the picker. */
+    message: string;
+}
+export declare function callableWorkflowBlock(ref: CallableWorkflowRef): CallableWorkflowBlock | undefined;
 /** Every way a graph can be refused. Exported so a canvas can key off the code. */
-export declare const WORKFLOW_ISSUE_CODES: readonly ["empty", "invalid-node-id", "duplicate-node-id", "edge-endpoint-missing", "self-edge", "duplicate-edge", "cycle", "no-source", "source-has-input", "no-sink", "duplicate-sink-type", "sink-has-output", "unreachable", "dead-end", "transform-not-named", "call-not-named"];
+export declare const WORKFLOW_ISSUE_CODES: readonly ["empty", "invalid-node-id", "duplicate-node-id", "edge-endpoint-missing", "self-edge", "duplicate-edge", "cycle", "no-source", "source-has-input", "no-sink", "duplicate-sink-type", "sink-has-output", "unreachable", "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"];
 export type WorkflowIssueCode = (typeof WORKFLOW_ISSUE_CODES)[number];
 export interface WorkflowValidationIssue {
     code: WorkflowIssueCode;
@@ -1147,10 +1725,68 @@ export declare function validateWorkflow(graph: WorkflowGraph): WorkflowValidati
  * order over a broken graph is a load that half-happens, which is harder to
  * recover from than one that never started.
  */
-export declare function workflowRunOrder(graph: WorkflowGraph): Array<{
+export declare function workflowRunOrder(graph: WorkflowGraph): WorkflowRunOrderEntry[];
+/** One position in the order: which node, what feeds it, and on which branches. */
+export interface WorkflowRunOrderEntry {
     node: WorkflowNode;
+    /** Upstream node ids, in inbound-edge order. */
     inputs: string[];
-}>;
+    /**
+     * The branch label of each inbound edge that has one, keyed by the upstream
+     * node id.
+     *
+     * A record rather than an array positionally aligned with {@link inputs},
+     * which was the obvious shape and is unsafe for one specific reason: this
+     * travels through a durable checkpoint as JSON, and `JSON.stringify` turns an
+     * `undefined` hole in an array into `null`. A plain wire would come back from
+     * a replay as `null` rather than absent, `null !== 'then'` would be false, and
+     * the node would be treated as dead — the graph would silently stop running
+     * half of itself on resumed runs only. A key that is simply not there
+     * round-trips exactly. The key is unique because duplicate edges are refused.
+     */
+    inputBranches: Record<string, WorkflowBranchLabel>;
+}
+/**
+ * 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.
+ */
+export declare function workflowNodeRuns(entry: {
+    inputs: readonly string[];
+    inputBranches?: Readonly<Record<string, WorkflowBranchLabel>>;
+}, outcomes: Readonly<Record<string, WorkflowNodeOutcome>>): boolean;
 /**
  * A stable fingerprint of what a graph *does*.
  *
@@ -1313,49 +1949,6 @@ export interface CatalogWorkflowStore {
         schedule?: string;
         enabled?: boolean;
     }, changedBy: string): Promise<CatalogWorkflow>;
-    /**
-     * Wrap a connector that predates workflows into the graph it always was.
-     *
-     * **The upgrade path, and the reason removing `POST connectors` does not
-     * orphan anything.** A deployment upgrading into this change has connectors
-     * that were authored directly — a kind, a config, optionally one transform,
-     * and a target type — and no route can edit them any more. Three outcomes
-     * were possible: migrate them, leave them readable but frozen, or make
-     * somebody rebuild each by hand. This is the first, and it is chosen because
-     * the shape was already exactly representable: a connector *is* a
-     * single-source, single-sink graph with at most one transform in the middle,
-     * and it has been describable as one since `workflowId` existed.
-     *
-     * ## What is preserved, and why each matters
-     *
-     * - **The connector id.** It is the mutex key, the owner of every
-     *   `ConnectorRun` and the holder of the watermark. Minting a fresh connector
-     *   and leaving the old one would split one pipeline's history in two and
-     *   leave nothing serialising the halves against each other.
-     * - **The watermark, re-keyed.** A plain connector kept a flat `state`; a
-     *   graph keys it by source-node id. Carrying the blob over unchanged would
-     *   leave the new source node with no watermark at all, and the first run
-     *   after the upgrade would re-read an incremental source from the beginning —
-     *   which is not data loss, but is a surprise measured in hours on a large
-     *   source.
-     * - **The schedule**, moved to the graph, which is where it is authored now.
-     *
-     * ## What changes, stated plainly
-     *
-     * The graph is published as `ready` without a person having declared it
-     * finished, because refusing to publish would leave the pipeline not running —
-     * an upgrade that silently stops twelve loads is a worse outcome than one that
-     * carries a decision forward on the operator's behalf. It is validated first
-     * and the adoption is **refused** if the wrap does not validate, so nothing is
-     * published that could not have been drawn.
-     *
-     * Idempotent: a connector that already has a `workflowId` is left alone and
-     * answered `undefined`. That is what makes it safe to run at every boot.
-     */
-    adoptConnector(connectorId: string, adoptedBy: string): Promise<{
-        workflow: CatalogWorkflow;
-        connector: CatalogConnector;
-    } | undefined>;
 }
 /**
  * Where the rows between two nodes actually sit.
@@ -1612,6 +2205,27 @@ export interface CatalogConnection {
     lastCheckOk?: boolean;
     lastCheckError?: string;
 }
+/**
+ * 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.
+ */
+export declare const REDACTED_SECRET = "REDACTED";
 /** What checking a connection found. */
 export interface ConnectionCheck {
     ok: boolean;