@dudousxd/nestjs-catalog 0.15.0 → 0.16.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,74 @@ 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;
+    /**
+     * Rows this node was *given*, for a node whose whole purpose is that the two
+     * numbers differ. Set by {@link WorkflowFilterNode} and absent everywhere else.
+     *
+     * Two numbers rather than a `dropped` counter, because `dropped` is
+     * `rowsIn - rows` and a third stored number is a third thing that can
+     * disagree with the other two. A run panel subtracts.
+     *
+     * Optional, so an outcome written before filters existed reads back as what it
+     * is — a node that never reported an input count — rather than as one that
+     * received nothing. Absent and zero are different facts here, and conflating
+     * them would make every historical transform look like it dropped everything.
+     */
+    rowsIn?: 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;
 }
@@ -568,13 +748,28 @@ export interface WorkflowNodeOutcome {
  * The kinds that were considered and rejected, since a small vocabulary is only
  * defensible if the omissions are:
  *
- * - **filter** — a transform whose code returns a subset of what it was given.
- *   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*.
+ * - **filter** — *this entry used to be a rejection, and it is worth leaving the
+ *   reversal visible rather than editing the history out.* The argument was that
+ *   a transform whose code returns a subset already filters, so the kind bought
+ *   a second way to drop rows and a second place to look when rows went missing.
+ *   That argument is sound about *code* and it is the reason
+ *   {@link WorkflowFilterNode} does not take any: what changed is that the
+ *   predicate is a **closed structure** rather than a body, and a closed
+ *   structure can be read by something other than a JavaScript engine. Only a
+ *   declarative predicate can be translated into a `WHERE` and pushed into the
+ *   query the source already runs, and that is not a micro-optimisation — a
+ *   transform filtering `obj_pribuybuylistdetail` reads all 7,637,391 rows off
+ *   disk, over the network, and into JS objects of ~80 properties each before
+ *   anything decides they were unwanted. See {@link WorkflowFilterNode} for what
+ *   is actually built today (an in-memory, per-batch pass) and for where the
+ *   pushdown seam is, which is a promise about a shape rather than a claim about
+ *   a measurement.
+ * - **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 +786,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", "filter"];
 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 +831,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 +1012,602 @@ 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;
+}
+/**
+ * The shapes a {@link WorkflowFilterPredicate} can take.
+ *
+ * Two leaf kinds plus a presence test plus two ways to combine them, and the
+ * list is closed for the same reason {@link WORKFLOW_PREDICATE_KINDS} is: every
+ * decision made per kind ends in {@link unreachableFilterPredicateKind}, so a
+ * sixth shape is a build failure naming the files that owe it an answer rather
+ * than a filter that saves, draws, and quietly keeps everything.
+ *
+ * **There is deliberately no `not`.** Every leaf carries its own inverse
+ * ({@link WORKFLOW_FILTER_OPERATORS} pairs each operator with one, `oneOf` has
+ * `notIn`, `present` has `isNotNull`) and `all`/`any` are duals, so De Morgan
+ * already writes any negation with the kinds here. A `not` node would be a
+ * second spelling of every predicate — two shapes to read when a load comes out
+ * short, and a UI with a checkbox nobody agrees on the placement of. The one
+ * case it does not cover is stated on {@link workflowFilterMatches}: a value the
+ * test cannot compare fails *both* a form and its inverse, on purpose.
+ *
+ * **There is deliberately no free-form expression and no code.** That is the
+ * whole argument for the node existing — see {@link WorkflowFilterNode}.
+ */
+export declare const WORKFLOW_FILTER_PREDICATE_KINDS: readonly ["compare", "oneOf", "present", "all", "any"];
+export type WorkflowFilterPredicateKind = (typeof WORKFLOW_FILTER_PREDICATE_KINDS)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowFilterPredicateKind(value: unknown): value is WorkflowFilterPredicateKind;
+/**
+ * {@link unreachablePredicateKind}, for the filter language, and for the
+ * identical reason.
+ *
+ * It throws as well as failing to compile: a predicate arrives as JSON out of a
+ * column, so a graph saved by a newer build and read by an older one is a thing
+ * that happens, and returning a default for a shape this build has no rule for
+ * would mean silently keeping — or silently dropping — every row.
+ */
+export declare function unreachableFilterPredicateKind(predicate: never, where: string): never;
+/**
+ * What a {@link WorkflowFilterComparison} does with its column and its value.
+ *
+ * Ten, in five inverse pairs, and the pairing is the reason there is no `not`
+ * kind. Each one has an obvious single-expression form in both dialects this
+ * repository speaks, which is not a coincidence — it is the constraint the list
+ * was chosen under, so that the day a predicate is pushed into a source query
+ * the translation is a `switch` and not a design.
+ *
+ * The omissions, since a closed list is only defensible if they are:
+ *
+ * - **`between`** — `all` of a `greaterThanOrEqual` and a `lessThanOrEqual`, in
+ *   one more click and with no second shape to validate, hash and translate.
+ * - **`endsWith`** — asked for far less than the other two, and unlike them it
+ *   has no index that could ever serve it in either dialect, so offering it in a
+ *   palette would advertise something that is a full scan by construction.
+ *   `contains` covers it at the same cost.
+ * - **regular expressions** — the dialects disagree about the syntax, the
+ *   engines disagree about the semantics, and a predicate whose meaning depends
+ *   on which database answered it is a predicate that cannot be pushed down
+ *   without changing what the load returns. That is the one property this list
+ *   exists to hold.
+ * - **case-insensitive variants** — collation is a property of the column in
+ *   both dialects, so a `equalsIgnoreCase` evaluated in memory and the same
+ *   predicate evaluated in a `WHERE` would legitimately disagree. Normalise in a
+ *   transform, where the disagreement is visible.
+ */
+export declare const WORKFLOW_FILTER_OPERATORS: readonly ["equals", "notEquals", "greaterThan", "lessThanOrEqual", "greaterThanOrEqual", "lessThan", "contains", "notContains", "startsWith", "notStartsWith"];
+export type WorkflowFilterOperator = (typeof WORKFLOW_FILTER_OPERATORS)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowFilterOperator(value: unknown): value is WorkflowFilterOperator;
+/**
+ * {@link unreachableFilterPredicateKind}, one level further down.
+ *
+ * An operator added to the list without a rule for evaluating it, describing it
+ * or hashing it is a type error naming the file — not a comparison that silently
+ * answers false for every row, which is a filter that drops the whole dataset
+ * and reports success.
+ */
+export declare function unreachableFilterOperator(operator: never, where: string): never;
+/**
+ * What a predicate may be compared against.
+ *
+ * Three scalars and nothing else. No `null` — {@link WorkflowFilterPresence} is
+ * how absence is tested, and folding it in here would make `equals: null` and
+ * `isNull` two spellings of one question with different answers under the
+ * three-valued logic on {@link workflowFilterMatches}. No object and no array —
+ * an array is {@link WorkflowFilterOneOf.values}, and an object compared with
+ * `===` never matches anything a source produced.
+ *
+ * **Dates are strings.** A source hands back whatever its driver decoded, and a
+ * catalog that tried to parse dates here would have to pick a format, get it
+ * wrong for one dialect, and produce a comparison that silently ordered rows
+ * differently from the `WHERE` this predicate is meant to become. ISO-8601
+ * strings sort correctly under `<` and under every SQL collation, which is why
+ * `boundStatement` already compares watermarks as text.
+ */
+export type WorkflowFilterValue = string | number | boolean;
+/** Whether a stored value is one this language can compare against. */
+export declare function isWorkflowFilterValue(value: unknown): value is WorkflowFilterValue;
+/**
+ * The column names a predicate may name.
+ *
+ * **The same pattern `boundStatement` requires of a watermark column**, and that
+ * is the point rather than a coincidence: an identifier cannot be bound by any
+ * driver, so pushing a predicate into a query means quoting the column into the
+ * SQL, and a name carrying a quote, a dot or a space is refused rather than
+ * escaped. Requiring it *now*, while the predicate is only ever evaluated in
+ * memory, is what stops a graph being authored today that could never be pushed
+ * down tomorrow.
+ *
+ * The cost, and it is real: a source whose column is called `Part Number` cannot
+ * be filtered directly. Rename it in a transform first — which is a node that
+ * already exists and whose output is a column this can name.
+ */
+export declare const WORKFLOW_FILTER_COLUMN_PATTERN: RegExp;
+/**
+ * How deep `all`/`any` may nest.
+ *
+ * A bound rather than a trust, because a predicate arrives as JSON out of a
+ * column and every function that walks one is recursive: a graph carrying a
+ * thousand-deep tree would be a stack overflow inside a durable step rather than
+ * a refusal naming the node. Six is past anything a person builds in a form and
+ * far short of anything that costs a frame to walk.
+ */
+export declare const WORKFLOW_FILTER_MAX_DEPTH = 6;
+/**
+ * How many values one {@link WorkflowFilterOneOf} may list.
+ *
+ * Bounded because the list travels in the graph, into the graph fingerprint, and
+ * eventually into an `IN (...)` — and past a few hundred entries all three of
+ * those stop being reasonable and the thing being expressed is a join against
+ * another dataset rather than a filter. Wire that dataset in as a second source
+ * and join it in a transform, which is the node that can.
+ */
+export declare const WORKFLOW_FILTER_MAX_VALUES = 500;
+/** One column against one value. The leaf almost every filter is made of. */
+export interface WorkflowFilterComparison {
+    kind: 'compare';
+    /** A bare column name. See {@link WORKFLOW_FILTER_COLUMN_PATTERN}. */
+    column: string;
+    operator: WorkflowFilterOperator;
+    value: WorkflowFilterValue;
+}
+/**
+ * One column against a list of values.
+ *
+ * Its own kind rather than an `equals` whose value is allowed to be an array,
+ * because that shape makes `value` mean two things and every reader has to test
+ * which — the flat-optional-fields mistake {@link WORKFLOW_PREDICATE_KINDS}
+ * argues against, one level down again. It also has no honest single spelling in
+ * SQL as a comparison: `IN (…)` takes a parenthesised list and one bound
+ * parameter per entry.
+ */
+export interface WorkflowFilterOneOf {
+    kind: 'oneOf';
+    column: string;
+    /** `notIn` rather than a `negated` flag, so the two read alike in a palette. */
+    operator: 'in' | 'notIn';
+    /** At most {@link WORKFLOW_FILTER_MAX_VALUES}, and never empty. */
+    values: WorkflowFilterValue[];
+}
+/**
+ * Whether a column has a value at all.
+ *
+ * The one test the other two cannot express, and the reason they cannot is the
+ * three-valued logic on {@link workflowFilterMatches}: every `compare` and every
+ * `oneOf` is false when the column is null, *including the inverses*, exactly as
+ * a `WHERE` would answer. So "the ones with no delivery date" has to be its own
+ * shape or it would be unaskable.
+ */
+export interface WorkflowFilterPresence {
+    kind: 'present';
+    column: string;
+    operator: 'isNull' | 'isNotNull';
+}
+/**
+ * What `all` and `any` share, which is everything except the word.
+ *
+ * **An empty group is refused**, by `validateWorkflow`, by
+ * {@link isWorkflowFilterPredicate} and at the HTTP boundary. It is not a
+ * pedantic refusal: `all` of nothing is vacuously true, so it keeps every row
+ * and the filter does nothing; `any` of nothing is vacuously false, so it drops
+ * every row and the load comes out empty. Both are silent, both are reached by
+ * deleting the last condition in a form, and they are opposite catastrophes.
+ */
+interface WorkflowFilterGroupBase {
+    /** Never empty. Nested no deeper than {@link WORKFLOW_FILTER_MAX_DEPTH}. */
+    children: WorkflowFilterPredicate[];
+}
+/**
+ * Every child holds.
+ *
+ * Two interfaces rather than one carrying `kind: 'all' | 'any'`, which was
+ * written first and does not work: TypeScript will not remove a union member
+ * from the union when its discriminant is itself a union of literals and the two
+ * are tested separately, so `unreachableFilterPredicateKind` at the end of every
+ * `switch`-by-`if` chain stopped compiling — which is to say the exhaustiveness
+ * this whole file is arranged around was silently unavailable for these two
+ * kinds. Two declarations over a shared base costs one line and buys the
+ * property back.
+ */
+export interface WorkflowFilterAll extends WorkflowFilterGroupBase {
+    kind: 'all';
+}
+/** At least one child holds. Two declarations, for the reason on {@link WorkflowFilterAll}. */
+export interface WorkflowFilterAny extends WorkflowFilterGroupBase {
+    kind: 'any';
+}
+export type WorkflowFilterGroup = WorkflowFilterAll | WorkflowFilterAny;
+/** What a filter node tests. See {@link WORKFLOW_FILTER_PREDICATE_KINDS}. */
+export type WorkflowFilterPredicate = WorkflowFilterComparison | WorkflowFilterOneOf | WorkflowFilterPresence | WorkflowFilterAll | WorkflowFilterAny;
+/**
+ * Narrow a stored filter predicate, refusing rather than repairing.
+ *
+ * The same contract {@link isWorkflowIfPredicate} has and for a sharper version
+ * of the same reason: a gate read back without its test picks a branch nobody
+ * authored, and a *filter* read back without its test decides which rows exist.
+ * Repairing a broken predicate — dropping an unreadable child out of an `all`,
+ * say — would silently widen or narrow what a load publishes, which is precisely
+ * the failure the node is built to make visible.
+ *
+ * Depth is carried rather than tracked globally so that the bound is on the
+ * *tree*, not on how many predicates have been checked: two sibling branches
+ * five deep are fine, and one branch seven deep is not.
+ */
+export declare function isWorkflowFilterPredicate(value: unknown, depth?: number): value is WorkflowFilterPredicate;
+/**
+ * Whether one row passes a predicate.
+ *
+ * Pure, allocation-free on the common path, and in core rather than in the
+ * runner so that the console can describe — and one day preview — exactly what
+ * the load will do, from the same function that does it. It is called once per
+ * row, so everything about it is arranged to be cheap: no closures built per
+ * row, no array built per row, and `note` is optional so a caller that does not
+ * want the diagnostics pays nothing for them.
+ *
+ * ## Null is unknown, and unknown does not pass
+ *
+ * A column that is `null`, `undefined`, or simply absent from the row fails
+ * **every** `compare` and **every** `oneOf`, *including the negative forms*.
+ * `status notEquals "CLOSED"` does not pass a row with no status.
+ *
+ * That is SQL's three-valued logic rather than JavaScript's, and it is chosen
+ * deliberately over the more intuitive JS answer for one reason: this predicate
+ * is meant to become a `WHERE`, and the day it does, the database will answer
+ * this way. A filter that kept those rows in memory and dropped them once pushed
+ * down would be a performance change that quietly altered what a type contains —
+ * which is the one thing a pushdown must never be able to do. {@link
+ * WorkflowFilterPresence} is how absence is tested on purpose.
+ *
+ * ## A value it cannot compare fails both a test and its inverse
+ *
+ * `qty greaterThan 10` against a `qty` holding `"n/a"` is not false because the
+ * string is small; there is no ordering between a string and a number that any
+ * two systems would agree on. Rather than invent one, the leaf answers false and
+ * calls `note` with the column, and the runner turns those counts into a line on
+ * the run: *"12,431 rows held a value in `qty` the test could not compare."*
+ *
+ * A row nothing can judge is therefore dropped rather than kept. That is the
+ * direction with a backstop — the sink's row-count bound sees the shrink, and a
+ * full sink refuses to commit nothing at all — whereas keeping unjudged rows
+ * would publish them into the type with nothing anywhere to notice.
+ */
+export declare function workflowFilterMatches(predicate: WorkflowFilterPredicate, row: Record<string, unknown>, note?: (column: string) => void): boolean;
+/**
+ * Drops the rows that fail a declarative test, and reports how many.
+ *
+ * ## Why this is a node and not a transform that returns a subset
+ *
+ * A transform can already filter, so the kind has to earn itself. Three reasons,
+ * in increasing order of how much they decide the shape:
+ *
+ * 1. **It is legible on the canvas.** "Keep the open orders" is readable from
+ *    the box; the same rule inside a transform is readable only by opening the
+ *    code, and only by somebody who can read the language it is written in.
+ * 2. **Its effect is reportable.** A filter records rows in *and* rows out
+ *    ({@link WorkflowNodeOutcome.rowsIn}), so a run panel can say what was
+ *    dropped. A transform records one number, and a transform that quietly
+ *    started dropping 90% of its input looks exactly like a source that got
+ *    smaller. A filter whose effect is invisible is how data goes missing.
+ * 3. **Only a declarative predicate can be pushed into the source.** This is the
+ *    one that fixes the design. Arbitrary code cannot be translated to SQL, so a
+ *    code filter is *always* the expensive path: every row is read off disk, sent
+ *    over the network and turned into a JS object before anything decides it was
+ *    unwanted. A closed structure of column, operator and value can become a
+ *    `WHERE`, and then the rows are never read at all.
+ *
+ * ## Where it runs today, and where it does not yet
+ *
+ * **Today: in memory, one staged batch at a time, always.** The predicate is
+ * shaped so it *could* be pushed into a SQL source's query, and it is not, and
+ * saying so plainly is better than implying a win that has not been measured.
+ * What stands in the way is not the predicate — `boundStatement` in
+ * `sources.ts` already wraps an author's SQL in `SELECT * FROM (…) WHERE …`
+ * with a quoted identifier and a bound parameter, which is exactly the mechanism
+ * a pushdown would reuse — but the fetcher contract: `SourceFetcher` receives a
+ * connector, a secret, a watermark and a mode, and knows nothing about the
+ * graph, while the runner that *does* know the graph dispatches by connector
+ * kind alone. Threading a graph-derived predicate through that also drags in the
+ * schema-discovery path, which shares `sqlTarget`.
+ *
+ * There is a second reason, and it is the more interesting one: a pushed-down
+ * filter **cannot honestly report rows in**. The rows it dropped were never
+ * fetched, so "7,637,391 in, 96,204 out" would become "96,204 in, 96,204 out,
+ * nothing dropped" — reason 2 above, deleted by reason 3. Recovering the number
+ * means a second `COUNT(*)` over the unfiltered query, which is the scan the
+ * pushdown existed to avoid. Whichever way that is resolved, it is a decision
+ * about what a run reports and not a refactor, so it belongs in the change that
+ * makes the move rather than in a field added speculatively here.
+ *
+ * The seam is therefore one marked place in `WorkflowRunnerService.runFilter`
+ * rather than an unused translator sitting in this file waiting to rot.
+ *
+ * ## The trap this node had to be designed against: {@link narrows}
+ *
+ * Dropping a filter onto an existing `source → sink` wire replaces the published
+ * snapshot of that type with a subset — and every part of the run reports
+ * success, because from the run's point of view everything did succeed. See
+ * {@link narrows} for how the graph is made to tell that apart from filtering to
+ * derive something new, and why it cannot be told apart structurally.
+ */
+export interface WorkflowFilterNode extends WorkflowNodeBase {
+    kind: 'filter';
+    /**
+     * What a row has to satisfy to pass. See
+     * {@link WORKFLOW_FILTER_PREDICATE_KINDS}.
+     */
+    predicate: WorkflowFilterPredicate;
+    /**
+     * The object types whose published snapshot this filter is acknowledged to
+     * narrow.
+     *
+     * ## The two intentions, and why the graph cannot tell them apart
+     *
+     * Filtering to **derive a new type** — `source → filter → sink(OpenOrders)` —
+     * and filtering before **recommitting the same type** —
+     * `source → filter → sink(PriBuy)`, where `PriBuy` was until this morning the
+     * whole table — are *structurally identical graphs*. The only thing that
+     * differs is what the type on the sink already means to everybody reading it,
+     * and there is nothing in the nodes or the edges that knows that. Any rule
+     * claiming to distinguish them from the shape alone would be inventing a
+     * signal, and would then either refuse the safe case or wave the dangerous one
+     * through.
+     *
+     * So the graph makes the author **name the types**, and that naming is the
+     * whole mechanism: typing `OpenOrders` is a different act from typing
+     * `PriBuy`, and nobody types the second one by accident. What makes it a
+     * safeguard rather than a checkbox is that it is *required exactly where it
+     * matters and refused everywhere else*, both checked by `validateWorkflow`:
+     *
+     * - It must list **every** full-mode sink this filter stands in front of *on
+     *   every path* — that is, every sink whose entire snapshot would be a subset
+     *   because of this node. Removing the node would make that sink unreachable;
+     *   see `workflowNarrowedTypes`, which is the one implementation both the
+     *   validator and the console call.
+     * - It must list **nothing else**. A type named here that this filter does not
+     *   in fact narrow is refused, for the reason a branch label on a plain wire
+     *   is: an acknowledgement nothing reads is worse than none, because it is
+     *   drawn.
+     *
+     * A filter on one of several paths into a sink narrows nothing — other rows
+     * still reach it — and a filter in front of an incremental sink narrows
+     * nothing either, because an incremental commit merges into what is already
+     * there rather than replacing it. Neither has anything to declare, and neither
+     * may declare it.
+     *
+     * The consequence is the intended one: dragging a filter onto a working
+     * `source → sink` wire produces a graph that **will not save** until somebody
+     * writes down the name of the type they are about to shrink. It is in the
+     * graph fingerprint, so acknowledging it is a new version of the graph.
+     *
+     * The run-time backstop is unchanged and still the last word: the sink's
+     * row-count bound (`maxShrink`) refuses a commit that loses more of the served
+     * snapshot than the type allows, whatever this field says.
+     */
+    narrows?: string[];
+}
 /**
  * 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 | WorkflowFilterNode;
+/**
+ * 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 +1624,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,7 +1861,25 @@ 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;
+    /**
+     * What a {@link WorkflowFilterNode} was handed, against `rows` above, which is
+     * what it passed on. See {@link WorkflowNodeOutcome.rowsIn}: it travels on the
+     * step's output so that a replayed node reports the same drop the first
+     * attempt did, rather than reporting nothing because it was not re-run.
+     */
+    rowsIn?: number;
     elapsedMs: number;
     /**
      * The one thing here that is not a counter, and the one exception worth
@@ -1076,35 +1968,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", "filter-predicate-invalid", "filter-narrows-unacknowledged", "filter-narrows-nothing"];
 export type WorkflowIssueCode = (typeof WORKFLOW_ISSUE_CODES)[number];
 export interface WorkflowValidationIssue {
     code: WorkflowIssueCode;
@@ -1135,6 +2119,35 @@ export interface WorkflowValidationIssue {
  * being read.
  */
 export declare function validateWorkflow(graph: WorkflowGraph): WorkflowValidationIssue[];
