@dudousxd/nestjs-catalog 0.27.0 → 0.28.0

package/dist/catalog.pipeline.d.ts

@@ -1183,12 +1183,25 @@ export interface WorkflowNodeOutcome {
  *   {@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.
- *   A `merge` kind would have had to carry a strategy field whose values the
- *   runner would have to implement one by one, and an unimplemented strategy in
- *   a dropdown is the failure this list exists to avoid.
+ * - **merge (unkeyed)** — a node with several inbound edges already receives its
+ *   inputs concatenated in edge order (see {@link WorkflowEdge}), so a `merge`
+ *   kind would be a box that draws what the wires already say. It would also
+ *   have had to carry a strategy field whose values the runner implements one by
+ *   one, and an unimplemented strategy in a dropdown is the failure this list
+ *   exists to avoid.
+ * - **join (keyed)** — *this half used to be refused with the entry above, and
+ *   the reversal is left visible rather than edited out*, the way the `filter`
+ *   entry leaves its own. The old argument was that a keyed join is ordinary
+ *   code inside a transform, which can already see every record. Every word of
+ *   that is true and it is exactly the problem: "can already see every record"
+ *   is the same sentence as "holds the whole load", and it is why a transform
+ *   makes `ConnectorRunnerService` log *"Held all N records in memory"*. A join
+ *   does not need both sides held. It needs **one** side held — as a map, keyed
+ *   — while the other streams past it, and that asymmetry is a property of the
+ *   operation that a function over a batch cannot express and a runner therefore
+ *   cannot exploit. {@link WorkflowLookupNode} is the keyed half, built narrow:
+ *   one key, named enrichment fields, and a reference side that is bounded and
+ *   refused loudly rather than held quietly.
  * - **call a durable *step*** — the sibling of {@link WorkflowCallNode} that
  *   somebody will eventually come looking for, and it cannot be built. A
  *   durable step has no global identity: it is dispatched by a routing name
@@ -1199,7 +1212,7 @@ 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", "if", "filter", "rename", "aggregate"];
+export declare const WORKFLOW_NODE_KINDS: readonly ["source", "transform", "sink", "call", "if", "filter", "rename", "aggregate", "lookup"];
 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;
@@ -2407,6 +2420,27 @@ export declare function isWorkflowAggregateFunction(value: unknown): value is Wo
  * thing that happens.
  */
 export declare function unreachableAggregateFunction(fn: never, where: string): never;
+/**
+ * What happens to a driving row whose key matches no reference row.
+ *
+ * Three words rather than a boolean, because the three are the three joins SQL
+ * has names for and each is a different node. See
+ * {@link WorkflowLookupNode.unmatched} for which one to reach for.
+ */
+export declare const WORKFLOW_LOOKUP_UNMATCHED: readonly ["null", "drop", "fail"];
+export type WorkflowLookupUnmatched = (typeof WORKFLOW_LOOKUP_UNMATCHED)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowLookupUnmatched(value: unknown): value is WorkflowLookupUnmatched;
+/**
+ * The exhaustiveness guard for {@link WORKFLOW_LOOKUP_UNMATCHED}.
+ *
+ * {@link unreachableNodeKind}, one level down, and for the identical reason: the
+ * three words decide whether a row keeps its data, disappears from the load, or
+ * stops the run, and a fourth added without a branch would silently pick
+ * whichever the last `if` was — which here means silently changing which rows
+ * reach a published type.
+ */
+export declare function unreachableLookupUnmatched(value: never, where: string): never;
 /**
  * How many columns one node may group on.
  *
@@ -2710,6 +2744,311 @@ export declare function aggregateRefusals(node: {
     aggregates?: unknown;
     maxGroups?: unknown;
 }): string[];
+/**
+ * How many fields one lookup may bring across.
+ *
+ * The same argument {@link WORKFLOW_RENAME_MAX_COLUMNS} makes, plus one that is
+ * specific to this node: every named field is held *per distinct key* for the
+ * whole run, so this number multiplies {@link WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS}
+ * into the actual memory bill. Past a few dozen the thing being expressed is
+ * "give me that whole table beside this one", which is a second source and a
+ * union, not an enrichment.
+ */
+export declare const WORKFLOW_LOOKUP_MAX_FIELDS = 64;
+/**
+ * How many rows the reference side may have before the node refuses to run.
+ *
+ * ## Why there is a number here at all
+ *
+ * Because exactly one side of a join can stream, and this node holds the other
+ * one. That is the whole property it exists to have (see
+ * {@link WorkflowLookupNode}) and it is also the whole hazard: a graph whose
+ * reference edge is accidentally wired to the 7.6-million-row side does not fail,
+ * it allocates until the pod is killed — and a pod killed by the kernel produces
+ * no run log, no failed node and no message, which is the silence this file is
+ * arranged against.
+ *
+ * ## Why it is measured in rows, and why it is free
+ *
+ * A staged input announces its `rowCount` before a single row is read back (see
+ * `WorkflowStageRef`), so the refusal happens *before* anything is held. A bound
+ * in bytes would have to be discovered by holding rows until they weighed too
+ * much, which is a bound that has already done the damage by the time it fires.
+ *
+ * Two hundred thousand, and the arithmetic rather than a round number that feels
+ * safe: what is retained per key is the key string plus the values of the named
+ * fields — not the reference row — so a reference of this size with a handful of
+ * short fields is tens of megabytes, and one at {@link WORKFLOW_LOOKUP_MAX_FIELDS}
+ * is the point where it stops being obviously fine. The real reference tables
+ * this was built against are three orders of magnitude below it: a work-plan code
+ * table is hundreds of rows and a unit dictionary is dozens.
+ *
+ * The refusal names the count, the bound and the fix, because the fix is
+ * genuinely available in the graph: put a filter on the reference side, or swap
+ * the two edges if the smaller side is the one being streamed.
+ */
+export declare const WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS = 200000;
+/**
+ * Enriches each row with fields from a reference dataset, matched by key.
+ *
+ * ## The property that justifies a kind rather than a transform
+ *
+ * **One side is held; the other streams.** The reference is read once into a map
+ * keyed by its key column, and then the driving rows go past it one batch at a
+ * time and never accumulate. That asymmetry is the entire content of the node,
+ * and it is not something a {@link WorkflowTransformNode} can express: a
+ * transform is a function over what it is given, so a join written as one has to
+ * be handed *both* sides at once — which is why a transform makes
+ * `ConnectorRunnerService` log *"Held all N records in memory"*, and why the
+ * whole-batch version of this exact join reached 78% of a hard 32 MiB output
+ * bound on 44,720 rows before it did anything interesting.
+ *
+ * A per-record transform ({@link CatalogTransform} in `record` mode) cannot do it
+ * either, and the reason is sharper: a function over one record has nowhere to
+ * put the map. It would rebuild it per record, or reach a database per record,
+ * and 44,720 round trips is not a shape anybody would choose on purpose.
+ *
+ * ## What it stays narrow about, deliberately
+ *
+ * The generic transform still exists, and that is what lets this node refuse
+ * every next field forever — the argument {@link WorkflowRenameNode} makes at
+ * length. No join *type* beyond {@link unmatched}, no composite keys, no
+ * expressions on either side, no aggregation of the matched rows. The answer to
+ * "I need more than this" is always *use a transform*, and never *add a field
+ * here*. Two of those refusals have a second reason on top:
+ *
+ * - **No composite key.** Two columns concatenated is a rule about a separator,
+ *   and a separator that occurs inside a value silently merges two different
+ *   keys into one. A {@link WorkflowRenameNode} cannot build one either, which is
+ *   the honest statement: build the key in a transform, then join on it, and the
+ *   separator is a decision somebody wrote down.
+ * - **No expressions on either side.** `UPPER(key)` looks harmless and is the
+ *   single most dangerous thing that could be added, because normalising a key
+ *   is a rule about which of two values are "the same value" — see the note on
+ *   {@link key} about what happens when only one side is normalised.
+ *
+ * ## Where the reference comes from: an edge, named
+ *
+ * The reference is **another node in this graph**, wired into this one, and
+ * {@link reference} says which of the inbound edges it is. Not a connector on
+ * this node, and not the first inbound edge.
+ *
+ * *Not a connector on this node*, because a source is already a modelled thing
+ * with a kind, an optional named connection, a secret, a mode, a config, schema
+ * discovery and a staging path — and putting a second, smaller copy of all that
+ * inside this node would fork it. Wiring a source in instead means the reference
+ * composes with everything: a `catalog` source reads the **current** snapshot of
+ * a published type, resolved when the run reaches it (see `sourceKind: 'catalog'`),
+ * which is the natural reference and names no physical table; a `sql` source
+ * reads a code table straight out of an operational database; and a filter or a
+ * rename may sit in between, which is how a reference with duplicate keys is
+ * made unambiguous (see below) without this node growing a rule for it.
+ *
+ * *Not the first inbound edge*, and this one is the sharp decision. Edge order
+ * is defined and does decide what a multi-input node receives — but for every
+ * other kind, reordering two wires changes only the order rows are concatenated
+ * in, which is at worst cosmetic. Here it would decide **which side is held
+ * entirely in memory**, and swapping them silently turns a working graph into
+ * one that either holds 44,720 rows to enrich 200, or joins the two datasets the
+ * wrong way round and reports success. Reordering edges is invisible on a canvas.
+ * So the node names its reference by node id, and `validateWorkflow` refuses a
+ * name that is not one of its inbound edges.
+ *
+ * ## The counts, which are the point
+ *
+ * The failure this node was built against is not a crash. flip's SUBWO reader
+ * builds exactly these two maps and reads them per row, and when the reference
+ * table is empty it produces **unenriched rows and a green run** — 44,720 rows
+ * with `planName`, `planDescription` and `unitMel` hard null, no error, no
+ * warning, and a documented seeding prerequisite that nothing checks. A zero-match
+ * join is indistinguishable from a working one by looking at the run.
+ *
+ * So the run log always carries three numbers, whatever {@link unmatched} says:
+ * how many rows matched, how many had a key that matched nothing, and how many
+ * had no key at all. The third is separate from the second on purpose — they
+ * have different causes and different fixes, and flip's reader folds both into
+ * the same NULL. A run where nothing matched gets a line of its own, the way
+ * `filterLogLines` calls out a filter that kept nothing.
+ *
+ * ## The decisions, each made rather than discovered
+ *
+ * - **A key that matches nothing** — {@link unmatched}, defaulting to `null`.
+ * - **Two reference rows for one key** — refused, *when they disagree*. See
+ *   {@link fields}.
+ * - **An enriched name the driving row already carries** — filled when it is
+ *   empty, refused when it holds a value. The rule is about destroying data
+ *   rather than about a name being taken, and the distinction is the whole
+ *   usefulness of the node: a published type *declares* the columns it holds, so
+ *   a graph reading one back to enrich it receives every one of them. The real
+ *   measurement is the argument — `SubwoReplica` hands over 44,720 rows all
+ *   carrying `planName`, `planDescription` and `unitMel` with `null` in them,
+ *   which is exactly the three columns this node was built to fill. A target
+ *   holding an actual value is two columns and one name and fails the node,
+ *   naming the row, which is the sentence {@link renameColumnRefusals} says about
+ *   the same problem arriving from the other direction.
+ * - **A reference row with no key** — not indexed, and counted. A real work-plan
+ *   table has them: flip writes `planId: row.planId ?? ""` when a load has no
+ *   plan code, so the empty-string key is in the table by construction and can
+ *   never be matched by anything. Refusing the whole reference over one of those
+ *   would make the node unusable against the data it was built for; indexing it
+ *   silently would let one keyless row become the answer for every keyless
+ *   driving row.
+ */
+export interface WorkflowLookupNode extends WorkflowNodeBase {
+    kind: 'lookup';
+    /**
+     * The id of the inbound node whose rows are the reference side.
+     *
+     * Held in memory for the whole node; everything else wired in streams past it.
+     * `validateWorkflow` refuses an id that is not one of this node's inbound
+     * edges, and refuses a lookup whose *only* inbound edge is this one — a lookup
+     * with nothing to enrich produces nothing, and would commit an empty snapshot.
+     */
+    reference: string;
+    /**
+     * The column on the **driving** row holding the key.
+     *
+     * Deliberately unconstrained in spelling, the way a rename's *source* names
+     * are: `Reg Number` and `Mgmt Cd` are what real drops are keyed by.
+     *
+     * ## How two keys are compared, stated once because it is the whole join
+     *
+     * A key is read off the row, and a value of `null` or `undefined` — or a
+     * column that is absent from that row — means the row **has no key**. It is
+     * counted separately and never matches, including against a reference row
+     * that also has no key.
+     *
+     * Anything else is compared **as a string**, by `String(value)`, with no
+     * trimming, no case folding and no other normalisation.
+     *
+     * The coercion is a decision and so is its limit. It is there because the two
+     * sides routinely come from different engines: a work-plan code arriving as a
+     * MySQL `VARCHAR` and the same code arriving as a number out of a spreadsheet
+     * parser are the same key to everyone except `===`, and a join that matched
+     * nothing for that reason is the exact silent-zero this node reports counts to
+     * prevent. What is *not* done is normalising the shape of the value, because
+     * every one of those is a rule about which of somebody's values are the same
+     * value: `"21 CES"` and `"21CES"` are not the same unit unless a person says
+     * so, and flip's own reader is the cautionary tale — it normalises the driving
+     * unit and compares it against a reference column normalised at write time by
+     * a different screen, so the two agree only for as long as nobody edits either.
+     * If a key needs normalising, normalise it in a transform, on both sides,
+     * where it is visible.
+     */
+    key: string;
+    /** The column on the **reference** row holding the key. Compared as {@link key} describes. */
+    referenceKey: string;
+    /**
+     * Reference column → the name it lands under on the driving row. Never empty;
+     * at most {@link WORKFLOW_LOOKUP_MAX_FIELDS} entries; every target matches
+     * {@link WORKFLOW_FILTER_COLUMN_PATTERN} and no two share one.
+     *
+     * A `Record` rather than a list of pairs, for the reason
+     * {@link WorkflowRenameNode.columns} is one: a key cannot appear twice, so
+     * bringing one reference column across twice is unrepresentable. Two brought
+     * across *onto* one name is representable and refused.
+     *
+     * The target pattern is the identifier rule and it is here for the reason the
+     * rename's targets are: a load looks every field up as `row[name]`, so a name
+     * no property can carry loads NULL into every row and reports success. That is
+     * the failure this node is supposed to be *fixing*, so producing it would be
+     * the trap re-armed one node further along.
+     *
+     * ## Empty is refused rather than treated as a no-op
+     *
+     * A lookup that brings nothing across is a node that draws as configured,
+     * costs a full pass over both sides, and changes nothing — except under `drop`,
+     * where it silently becomes a semi-join that deletes every row whose key is not
+     * in the reference. Two silent opposites reached by deleting the last row of a
+     * form, which is exactly the argument {@link renameColumnRefusals} makes.
+     *
+     * ## Why the fields decide the duplicate-key rule
+     *
+     * Two reference rows for one key means either the join multiplies rows or
+     * something picks a winner, and picking a winner is a rule about whose data
+     * survives — the reasoning {@link renameColumnRefusals} already refused, for
+     * two columns renamed onto one name. Multiplying rows is worse here than it
+     * looks: this node's contract is that it enriches, so a sink downstream would
+     * commit more rows than were read with nothing on the canvas saying why.
+     *
+     * So: **two reference rows for one key are refused when they disagree about
+     * any named field, and collapsed when they agree.** Agreeing costs nobody
+     * anything — there is no winner, the answer is the same either way — and it is
+     * what a real reference table looks like when it has one row per key *and*
+     * something else, which is the common case. Disagreeing fails the node, naming
+     * the key, the field and both values.
+     *
+     * Note what makes this rule cheap and total: it is decided over the **named
+     * fields only**, so two reference rows that differ in a column this node does
+     * not bring across are not a conflict, because nothing about them reaches the
+     * output. And it is decided while the map is built, before a single driving
+     * row is read, so it fails at the start of the node rather than at row ninety
+     * thousand.
+     *
+     * flip's own reader is the argument for refusing rather than choosing. It
+     * builds the plan map with `plansMap.set(plan.planId, plan)`, which keeps the
+     * **last** row; it resolves the unit dictionary with `Array.prototype.find`,
+     * which keeps the **first**; neither key column has a unique constraint; and
+     * the two rules live forty lines apart in one file. Nobody chose either of
+     * them.
+     */
+    fields: Record<string, string>;
+    /**
+     * What happens to a driving row whose key matches nothing. Absent means `null`.
+     *
+     * `null` is the default because it is the only one of the three that changes
+     * neither which rows exist nor whether the run finishes, so it is the one that
+     * can be the answer for a graph nobody has thought about yet. It is also what
+     * flip does today — and the difference this node makes is not the disposition,
+     * it is that the count is reported rather than left to be discovered by
+     * querying the committed snapshot.
+     *
+     * `drop` is an INNER JOIN and it removes rows, so it is never a default: a
+     * lookup wired in front of a full-mode sink under `drop` shrinks a published
+     * type, which is the accident {@link WorkflowFilterNode.narrows} exists about.
+     *
+     * `fail` is for a reference that is a **documented prerequisite**, which is not
+     * a hypothetical: flip's docs make seeding the unit dictionary a prerequisite
+     * of MEL, MVR and SUBWO, and an unseeded one yields unnormalized rows rather
+     * than an error. A load that cannot be enriched is a load that should not
+     * commit, and this is how somebody says so.
+     */
+    unmatched?: WorkflowLookupUnmatched;
+}
+/** {@link WorkflowLookupNode.unmatched}, resolved. One reader of the default. */
+export declare function workflowLookupUnmatched(node: WorkflowLookupNode): WorkflowLookupUnmatched;
+/**
+ * A key, as this node compares them, or `undefined` for a row that has none.
+ *
+ * One function, exported, and called by the runner for both sides — because the
+ * one way a join goes silently wrong is the two sides being read by two pieces
+ * of code that agree today. See {@link WorkflowLookupNode.key} for what it does
+ * and, more to the point, what it deliberately does not do.
+ */
+export declare function workflowLookupKey(value: unknown): string | undefined;
+/**
+ * Every reason a lookup's configuration cannot be stored, as sentences, or empty.
+ *
+ * One function, called by {@link validateWorkflow}, by the HTTP boundary and by
+ * the canvas, for the reason {@link renameColumnRefusals} is: a screen that
+ * checked a target name against its own copy of the pattern is a screen that
+ * eventually accepts something the server refuses, halfway through a save.
+ *
+ * All of them rather than the first, for the reason `refuseUnpublishablePropertyNames`
+ * gives: a form filled in one sitting is usually wrong about several things in
+ * the same way.
+ *
+ * The *wiring* rules — that {@link WorkflowLookupNode.reference} names an inbound
+ * edge, and that something other than the reference is wired in — are not here,
+ * and that is not an omission. They are facts about the graph rather than about
+ * the node, so they cannot be answered from the node alone; `validateWorkflow`
+ * owns them and the inspector reads them from `validateWorkflow`.
+ */
+export declare function lookupConfigRefusals(node: {
+    key?: unknown;
+    referenceKey?: unknown;
+    fields?: Record<string, string>;
+}): string[];
 /**
  * Whether a stored aggregate list is one this build can run.
  *
@@ -2719,13 +3058,25 @@ export declare function aggregateRefusals(node: {
  * under a name somebody put in an object type on purpose.
  */
 export declare function isWorkflowAggregates(value: unknown): value is WorkflowAggregate[];
+/**
+ * Whether a stored field map is one this build can run.
+ *
+ * Refused rather than repaired, the stance {@link isWorkflowRenameColumns} takes
+ * and for the same reason: a map read back with one entry silently dropped is a
+ * graph that commits a column of NULLs under a name nobody can now explain.
+ *
+ * `Object.entries` rather than a `for…in`, so an inherited key cannot enter the
+ * map. The key columns are not checked here because they are not this value;
+ * {@link lookupConfigRefusals} is what sees the whole node.
+ */
+export declare function isWorkflowLookupFields(value: unknown): value is Record<string, 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 | WorkflowIfNode | WorkflowFilterNode | WorkflowRenameNode | WorkflowAggregateNode;
+export type WorkflowNode = WorkflowSourceNode | WorkflowTransformNode | WorkflowSinkNode | WorkflowCallNode | WorkflowIfNode | WorkflowFilterNode | WorkflowRenameNode | WorkflowAggregateNode | WorkflowLookupNode;
 /**
  * The node kinds that can be saved once and used in several graphs.
  *
@@ -2789,6 +3140,11 @@ export declare function isReusableNodeKind(value: unknown): value is ReusableNod
  *   its *output* column set is the thing downstream nodes are validated against,
  *   so a shared node editable from elsewhere would silently change what another
  *   graph's sink is allowed to write.
+ * - `lookup` — that argument, and one that is not an argument at all but an
+ *   impossibility: {@link WorkflowLookupNode.reference} is **a node id in this
+ *   graph**. A shared body carrying one would name a node the adopting graph has
+ *   never had, and it is not a cosmetic field — it is the one that decides which
+ *   side of the join is held in memory.
  */
 export declare const NODE_KIND_IS_REUSABLE: {
     readonly source: true;
@@ -2799,6 +3155,7 @@ export declare const NODE_KIND_IS_REUSABLE: {
     readonly filter: false;
     readonly rename: false;
     readonly aggregate: false;
+    readonly lookup: false;
 };
 /** Whether this kind can be saved as a reusable node. Reads {@link NODE_KIND_IS_REUSABLE}. */
 export declare function nodeKindIsReusable(kind: WorkflowNodeKind): boolean;
@@ -3597,7 +3954,7 @@ export interface CallableWorkflowBlock {
 }
 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", "source-type-not-named", "call-not-named", "call-plain-has-output", "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", "rename-invalid", "aggregate-invalid", "column-not-produced", "version-pin-invalid"];
+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", "source-type-not-named", "call-not-named", "call-plain-has-output", "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", "rename-invalid", "aggregate-invalid", "lookup-invalid", "lookup-reference-not-wired", "lookup-nothing-to-enrich", "column-not-produced", "version-pin-invalid"];
 export type WorkflowIssueCode = (typeof WORKFLOW_ISSUE_CODES)[number];
 export interface WorkflowValidationIssue {
     code: WorkflowIssueCode;
@@ -3830,7 +4187,39 @@ export declare function workflowFilterColumns(predicate: WorkflowFilterPredicate
  * cyclic graph before it gets here, but the canvas calls this while a graph is
  * being drawn and is entitled to a wrong-but-terminating answer.
  */
-export declare function workflowKnownColumns(graph: WorkflowGraph, nodeId: string, knowledge?: WorkflowColumnKnowledge): ReadonlySet<string> | undefined;
+export declare function workflowKnownColumns(graph: WorkflowGraph, nodeId: string, knowledge?: WorkflowColumnKnowledge, onlyFrom?: WorkflowInputFilter): ReadonlySet<string> | undefined;
+/**
+ * Which of a node's inbound edges a question is about.
+ *
+ * One node kind needs this and it is {@link WorkflowLookupNode}, which is the
+ * only one whose inputs are not interchangeable: the reference side is held as a
+ * map and its columns do **not** flow on, so the union of everything wired in is
+ * the wrong answer to "what does this node pass down". Without the distinction
+ * the walk would report the reference's columns as available downstream, and a
+ * filter naming one of them would be accepted by the validator and then match no
+ * row at run time — the precise silent failure `checkColumnsProduced` exists to
+ * catch, produced by the check itself.
+ *
+ * Optional everywhere it appears, and omitting it means every inbound edge —
+ * which is what every other kind wants and what every existing caller gets.
+ */
+export type WorkflowInputFilter = (fromNodeId: string) => boolean;
+/**
+ * The two column sets a lookup sees, told apart.
+ *
+ * Exported because three callers need the same split and each one getting it
+ * right separately is how they come to disagree: the validator refuses a key
+ * column that is not on the driving side, the walk answers what the node passes
+ * on, and the inspector says both out loud on the screen where the columns are
+ * typed.
+ *
+ * Either side answers `undefined` for the ordinary reason — see
+ * {@link workflowKnownColumns} — and `undefined` must not be read as empty.
+ */
+export declare function workflowLookupColumns(graph: WorkflowGraph, node: WorkflowLookupNode, knowledge?: WorkflowColumnKnowledge): {
+    driving: ReadonlySet<string> | undefined;
+    reference: ReadonlySet<string> | undefined;
+};
 /**
  * What a caller can tell the column walk that the graph does not hold.
  *