+/**
+ * The object types whose whole published snapshot a node stands in front of.
+ *
+ * A sink is in this list when it commits in `full` mode — replacing what is
+ * served rather than merging into it — **and** removing the named node would
+ * make it unreachable from everything that originates rows. That second half is
+ * the load-bearing one: a filter on one of two paths into a sink narrows
+ * nothing, because the other path still delivers, and a rule that ignored it
+ * would demand an acknowledgement for a graph where nothing is lost.
+ *
+ * Removal-reachability rather than a dominator algorithm, deliberately. The
+ * graphs here are a screenful of boxes, this runs once per filter node, and the
+ * cheaper version would be a second, subtler implementation of "does this node
+ * decide whether that one runs" living next to `checkReachability` — which is
+ * exactly the kind of duplication that eventually disagrees with the walk the
+ * rest of this file does.
+ *
+ * Exported because the console needs the same answer to offer the right
+ * acknowledgements, and a canvas that computed its own would offer a set the
+ * server then refuses.
+ *
+ * `precomputed` exists only so the validator, which has already built the
+ * adjacency it needs, does not build it twice per filter node. Callers outside
+ * this file pass a graph and nothing else.
+ */
+export declare function workflowNarrowedTypes(graph: WorkflowGraph, nodeId: string, precomputed?: {
+    originators: string[];
+    outgoing: ReadonlyMap<string, string[]>;
+}): string[];
 /**
  * The order the nodes run in, and the inputs each one gets.
  *
@@ -1147,10 +2160,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 +2384,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 +2640,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;