@dudousxd/nestjs-catalog 0.26.0 → 0.28.0

package/dist/catalog.pipeline.js

@@ -9,7 +9,7 @@
  * systems each believing they decide when a load runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REDACTED_SECRET = exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_CALL_CONTRACT = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_BRANCH_LABELS = exports.NODE_KIND_IS_REUSABLE = exports.REUSABLE_NODE_KINDS = exports.WORKFLOW_RENAME_MAX_COLUMNS = exports.WORKFLOW_RENAME_UNNAMED = exports.WORKFLOW_FILTER_MAX_VALUES = exports.WORKFLOW_FILTER_MAX_DEPTH = exports.WORKFLOW_FILTER_COLUMN_PATTERN = exports.WORKFLOW_FILTER_OPERATORS = exports.WORKFLOW_FILTER_PREDICATE_KINDS = exports.WORKFLOW_PREDICATE_KINDS = exports.WORKFLOW_CALL_MODES = exports.WORKFLOW_ROW_GAP = exports.WORKFLOW_COLUMN_GAP = exports.WORKFLOW_NODE_HEIGHT = exports.WORKFLOW_NODE_WIDTH = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_SKIP_REASONS = exports.CODE_CONTEXT_CONTRACT = exports.TRANSFORM_RUNNER = exports.TRANSFORM_MODES = exports.TRANSFORM_LANGUAGES = exports.SOURCE_FORMATS = exports.CATALOG_SOURCE_TYPE_KEY = exports.CONNECTOR_KINDS = void 0;
+exports.REDACTED_SECRET = exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_CALL_CONTRACT = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_BRANCH_LABELS = exports.NODE_KIND_IS_REUSABLE = exports.REUSABLE_NODE_KINDS = exports.WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS = exports.WORKFLOW_LOOKUP_MAX_FIELDS = exports.WORKFLOW_AGGREGATE_DEFAULT_SEPARATOR = exports.WORKFLOW_AGGREGATE_MAX_SEPARATOR = exports.WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING = exports.WORKFLOW_AGGREGATE_JOIN_MAX_LENGTH = exports.WORKFLOW_AGGREGATE_GROUPS_CEILING = exports.WORKFLOW_AGGREGATE_MAX_GROUPS = exports.WORKFLOW_AGGREGATE_MAX_AGGREGATES = exports.WORKFLOW_AGGREGATE_MAX_GROUP_BY = exports.WORKFLOW_LOOKUP_UNMATCHED = exports.WORKFLOW_AGGREGATE_FUNCTIONS = exports.WORKFLOW_RENAME_MAX_COLUMNS = exports.WORKFLOW_RENAME_UNNAMED = exports.WORKFLOW_FILTER_MAX_VALUES = exports.WORKFLOW_FILTER_MAX_DEPTH = exports.WORKFLOW_FILTER_COLUMN_PATTERN = exports.WORKFLOW_FILTER_OPERATORS = exports.WORKFLOW_FILTER_PREDICATE_KINDS = exports.WORKFLOW_PREDICATE_KINDS = exports.WORKFLOW_CALL_MODES = exports.WORKFLOW_ROW_GAP = exports.WORKFLOW_COLUMN_GAP = exports.WORKFLOW_NODE_HEIGHT = exports.WORKFLOW_NODE_WIDTH = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_SKIP_REASONS = exports.CODE_CONTEXT_CONTRACT = exports.TRANSFORM_RUNNER = exports.TRANSFORM_MODES = exports.TRANSFORM_LANGUAGES = exports.SOURCE_FORMATS = exports.CATALOG_SOURCE_TYPE_KEY = exports.CONNECTOR_KINDS = void 0;
 exports.isConnectorKind = isConnectorKind;
 exports.unreachableConnectorKind = unreachableConnectorKind;
 exports.workflowSourceObjectType = workflowSourceObjectType;
@@ -44,6 +44,22 @@ exports.unreachableRenameUnnamed = unreachableRenameUnnamed;
 exports.workflowRenameUnnamed = workflowRenameUnnamed;
 exports.renameColumnRefusals = renameColumnRefusals;
 exports.isWorkflowRenameColumns = isWorkflowRenameColumns;
+exports.isWorkflowAggregateFunction = isWorkflowAggregateFunction;
+exports.unreachableAggregateFunction = unreachableAggregateFunction;
+exports.isWorkflowLookupUnmatched = isWorkflowLookupUnmatched;
+exports.unreachableLookupUnmatched = unreachableLookupUnmatched;
+exports.workflowAggregateMaxGroups = workflowAggregateMaxGroups;
+exports.workflowAggregateSeparator = workflowAggregateSeparator;
+exports.workflowAggregateJoinMaxLength = workflowAggregateJoinMaxLength;
+exports.workflowAggregateNeedsColumn = workflowAggregateNeedsColumn;
+exports.workflowAggregateColumns = workflowAggregateColumns;
+exports.workflowAggregateOutputColumns = workflowAggregateOutputColumns;
+exports.aggregateRefusals = aggregateRefusals;
+exports.workflowLookupUnmatched = workflowLookupUnmatched;
+exports.workflowLookupKey = workflowLookupKey;
+exports.lookupConfigRefusals = lookupConfigRefusals;
+exports.isWorkflowAggregates = isWorkflowAggregates;
+exports.isWorkflowLookupFields = isWorkflowLookupFields;
 exports.isReusableNodeKind = isReusableNodeKind;
 exports.nodeKindIsReusable = nodeKindIsReusable;
 exports.unreachableReusableNodeKind = unreachableReusableNodeKind;
@@ -64,6 +80,7 @@ exports.workflowNodeRuns = workflowNodeRuns;
 exports.workflowGraphHash = workflowGraphHash;
 exports.workflowFilterColumns = workflowFilterColumns;
 exports.workflowKnownColumns = workflowKnownColumns;
+exports.workflowLookupColumns = workflowLookupColumns;
 exports.isWorkflowNode = isWorkflowNode;
 exports.isWorkflowEdge = isWorkflowEdge;
 exports.supportsWorkflows = supportsWorkflows;
@@ -501,12 +518,25 @@ function isWorkflowSkipReason(value) {
  *   {@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
@@ -532,6 +562,10 @@ exports.WORKFLOW_NODE_KINDS = [
     'filter',
     /** Renames columns, declaratively. See {@link WorkflowRenameNode}. */
     'rename',
+    /** Groups records and summarises each group. See {@link WorkflowAggregateNode}. */
+    'aggregate',
+    /** Enriches each row from a reference dataset, by key. See {@link WorkflowLookupNode}. */
+    'lookup',
 ];
 /** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
 function isWorkflowNodeKind(value) {
@@ -1306,6 +1340,609 @@ function isWorkflowRenameColumns(value) {
     }
     return false;
 }
+/* --- aggregate ----------------------------------------------------------- */
+/**
+ * The aggregate functions this node computes, and the rule that closes the list.
+ *
+ * A closed list with an exhaustiveness guard, for the reason every other list in
+ * this file is one. What is different here is that the list has a **stated
+ * admission rule**, because "we will keep it narrow" is a promise nobody can
+ * check and a rule is:
+ *
+ * > A function is in if it can be computed from a **fixed-size accumulator**,
+ * > and if its answer does not depend on a decision the config would have to
+ * > carry.
+ *
+ * The first half is the node's whole reason to exist. A hash aggregate is cheap
+ * because it holds one entry per group; an accumulator whose size grows with the
+ * number of *rows* in a group puts the rows back in memory and gives up the
+ * property. The second half is what keeps the config from becoming a small
+ * language: a function that needs an extra field to say what it means is a
+ * function whose meaning was not decided.
+ *
+ * What the rule excludes, so the omissions are on the record rather than
+ * implied:
+ *
+ * - **`countDistinct`** — the sharpest one. It needs a set of the distinct
+ *   values *per group per column*, so its accumulator is O(distinct values) and
+ *   a high-cardinality column inside a group holds the load. It is the exact
+ *   thing this node was built to stop doing, wearing an aggregate's name. A
+ *   sketch (HyperLogLog) is fixed-size and is a different function — an
+ *   estimate — which is not something to ship under the word `distinct`.
+ * - **`median`, percentiles, `stddev` of a stream** — all need the values, or a
+ *   digest that is an approximation with an error bound the config would have to
+ *   carry.
+ * - **`first` / `last`** — fixed-size, and excluded on the other half of the
+ *   rule: they mean "in input order", and this node's input order is a
+ *   `SELECT` without an `ORDER BY`. An aggregate that returns a different value
+ *   on a rerun is a load nobody can diff. `min`/`max` are the order-independent
+ *   version and are what somebody reaching for `first` usually wants.
+ * - **Conditional aggregation — `MAX(CASE WHEN … THEN … END)`** — deliberately
+ *   out of scope, and it is the one omission a reader of flip's `wo` query will
+ *   go looking for, because that query has a three-branch status ladder in it.
+ *   Admitting it means admitting a predicate *inside* an aggregate, which is a
+ *   second expression language nested in the first, evaluated per row per
+ *   aggregate. That is transform territory and the generic
+ *   {@link WorkflowTransformNode} still exists. What the ladder actually is, is
+ *   a priority ordering over a closed set of codes, and it composes: map the
+ *   code to a rank in a transform above this node, `min` the rank, map it back
+ *   below. Two cheap per-record steps instead of a language.
+ * - **`avg` is in**, and it is in *because* of the rule rather than despite it.
+ *   It is `sum` and `count` in one accumulator, both of which are already here,
+ *   and SQL has exactly one answer for it. Excluding it would have made the list
+ *   an arbitrary set that happened to cover one query, which is the thing the
+ *   rule is for.
+ */
+exports.WORKFLOW_AGGREGATE_FUNCTIONS = [
+    /** Rows in the group, or non-null values of a column. `COUNT(*)` / `COUNT(c)`. */
+    'count',
+    /** The total. See `addToSum` for the summation error and what is done about it. */
+    'sum',
+    /** The mean of the non-null values. `sum` and `count` in one accumulator. */
+    'avg',
+    /** The least value. See `compareValues` for the order, which is not MySQL's. */
+    'min',
+    /** The greatest value. Same comparison, same docblock. */
+    'max',
+    /** The values, concatenated. `GROUP_CONCAT`, with a bound that refuses. */
+    'join',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowAggregateFunction(value) {
+    return exports.WORKFLOW_AGGREGATE_FUNCTIONS.some((fn) => fn === value);
+}
+/**
+ * {@link unreachableNodeKind}, one level down, and for the identical reason.
+ *
+ * Every branch over {@link WorkflowAggregateFunction} ends here, so a seventh
+ * function added to the list without an accumulator, a finisher, a canonical
+ * form and a sentence is a type error naming the file rather than a node that
+ * saves, draws and then computes nothing. It throws as well, because a function
+ * name arrives as JSON out of a column and a build older than the data is a
+ * thing that happens.
+ */
+function unreachableAggregateFunction(fn, where) {
+    throw new Error(`${where} has no rule for the aggregate function ${JSON.stringify(fn)}. It was added to WORKFLOW_AGGREGATE_FUNCTIONS without teaching this code how to compute it, and guessing would commit a number nobody derived.`);
+}
+/* --- lookup -------------------------------------------------------------- */
+/**
+ * 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.
+ */
+exports.WORKFLOW_LOOKUP_UNMATCHED = [
+    /** The enriched columns are set to `null` on that row. A LEFT JOIN. The default. */
+    'null',
+    /** The row does not reach the next node at all. An INNER JOIN. */
+    'drop',
+    /** The node fails, naming the key. For a reference that is a prerequisite. */
+    'fail',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowLookupUnmatched(value) {
+    return exports.WORKFLOW_LOOKUP_UNMATCHED.some((each) => each === value);
+}
+/**
+ * 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.
+ */
+function unreachableLookupUnmatched(value, where) {
+    throw new Error(`${where} does not handle the lookup disposition ${JSON.stringify(value)}. The list and every decision made per entry are meant to move together.`);
+}
+/**
+ * How many columns one node may group on.
+ *
+ * The same argument {@link WORKFLOW_RENAME_MAX_COLUMNS} makes, plus one specific
+ * to this node: every extra group-by column can only ever *increase* the number
+ * of groups, so a long list is the shape a high-cardinality grouping arrives in.
+ * flip's real derivation groups on two.
+ */
+exports.WORKFLOW_AGGREGATE_MAX_GROUP_BY = 16;
+/**
+ * How many aggregates one node may compute.
+ *
+ * flip's `wo` derivation has 49, so the bound has to be comfortably above that
+ * or the node does not do the job it was written for. Past a few hundred the
+ * thing being expressed is a table definition rather than a summary, and the
+ * cost is real: every aggregate is an accumulator held **per group**, so this
+ * number multiplies {@link WORKFLOW_AGGREGATE_MAX_GROUPS} in the heap.
+ */
+exports.WORKFLOW_AGGREGATE_MAX_AGGREGATES = 256;
+/**
+ * The default ceiling on distinct groups, and the loud refusal that goes with
+ * it.
+ *
+ * A hash aggregate is cheap **only while the groups are far fewer than the
+ * rows**. Group on a near-unique column and it holds one accumulator row per
+ * input row, which is the whole-batch behaviour this node replaces, arrived at
+ * by a different route and with nothing on the canvas to point at. So the
+ * ceiling exists, it is crossed loudly, and the message names the columns being
+ * grouped on — because a bound that is merely reported is a bound that is
+ * discovered by the machine running out of memory.
+ *
+ * A million is chosen against the measurement rather than as a round number:
+ * flip's derivation holds 16,119, so the default is 62× the real case and no
+ * author of a sane grouping ever meets it. What it catches is `groupBy:
+ * ['combinedId']` on a 44,720-row type — a grouping that is *legal*, produces
+ * one group per row, and is somebody having picked the wrong column.
+ *
+ * The number is a proxy and it is worth saying which part it cannot see: what a
+ * group costs in bytes depends on how many aggregates the node has and how long
+ * a `join` grows. The first is bounded by
+ * {@link WORKFLOW_AGGREGATE_MAX_AGGREGATES}; the second has its own bound on the
+ * aggregate, because it is the one accumulator whose size is not fixed by the
+ * group count.
+ */
+exports.WORKFLOW_AGGREGATE_MAX_GROUPS = 1_000_000;
+/**
+ * The highest ceiling an author may ask for.
+ *
+ * Configurable because "how many groups is too many" genuinely depends on the
+ * machine and on how wide the node is, and a hard-coded limit would make the
+ * node unusable for the one legitimate large grouping. Bounded because past this
+ * the answer is not a bigger number — it is that the grouping belongs in the
+ * source query, where the database already has spill-to-disk and this process
+ * does not.
+ */
+exports.WORKFLOW_AGGREGATE_GROUPS_CEILING = 20_000_000;
+/**
+ * The default bound on one joined value, in characters.
+ *
+ * 65,535 because that is what a MySQL `TEXT` column holds, and a value the
+ * target column cannot store is the same defect one layer further down. See
+ * `appendJoin` for the full argument, including the five groups per column that
+ * are silently truncated in production today under a limit of 1,024.
+ */
+exports.WORKFLOW_AGGREGATE_JOIN_MAX_LENGTH = 65_535;
+/** The highest an author may raise a `join` bound to. One `MEDIUMTEXT`. */
+exports.WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING = 16_777_215;
+/** The longest separator a `join` may use. Long enough for `" | "`, short enough not to be data. */
+exports.WORKFLOW_AGGREGATE_MAX_SEPARATOR = 16;
+/** The separator a `join` uses when the aggregate does not name one. */
+exports.WORKFLOW_AGGREGATE_DEFAULT_SEPARATOR = ', ';
+/** {@link WorkflowAggregateNode.maxGroups}, resolved. One reader of the default. */
+function workflowAggregateMaxGroups(node) {
+    const asked = node.maxGroups;
+    if (typeof asked !== 'number' || !Number.isInteger(asked) || asked < 1) {
+        return exports.WORKFLOW_AGGREGATE_MAX_GROUPS;
+    }
+    return Math.min(asked, exports.WORKFLOW_AGGREGATE_GROUPS_CEILING);
+}
+/** {@link WorkflowAggregate.separator}, resolved. One reader of the default. */
+function workflowAggregateSeparator(aggregate) {
+    const asked = aggregate.separator;
+    return typeof asked === 'string' ? asked : exports.WORKFLOW_AGGREGATE_DEFAULT_SEPARATOR;
+}
+/** {@link WorkflowAggregate.maxLength}, resolved. One reader of the default. */
+function workflowAggregateJoinMaxLength(aggregate) {
+    const asked = aggregate.maxLength;
+    if (typeof asked !== 'number' || !Number.isInteger(asked) || asked < 1) {
+        return exports.WORKFLOW_AGGREGATE_JOIN_MAX_LENGTH;
+    }
+    return Math.min(asked, exports.WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING);
+}
+/** Whether this function reads a column. Only `count` may go without one. */
+function workflowAggregateNeedsColumn(fn) {
+    return fn !== 'count';
+}
+/**
+ * The columns an aggregate node **reads**: its group keys and its inputs.
+ *
+ * What `checkColumnsProduced` tests against what the graph can prove is there,
+ * and what the run log reports as never-seen. Deduplicated and in a stable
+ * order, because it goes into a sentence.
+ */
+function workflowAggregateColumns(node) {
+    const columns = new Set();
+    for (const column of node.groupBy ?? []) {
+        if (typeof column === 'string' && column.length > 0)
+            columns.add(column);
+    }
+    for (const aggregate of node.aggregates ?? []) {
+        const column = aggregate?.column;
+        if (typeof column === 'string' && column.length > 0)
+            columns.add(column);
+    }
+    return [...columns];
+}
+/**
+ * The columns an aggregate node **produces**, which is all of them and nothing
+ * else.
+ *
+ * Closed by the config, and closed *exactly* rather than as an upper bound —
+ * every emitted record carries every one of these keys, whatever was upstream
+ * and whatever the values turned out to be. That is a stronger claim than the
+ * one `rename` introduced, and it is stronger for a structural reason: a rename
+ * only produces a target where the input actually held the source column,
+ * whereas an aggregate writes a group's answer whether or not anything in the
+ * group had a value for it.
+ *
+ * The one thing it does not claim is that the values are useful. An aggregate
+ * over a column that no record carried produces the column, holding `null`.
+ */
+function workflowAggregateOutputColumns(node) {
+    const columns = [];
+    for (const column of node.groupBy ?? []) {
+        if (typeof column === 'string' && column.length > 0 && !columns.includes(column)) {
+            columns.push(column);
+        }
+    }
+    for (const aggregate of node.aggregates ?? []) {
+        const as = aggregate?.as;
+        if (typeof as === 'string' && as.length > 0 && !columns.includes(as))
+            columns.push(as);
+    }
+    return columns;
+}
+/**
+ * Every reason an aggregate cannot be stored, as sentences, or empty.
+ *
+ * One function, called by {@link validateWorkflow}, by the HTTP boundary, by the
+ * canvas and by the fold itself, for the reason {@link renameColumnRefusals} is
+ * shared: a screen with its own copy of the identifier pattern is a screen that
+ * accepts something the server refuses, halfway through a save.
+ *
+ * All of them rather than the first, exactly as
+ * {@link refuseUnpublishablePropertyNames} argues: a node with forty aggregates
+ * typed in one sitting is usually wrong about several in the same way.
+ */
+function aggregateRefusals(node) {
+    const groupBy = Array.isArray(node.groupBy) ? node.groupBy : [];
+    const aggregates = Array.isArray(node.aggregates) ? node.aggregates : [];
+    const named = new Set();
+    const refusals = [
+        ...groupByRefusals(groupBy, named),
+        ...aggregatesRefusals(aggregates, named),
+        ...ceilingRefusals(node.maxGroups),
+    ];
+    return refusals;
+}
+/**
+ * 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.
+ */
+exports.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.
+ */
+exports.WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS = 200_000;
+/** {@link WorkflowLookupNode.unmatched}, resolved. One reader of the default. */
+function workflowLookupUnmatched(node) {
+    return node.unmatched ?? 'null';
+}
+/**
+ * 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.
+ */
+function workflowLookupKey(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    // Objects and arrays are refused rather than stringified: `String({})` is
+    // `"[object Object]"`, which is a key that every JSON column in a row would
+    // share, so a join on a mis-chosen column would match everything to everything
+    // and report a very large number of matches.
+    if (typeof value === 'object')
+        return undefined;
+    const key = String(value);
+    // The empty string is "no key", not a key. A reference table writes it where a
+    // code was missing (flip's `planId: row.planId ?? ""`), so treating it as a
+    // value would make one keyless reference row the answer for every keyless
+    // driving row.
+    return key.length === 0 ? undefined : key;
+}
+/**
+ * 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`.
+ */
+function lookupConfigRefusals(node) {
+    const refusals = [];
+    if (typeof node.key !== 'string' || node.key.length === 0) {
+        refusals.push('It names no key column on the rows being enriched, so there is nothing to match on.');
+    }
+    if (typeof node.referenceKey !== 'string' || node.referenceKey.length === 0) {
+        refusals.push('It names no key column on the reference rows, so there is nothing to match against.');
+    }
+    refusals.push(...lookupFieldRefusals(node.fields ?? {}));
+    // Last, so a blank key has already been reported as a blank key rather than as
+    // a collision with itself, and so this reads after the sentences about the map.
+    if (typeof node.key === 'string' && node.key.length > 0) {
+        const onto = Object.entries(node.fields ?? {})
+            .filter(([, to]) => to === node.key)
+            .map(([from]) => JSON.stringify(from));
+        if (onto.length > 0) {
+            refusals.push(`${onto.join(' and ')} would land as ${JSON.stringify(node.key)}, which is the column this node matches on. The key would be overwritten by the reference's copy of it on every row that matched and left alone on every row that did not, so afterwards the column would no longer say which rows were enriched.`);
+        }
+    }
+    return refusals;
+}
+/**
+ * What the grouping half can be wrong about, and the names it accepted.
+ *
+ * The accepted set is threaded out rather than recomputed, because the sharpest
+ * refusal in the file needs both halves: an aggregate writing into a column the
+ * node also groups on is one name holding two values, and only a reader that has
+ * seen the group-by list can see it.
+ */
+function groupByRefusals(groupBy, accepted) {
+    const refusals = [];
+    if (groupBy.length === 0) {
+        refusals.push('It groups on nothing. With no group-by columns an aggregate returns exactly one row whether it read a billion records or none, so a run that summarised everything and a run that read an empty source commit the same thing. If a grand total is wanted, add a constant column in a transform above this node and group on it, so the one row is visible in the graph.');
+    }
+    if (groupBy.length > exports.WORKFLOW_AGGREGATE_MAX_GROUP_BY) {
+        refusals.push(`It groups on ${groupBy.length} columns, and at most ${exports.WORKFLOW_AGGREGATE_MAX_GROUP_BY} may be named. Every extra column can only increase the number of groups, and a long list is the shape a grouping that holds the whole load arrives in.`);
+    }
+    for (const column of groupBy) {
+        if (typeof column !== 'string' || !exports.WORKFLOW_FILTER_COLUMN_PATTERN.test(column)) {
+            refusals.push(`It groups on ${JSON.stringify(column)}, which is not a name a column can have: letters, digits and underscore, starting with a letter or an underscore. A group key comes out under the name it went in under, so a name this service cannot carry downstream is one that loads NULL into every row and reports success. A source whose own headers are spelled like ${JSON.stringify('Work Order Id')} is what a rename node above this one is for.`);
+            continue;
+        }
+        if (accepted.has(column)) {
+            refusals.push(`It groups on ${JSON.stringify(column)} twice. The second one changes no group and produces no second column, so it is either a typo or a column somebody meant to name instead.`);
+            continue;
+        }
+        accepted.add(column);
+    }
+    return refusals;
+}
+/** What the computing half can be wrong about, given the group keys already accepted. */
+function aggregatesRefusals(aggregates, groupedOn) {
+    const refusals = [];
+    if (aggregates.length === 0) {
+        refusals.push('It computes nothing. An aggregate with no functions is a node that emits the distinct combinations of its group-by columns and drops every other column of every row — which is a real operation and a completely different one. Reaching it by deleting the last row of a form is how a published type loses forty columns.');
+    }
+    if (aggregates.length > exports.WORKFLOW_AGGREGATE_MAX_AGGREGATES) {
+        refusals.push(`It computes ${aggregates.length} aggregates, and at most ${exports.WORKFLOW_AGGREGATE_MAX_AGGREGATES} may be named in one node. Every one of them is an accumulator held per group, so this number multiplies the group ceiling in memory.`);
+    }
+    const names = new Map();
+    for (const entry of aggregates) {
+        if (typeof entry !== 'object' || entry === null) {
+            refusals.push(`One aggregate is ${JSON.stringify(entry)} rather than a function, a column and a name.`);
+            continue;
+        }
+        refusals.push(...oneAggregateRefusals(entry, groupedOn, names));
+    }
+    for (const [as, count] of names) {
+        if (count < 2)
+            continue;
+        refusals.push(`${count} aggregates are written out as ${JSON.stringify(as)}. Two columns cannot share one name, and picking a winner would be a rule about which of somebody's numbers survives.`);
+    }
+    return refusals;
+}
+/** One entry of the list: its name, its function, its column, and its two optional fields. */
+function oneAggregateRefusals(entry, groupedOn, names) {
+    const refusals = [];
+    const as = Reflect.get(entry, 'as');
+    const fn = Reflect.get(entry, 'fn');
+    const column = Reflect.get(entry, 'column');
+    const label = typeof as === 'string' && as.length > 0 ? JSON.stringify(as) : 'One aggregate';
+    if (typeof as !== 'string' || !exports.WORKFLOW_FILTER_COLUMN_PATTERN.test(as)) {
+        refusals.push(`${label} is written out as ${JSON.stringify(as)}, which is not a name a column can have: letters, digits and underscore, starting with a letter or an underscore. A load looks every field up as \`row[name]\`, so a column this service cannot name downstream is one that loads NULL into every row and reports success.`);
+    }
+    else {
+        names.set(as, (names.get(as) ?? 0) + 1);
+        if (groupedOn.has(as)) {
+            refusals.push(`${label} writes into a column this node also groups on. One name cannot hold both the group key and a summary of the group, and picking a winner would be a rule about which of somebody's data survives.`);
+        }
+    }
+    if (!isWorkflowAggregateFunction(fn)) {
+        refusals.push(`${label} uses the function ${JSON.stringify(fn)}, which this service cannot compute. The functions are ${exports.WORKFLOW_AGGREGATE_FUNCTIONS.join(', ')}; anything else is a transform.`);
+        return refusals;
+    }
+    if (workflowAggregateNeedsColumn(fn)) {
+        if (typeof column !== 'string' || !exports.WORKFLOW_FILTER_COLUMN_PATTERN.test(column)) {
+            refusals.push(`${label} reads ${JSON.stringify(column)} with ${fn}, and that is not a column name: letters, digits and underscore, starting with a letter or an underscore. Only \`count\` may go without a column, where it means how many records landed in the group.`);
+        }
+    }
+    else if (column !== undefined && !exports.WORKFLOW_FILTER_COLUMN_PATTERN.test(String(column))) {
+        refusals.push(`${label} counts ${JSON.stringify(column)}, and that is not a column name. Leave the column out to count the records in the group, or name one to count its non-null values.`);
+    }
+    refusals.push(...joinFieldRefusals(entry, fn, label));
+    return refusals;
+}
+/**
+ * The half of {@link lookupConfigRefusals} that a field map answers on its own.
+ *
+ * Split out because {@link isWorkflowLookupFields} is handed a map and nothing
+ * else, and calling the whole function with invented key columns would either
+ * report two refusals about keys it was not asked about, or — with plausible
+ * stand-ins — report a collision between a real target and a made-up key. A
+ * guard that fires on the value it was given plus two values it made up is a
+ * guard that rejects a graph for a reason that is not in the graph.
+ */
+function lookupFieldRefusals(fields) {
+    const refusals = [];
+    const entries = Object.entries(fields);
+    if (entries.length === 0) {
+        refusals.push('It brings no fields across. An empty list is refused rather than stored: it is a node that draws as configured, costs a pass over both sides and changes nothing — and with unmatched rows dropped it silently becomes a filter that deletes every row whose key is not in the reference.');
+    }
+    if (entries.length > exports.WORKFLOW_LOOKUP_MAX_FIELDS) {
+        refusals.push(`It brings ${entries.length} fields across, and at most ${exports.WORKFLOW_LOOKUP_MAX_FIELDS} may come from one lookup. Every one of them is held per distinct key for the whole run, and past this the thing being expressed is a second dataset beside this one rather than an enrichment.`);
+    }
+    const targets = new Map();
+    for (const [from, to] of entries) {
+        if (from.length === 0) {
+            refusals.push('One field names no column on the reference rows, so there is nothing for it to bring across.');
+            continue;
+        }
+        if (typeof to !== 'string' || !exports.WORKFLOW_FILTER_COLUMN_PATTERN.test(to)) {
+            refusals.push(`${JSON.stringify(from)} would land as ${JSON.stringify(to)}, which is not a name a column can have: letters, digits and underscore, starting with a letter or an underscore. A load looks every field up as \`row[name]\`, so a column this service cannot name downstream is one that loads NULL into every row and reports success — which is the failure this node exists to end, not to relocate.`);
+            continue;
+        }
+        targets.set(to, [...(targets.get(to) ?? []), from]);
+    }
+    for (const [to, sources] of targets) {
+        if (sources.length < 2)
+            continue;
+        refusals.push(`${sources.map((from) => JSON.stringify(from)).join(' and ')} would both land as ${JSON.stringify(to)}. Two columns cannot share one name, and picking a winner would be a rule about which of somebody's data survives.`);
+    }
+    return refusals;
+}
+/**
+ * The two fields only `join` reads.
+ *
+ * Refused on any other function rather than ignored, which is the rule the whole
+ * config follows: a field that only some functions read is a field somebody sets
+ * on the wrong one and never finds out.
+ */
+function joinFieldRefusals(entry, fn, label) {
+    const refusals = [];
+    const separator = Reflect.get(entry, 'separator');
+    if (separator !== undefined) {
+        if (fn !== 'join') {
+            refusals.push(`${label} carries a separator and computes ${fn}, which has nothing to separate. A field that only some functions read is a field somebody will set on the wrong one and never find out.`);
+        }
+        else if (typeof separator !== 'string' ||
+            separator.length > exports.WORKFLOW_AGGREGATE_MAX_SEPARATOR) {
+            refusals.push(`${label} joins with ${JSON.stringify(separator)}, and a separator has to be text of at most ${exports.WORKFLOW_AGGREGATE_MAX_SEPARATOR} characters. Past that it is data rather than punctuation, and it is data repeated once per record.`);
+        }
+    }
+    const maxLength = Reflect.get(entry, 'maxLength');
+    if (maxLength === undefined)
+        return refusals;
+    if (fn !== 'join') {
+        refusals.push(`${label} carries a maximum length and computes ${fn}, which produces no text to bound.`);
+        return refusals;
+    }
+    if (typeof maxLength !== 'number' ||
+        !Number.isInteger(maxLength) ||
+        maxLength < 1 ||
+        maxLength > exports.WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING) {
+        refusals.push(`${label} bounds its joined value at ${JSON.stringify(maxLength)}, and the bound has to be a whole number of characters between 1 and ${exports.WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING}. Past that the value cannot be stored in the column it is going into, which is the same failure one layer further down.`);
+    }
+    return refusals;
+}
+/** The group ceiling, when the node set one. See {@link WORKFLOW_AGGREGATE_MAX_GROUPS}. */
+function ceilingRefusals(maxGroups) {
+    if (maxGroups === undefined)
+        return [];
+    if (typeof maxGroups === 'number' &&
+        Number.isInteger(maxGroups) &&
+        maxGroups >= 1 &&
+        maxGroups <= exports.WORKFLOW_AGGREGATE_GROUPS_CEILING) {
+        return [];
+    }
+    return [
+        `It caps itself at ${JSON.stringify(maxGroups)} groups, and the cap has to be a whole number between 1 and ${exports.WORKFLOW_AGGREGATE_GROUPS_CEILING}. Past that the answer is not a bigger number — it is that the grouping belongs in the source query, where the database has spill-to-disk and this process does not.`,
+    ];
+}
+/**
+ * Whether a stored aggregate list is one this build can run.
+ *
+ * Refused rather than repaired, the stance {@link isWorkflowRenameColumns} takes
+ * and for the same reason one step further along: an aggregate list read back
+ * with one entry silently dropped is a graph that commits a column of nulls
+ * under a name somebody put in an object type on purpose.
+ */
+function isWorkflowAggregates(value) {
+    if (!Array.isArray(value))
+        return false;
+    return aggregateRefusals({ groupBy: ['x'], aggregates: value }).length === 0;
+}
+/**
+ * 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.
+ */
+function isWorkflowLookupFields(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    const fields = {};
+    for (const [from, to] of entries) {
+        if (typeof to !== 'string')
+            return false;
+        fields[from] = to;
+    }
+    // Only the field-shaped refusals can be answered from this value alone. See
+    // {@link lookupFieldRefusals} for why the whole function is not called here.
+    return lookupFieldRefusals(fields).length === 0;
+}
 /* --- reusable nodes ------------------------------------------------------ */
 /**
  * The node kinds that can be saved once and used in several graphs.
@@ -1364,6 +2001,18 @@ function isReusableNodeKind(value) {
  *   *about* one drop of one file. `Mgmt Cd → mgmtCd` saved under a name and
  *   dropped into a graph reading a different system renames nothing at all, and
  *   the symptom is a column of NULLs rather than a failure.
+ * - `aggregate` — the same again, and it fails in both directions at once. Its
+ *   group-by columns and its inputs name one type's columns, so a shared one
+ *   groups a graph it was not written for on a column that is not there — which
+ *   collapses every record into one null-keyed group rather than erroring. And
+ *   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.
  */
 exports.NODE_KIND_IS_REUSABLE = {
     source: true,
@@ -1373,6 +2022,8 @@ exports.NODE_KIND_IS_REUSABLE = {
     if: false,
     filter: false,
     rename: false,
+    aggregate: false,
+    lookup: false,
 };
 /** Whether this kind can be saved as a reusable node. Reads {@link NODE_KIND_IS_REUSABLE}. */
 function nodeKindIsReusable(kind) {
@@ -1794,6 +2445,42 @@ exports.WORKFLOW_ISSUE_CODES = [
      * {@link renameColumnRefusals} for the sentences.
      */
     'rename-invalid',
+    /**
+     * An aggregate this service will not store: grouping on nothing or on a name
+     * a column cannot have, computing nothing, two aggregates sharing an output
+     * name, a function this build cannot compute, a separator on something that
+     * does not join.
+     *
+     * Every one of those is decidable from the node alone, and every one of them
+     * is silent if it is let through — the two worst being an empty `groupBy`,
+     * which commits exactly one row whether the source held everything or nothing,
+     * and an empty `aggregates`, which drops every column the node does not group
+     * on. See {@link aggregateRefusals} for the sentences.
+     */
+    'aggregate-invalid',
+    /**
+     * A lookup whose configuration cannot be stored: no key on one side or the
+     * other, no fields, too many, or a target that is not a column name, that two
+     * reference columns share, or that would overwrite the key. All from the node
+     * alone — see {@link lookupConfigRefusals} for the sentences.
+     */
+    'lookup-invalid',
+    /**
+     * A lookup whose `reference` does not name one of its inbound edges.
+     *
+     * A code of its own rather than part of `lookup-invalid`, because it is a fact
+     * about the *graph* and points at two boxes: this node and, when it exists, the
+     * node it wrongly names. It is also the one lookup mistake that produces a
+     * green run — with no reference rows to hold, every row comes out enriched with
+     * nulls and the load commits.
+     */
+    'lookup-reference-not-wired',
+    /**
+     * A lookup with nothing wired in but its reference. The reference is held as a
+     * map and never passed on, so the node produces no rows and a full-mode sink
+     * below it commits an empty snapshot over what is published.
+     */
+    'lookup-nothing-to-enrich',
     /**
      * A node naming a column that nothing upstream can produce.
      *
@@ -1870,6 +2557,10 @@ function validateWorkflow(graph, knowledge) {
     const roots = nodes.filter(runsWithoutInput);
     const sinks = nodes.filter((node) => node.kind === 'sink');
     checkNodeWiring(nodes, incoming, outgoing, issues);
+    // After `checkEdges` has returned, so every id named by an edge is a node that
+    // exists and this cannot report a reference whose real problem is a wire
+    // pointing at something deleted.
+    checkLookupWiring(nodes, incoming, byId, issues);
     checkEndpoints(originators, sinks, issues);
     checkBranches(edges, byId, issues);
     checkPlainCallOutputs(nodes, outgoing, byId, issues);
@@ -2263,8 +2954,116 @@ function nodeIsUnconfigured(node) {
         return filterIsUnconfigured(node);
     if (node.kind === 'rename')
         return renameIsUnconfigured(node);
+    if (node.kind === 'aggregate')
+        return aggregateIsUnconfigured(node);
+    if (node.kind === 'lookup')
+        return lookupIsUnconfigured(node);
     return undefined;
 }
+/**
+ * An aggregate this service will not store.
+ *
+ * The refusals come from {@link aggregateRefusals} rather than being restated
+ * here, so the canvas, the HTTP boundary, the validator and the fold itself say
+ * the same sentence about the same node. Every one of them is a *silent* failure
+ * if it were let through, and the two most dangerous point in opposite
+ * directions: no group-by columns commits exactly one row whatever the source
+ * held, and no aggregates commits the distinct group keys with every other
+ * column of every row gone.
+ */
+function aggregateIsUnconfigured(node) {
+    const refusals = aggregateRefusals(node);
+    if (refusals.length === 0)
+        return undefined;
+    return {
+        code: 'aggregate-invalid',
+        nodeIds: [node.id],
+        message: `Aggregate "${node.name}" (${node.id}) cannot be stored as it is. ${refusals.join(' ')}`,
+    };
+}
+/**
+ * A lookup whose configuration this service will not store.
+ *
+ * The refusals come from {@link lookupConfigRefusals} rather than being restated
+ * here, so the canvas, the HTTP boundary and this validator say the same sentence
+ * about the same node. Every one of them is a *silent* failure if let through: no
+ * key column is a join that matches nothing, no fields is a node that either does
+ * nothing or quietly becomes a filter, and a target this service cannot name
+ * downstream loads NULL into every row and reports success.
+ *
+ * The wiring rules are next door in {@link checkLookupWiring}, because they are
+ * facts about the graph rather than about the node — and because a lookup with
+ * the reference edge missing has to point at *two* boxes, which is a thing an
+ * `unconfigured` issue about one node cannot do.
+ */
+function lookupIsUnconfigured(node) {
+    const refusals = lookupConfigRefusals(node);
+    if (refusals.length === 0)
+        return undefined;
+    return {
+        code: 'lookup-invalid',
+        nodeIds: [node.id],
+        message: `Lookup "${node.name}" (${node.id}) cannot be stored as it is. ${refusals.join(' ')}`,
+    };
+}
+/**
+ * A lookup's two edges: the reference it holds, and something to enrich.
+ *
+ * ## Why this is refused here rather than discovered at run time
+ *
+ * Both failures produce a run that finishes. A lookup whose `reference` names a
+ * node that is not wired into it has no reference rows at all, so under the
+ * default disposition every row is enriched with nulls and the load commits —
+ * which is the exact defect this node was built to end, arrived at through the
+ * wiring instead of through the data. A lookup with *only* the reference wired in
+ * has nothing to enrich, so it produces zero rows and a full-mode sink below it
+ * commits an empty snapshot over whatever was live.
+ *
+ * Named by id rather than taken from edge order, and {@link WorkflowLookupNode}
+ * argues why at length: edge order decides which side is held in memory, and
+ * reordering two wires is invisible on a canvas.
+ */
+function checkLookupWiring(nodes, incoming, byId, issues) {
+    for (const node of nodes) {
+        if (node.kind !== 'lookup')
+            continue;
+        const feeds = incoming.get(node.id) ?? [];
+        const named = typeof node.reference === 'string' ? node.reference : '';
+        if (named.length === 0 || !feeds.includes(named)) {
+            issues.push(lookupReferenceNotWired(node, named, feeds, byId));
+            continue;
+        }
+        if (feeds.length < 2) {
+            issues.push({
+                code: 'lookup-nothing-to-enrich',
+                nodeIds: [node.id, named],
+                message: `Lookup "${node.name}" (${node.id}) has only its reference wired into it. The reference is held as a map and is not passed on, so this node would produce no rows at all and a full-mode sink below it would commit an empty snapshot over whatever is published. Wire in the rows you want enriched as well.`,
+            });
+        }
+    }
+}
+/**
+ * The sentence for a reference that is not one of this node's inbound edges.
+ *
+ * Its own function because it has three cases to name — a reference that is
+ * blank, one that names a node in the graph, and one that names nothing at all —
+ * and each has to say something different for the message to be worth reading.
+ * The last two are genuinely different mistakes: the first is a wire that was
+ * never drawn, the second is an id that was typed or that survived a node being
+ * deleted.
+ */
+function lookupReferenceNotWired(node, named, feeds, byId) {
+    const known = byId.get(named);
+    const names = named.length === 0 ? 'no node at all' : known ? `"${known.name}" (${named})` : `"${named}"`;
+    const wired = feeds.length === 0
+        ? 'Nothing is wired into it.'
+        : `What is wired into it is ${listNodes(feeds, byId)}.`;
+    return {
+        code: 'lookup-reference-not-wired',
+        nodeIds: known ? [node.id, named] : [node.id],
+        message: `Lookup "${node.name}" (${node.id}) takes its reference rows from ${names}, which is not wired into it. ${wired} A lookup holds one of its inputs in memory as a map and streams the rest past it, so it has to be told which one — and with no reference rows to hold, every row would come out enriched with nulls and the load would commit.`,
+    };
+}
 /**
  * A rename whose map this service will not store.
  *
@@ -2797,25 +3596,8 @@ function workflowGraphHash(graph) {
 }
 /** The parts of a node that change what a run produces. */
 function canonicalNode(node) {
-    if (node.kind === 'source') {
-        return JSON.stringify([
-            node.id,
-            node.kind,
-            node.sourceKind,
-            node.connectionId ?? '',
-            node.secretEnvVar ?? '',
-            node.mode ?? 'full',
-            // Sorted keys, so a canvas that rewrites the object in a different order
-            // does not look like an edit.
-            sortedEntries(node.config),
-            // Appended only when there is a reference, exactly as `edge.branch` above
-            // is appended only when there is a label, and for the same reason: adding
-            // reusable nodes to this file must not renumber the version of a single
-            // graph that did not change. Every source drawn before they existed
-            // hashes to the string it always did.
-            ...canonicalReuse(node),
-        ]);
-    }
+    if (node.kind === 'source')
+        return canonicalSource(node);
     if (node.kind === 'transform') {
         // The transform's *version as stored* is deliberately not in here, and that
         // has not changed: editing a transform is recorded as a new transform
@@ -2875,6 +3657,10 @@ function canonicalNode(node) {
     }
     if (node.kind === 'rename')
         return canonicalRename(node);
+    if (node.kind === 'aggregate')
+        return canonicalAggregate(node);
+    if (node.kind === 'lookup')
+        return canonicalLookup(node);
     if (node.kind === 'sink') {
         return JSON.stringify([
             node.id,
@@ -2886,6 +3672,34 @@ function canonicalNode(node) {
     }
     return unreachableNodeKind(node, 'workflowGraphHash');
 }
+/**
+ * A source, canonicalised.
+ *
+ * Its own function, beside the ones every other configured kind already has, for
+ * the reason `toTransformNode` is one package over: `canonicalNode` is a
+ * dispatcher, and a dispatcher that also carries the longest of its cases inline
+ * is where the next case gets written inline too. Nothing about what is hashed
+ * changed with the move — this is the string it always produced.
+ */
+function canonicalSource(node) {
+    return JSON.stringify([
+        node.id,
+        node.kind,
+        node.sourceKind,
+        node.connectionId ?? '',
+        node.secretEnvVar ?? '',
+        node.mode ?? 'full',
+        // Sorted keys, so a canvas that rewrites the object in a different order
+        // does not look like an edit.
+        sortedEntries(node.config),
+        // Appended only when there is a reference, exactly as `edge.branch` above
+        // is appended only when there is a label, and for the same reason: adding
+        // reusable nodes to this file must not renumber the version of a single
+        // graph that did not change. Every source drawn before they existed
+        // hashes to the string it always did.
+        ...canonicalReuse(node),
+    ]);
+}
 /**
  * A rename, canonicalised.
  *
@@ -2908,6 +3722,79 @@ function canonicalRename(node) {
         ...(workflowRenameUnnamed(node) === 'drop' ? ['drop'] : []),
     ]);
 }
+/**
+ * An aggregate, canonicalised.
+ *
+ * **`groupBy` is sorted and the aggregates are sorted by output name**, because
+ * neither order changes what the node computes: a set of group-by columns
+ * defines the same groups whatever order they are listed in, and two aggregates
+ * are independent of each other. Order *is* what the output columns come out in,
+ * and a record's key order is not something anything downstream reads — the sink
+ * looks every property up by name. So reordering rows in the inspector is not an
+ * edit and does not bump a version.
+ *
+ * Each aggregate's optional fields are appended **only when set**, exactly as
+ * `edge.branch` and a rename's `unnamed` are, so the default has one spelling.
+ * The point of that rule is the same one every time: adding a node kind to this
+ * file must not renumber a graph that did not change. Here it holds for a
+ * stronger reason as well — no stored graph contains an aggregate node at all,
+ * because this release is the first one in which such a node can be saved, so
+ * every existing graph's canonical string is byte-identical to what it was.
+ */
+function canonicalAggregate(node) {
+    const groupBy = [...(node.groupBy ?? [])].sort();
+    const aggregates = [...(node.aggregates ?? [])]
+        .sort((left, right) => (left.as < right.as ? -1 : left.as > right.as ? 1 : 0))
+        .map((each) => [
+        each.as,
+        each.fn,
+        each.column ?? '',
+        ...(each.separator === undefined ? [] : [each.separator]),
+        ...(each.maxLength === undefined ? [] : [each.maxLength]),
+    ]);
+    return JSON.stringify([
+        node.id,
+        node.kind,
+        groupBy,
+        aggregates,
+        // In the fingerprint because it decides whether a run finishes or refuses,
+        // which is a difference between two runs of "the same" graph worth being
+        // able to point at. Appended only when set, so the default has one spelling.
+        ...(node.maxGroups === undefined ? [] : [node.maxGroups]),
+    ]);
+}
+/**
+ * A lookup, canonicalised.
+ *
+ * `reference` is in here and it is the field somebody would be tempted to leave
+ * out, because it names a node rather than describing an operation. It has to be
+ * in: repointing the reference edge at a different node is a change to what the
+ * load produces on every row, and it is one of the few edits that leaves the
+ * canvas looking identical.
+ *
+ * The fields are sorted by reference column, safe for the reason a rename's map
+ * is: the whole map is applied to one row at once, so its order changes nothing
+ * about the result and a canvas rewriting the object in another order is not an
+ * edit.
+ *
+ * `unmatched` is appended only when it is not the default, exactly as
+ * `edge.branch` is appended only when there is a label. That rule buys nothing
+ * today — no stored graph has a lookup in it, since the kind is new — and it is
+ * followed anyway, because the version *after* this one is where a default gets
+ * normalised onto the node by some canvas and renumbers every graph that has one.
+ */
+function canonicalLookup(node) {
+    const unmatched = workflowLookupUnmatched(node);
+    return JSON.stringify([
+        node.id,
+        node.kind,
+        node.reference,
+        node.key,
+        node.referenceKey,
+        sortedEntries(node.fields),
+        ...(unmatched === 'null' ? [] : [unmatched]),
+    ]);
+}
 /**
  * The reusable reference, as zero, one or two trailing hash components.
  *
@@ -3092,7 +3979,7 @@ function workflowFilterColumns(predicate) {
  * 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.
  */
-function workflowKnownColumns(graph, nodeId, knowledge) {
+function workflowKnownColumns(graph, nodeId, knowledge, onlyFrom) {
     const nodes = graph.nodes ?? [];
     const byId = new Map(nodes.map((node) => [node.id, node]));
     const { incoming } = buildAdjacency(nodes, graph.edges ?? []);
@@ -3109,13 +3996,16 @@ function workflowKnownColumns(graph, nodeId, knowledge) {
         if (!node)
             return undefined;
         open.add(id);
-        const produced = producedColumns(node, () => intoNode(id), knowledge);
+        const produced = producedColumns(node, (only) => intoNode(id, only), knowledge);
         open.delete(id);
+        // Memoised without the filter, and safe because the filter is only ever
+        // applied at the node being *asked about*: `outOf` answers what a node
+        // passes on, which does not depend on who is asking.
         answered.set(id, produced);
         return produced;
     };
-    const intoNode = (id) => {
-        const feeds = incoming.get(id) ?? [];
+    const intoNode = (id, only) => {
+        const feeds = (incoming.get(id) ?? []).filter((from) => only?.(from) ?? true);
         if (feeds.length === 0)
             return undefined;
         const union = new Set();
@@ -3131,7 +4021,28 @@ function workflowKnownColumns(graph, nodeId, knowledge) {
         }
         return union;
     };
-    return intoNode(nodeId);
+    return intoNode(nodeId, onlyFrom);
+}
+/**
+ * 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.
+ */
+function workflowLookupColumns(graph, node, knowledge) {
+    const named = typeof node.reference === 'string' ? node.reference : '';
+    return {
+        driving: workflowKnownColumns(graph, node.id, knowledge, (from) => from !== named),
+        reference: named.length === 0
+            ? undefined
+            : workflowKnownColumns(graph, node.id, knowledge, (from) => from === named),
+    };
 }
 /**
  * What one node passes on, given what reaches it.
@@ -3146,17 +4057,17 @@ function workflowKnownColumns(graph, nodeId, knowledge) {
  * *safe* wrong answer and would therefore never be noticed.
  */
 function producedColumns(node, upstream, knowledge) {
-    if (node.kind === 'rename') {
-        if (workflowRenameUnnamed(node) === 'drop')
-            return new Set(Object.values(node.columns ?? {}));
-        const known = upstream();
-        if (known === undefined)
-            return undefined;
-        const renamed = new Set();
-        for (const column of known)
-            renamed.add(node.columns?.[column] ?? column);
-        return renamed;
-    }
+    if (node.kind === 'lookup')
+        return lookupProducedColumns(node, upstream);
+    if (node.kind === 'rename')
+        return renameProducedColumns(node, upstream);
+    // The one kind whose output set is *exact* rather than an upper bound, and it
+    // is exact without looking upstream at all: an aggregate emits its group-by
+    // columns and its named aggregates on every record it produces, whatever it
+    // was handed and whatever the values turned out to be. See
+    // {@link workflowAggregateOutputColumns} for the one thing it does not claim.
+    if (node.kind === 'aggregate')
+        return new Set(workflowAggregateOutputColumns(node));
     // Neither of these touches a column: a filter decides which *rows* survive and
     // an `if` decides which *nodes* run. Both hand on exactly the shape they were
     // given, which is what makes a closed set survive one.
@@ -3173,6 +4084,50 @@ function producedColumns(node, upstream, knowledge) {
     }
     return unreachableNodeKind(node, 'workflowKnownColumns');
 }
+/**
+ * What a rename passes on, given what reaches it.
+ *
+ * The one that makes the upstream argument a thunk: a rename that drops its
+ * unnamed columns answers from its own config, so the walk stops here rather
+ * than climbing to a source it would learn nothing from.
+ */
+function renameProducedColumns(node, upstream) {
+    if (workflowRenameUnnamed(node) === 'drop')
+        return new Set(Object.values(node.columns ?? {}));
+    const known = upstream();
+    if (known === undefined)
+        return undefined;
+    const renamed = new Set();
+    for (const column of known)
+        renamed.add(node.columns?.[column] ?? column);
+    return renamed;
+}
+/**
+ * What a lookup passes on, which is not what it was given.
+ *
+ * The reference side is asked *not* to contribute, and that is the whole reason
+ * {@link producedColumns} hands its caller a filter. Its rows are held as a map
+ * and never passed on, so a column that only exists over there is not a column
+ * anything below this node can see — and a set that claimed otherwise would make
+ * the validator accept a filter that matches no row, which is the precise failure
+ * `checkColumnsProduced` exists to catch.
+ *
+ * Exact rather than an upper bound, and that is the payoff of the config being
+ * data: what leaves a lookup is what arrived plus the names it was told to add,
+ * and nothing else can appear. Under `unmatched: 'null'` and `'fail'` every row
+ * carries every target; under `'drop'` the rows that would not have are gone, so
+ * it holds there too.
+ */
+function lookupProducedColumns(node, upstream) {
+    const named = typeof node.reference === 'string' ? node.reference : '';
+    const driving = upstream((from) => from !== named);
+    if (driving === undefined)
+        return undefined;
+    const enriched = new Set(driving);
+    for (const to of Object.values(node.fields ?? {}))
+        enriched.add(to);
+    return enriched;
+}
 /**
  * What a source produces, per source kind.
  *
@@ -3243,33 +4198,143 @@ function checkColumnsProduced(graph, issues, knowledge) {
         // Narrowed off the union rather than tested with a property check, so a kind
         // that starts naming columns without being answered for here is a type error
         // at `missingColumnMessage` and not a check that silently passes.
-        if (node.kind !== 'filter' && node.kind !== 'rename')
-            continue;
-        const named = node.kind === 'filter'
-            ? workflowFilterColumns(node.predicate)
-            : Object.keys(node.columns ?? {});
-        if (named.length === 0)
-            continue;
-        const known = workflowKnownColumns(graph, node.id, knowledge);
-        if (known === undefined)
-            continue;
-        const missing = named.filter((column) => column.length > 0 && !known.has(column));
-        if (missing.length === 0)
-            continue;
+        if (node.kind === 'lookup')
+            checkLookupColumns(graph, node, issues, knowledge);
+        else if (node.kind === 'filter' || node.kind === 'rename' || node.kind === 'aggregate') {
+            checkNamedColumns(graph, node, issues, knowledge);
+        }
+    }
+}
+/**
+ * The columns a node names, per kind that names any.
+ *
+ * Its own function so the union it takes and the union
+ * {@link missingColumnMessage} takes are the same three kinds written down
+ * twice — which is what makes a fourth kind that starts naming columns a type
+ * error in both places rather than a check that silently passes.
+ */
+function columnsNamedBy(node) {
+    if (node.kind === 'filter')
+        return workflowFilterColumns(node.predicate);
+    if (node.kind === 'rename')
+        return Object.keys(node.columns ?? {});
+    return workflowAggregateColumns(node);
+}
+/**
+ * The columns a filter, a rename or an aggregate names, checked against
+ * everything reaching the node.
+ *
+ * The union is the right set for these three, and it is the whole difference
+ * from {@link checkLookupColumns}: the rows a multi-input node receives arrive
+ * concatenated, so a column any one of its inputs carries is a column it can
+ * see. A lookup is the one kind that is not like that — its reference is held as
+ * a map and never passed on — which is why it is dispatched away from here
+ * rather than folded in.
+ */
+function checkNamedColumns(graph, node, issues, knowledge) {
+    const named = columnsNamedBy(node);
+    if (named.length === 0)
+        return;
+    const known = workflowKnownColumns(graph, node.id, knowledge);
+    if (known === undefined)
+        return;
+    const missing = named.filter((column) => column.length > 0 && !known.has(column));
+    if (missing.length === 0)
+        return;
+    issues.push({
+        code: 'column-not-produced',
+        nodeIds: [node.id],
+        message: missingColumnMessage(node, missing, known),
+    });
+}
+/**
+ * A lookup's columns, checked against the side each of them lives on.
+ *
+ * Its own function rather than a branch inside {@link checkColumnsProduced},
+ * because a lookup is the one node whose named columns do not all come from one
+ * place: `key` is on the rows being enriched, and `referenceKey` and every field
+ * source are on the reference. Folding it into the loop above would have meant
+ * checking both against the union — which is *worse than not checking*, because
+ * the union would accept a key column that only exists on the reference. That
+ * join matches nothing on every row and the load commits, which is what this node
+ * is for.
+ *
+ * What is deliberately **not** checked here is a field landing on a name the
+ * driving rows already carry. See {@link checkLookupDriving}.
+ *
+ * Every check is skipped where the set is unknown, for the reason the walk
+ * answers `undefined` rather than empty: silence is correct here, and refusing a
+ * column the graph merely has no opinion about would make every lookup below a
+ * transform unsaveable.
+ */
+function checkLookupColumns(graph, node, issues, knowledge) {
+    const { driving, reference } = workflowLookupColumns(graph, node, knowledge);
+    if (driving !== undefined)
+        checkLookupDriving(node, driving, issues);
+    if (reference !== undefined)
+        checkLookupReference(node, reference, issues);
+}
+/** `"a", "b"`, for a message that has to name a set of columns. */
+function quotedColumns(names) {
+    return [...names].map((column) => JSON.stringify(column)).join(', ');
+}
+/**
+ * The key this lookup matches on, against the rows it enriches.
+ *
+ * The *driving* set specifically, and pooling the inputs would make this wrong in
+ * the dangerous direction: a key column that exists only on the reference would
+ * be accepted here and then match nothing on every row.
+ *
+ * ## Why a name the driving rows already carry is not refused here
+ *
+ * Because *that is the normal case*, and refusing it made the node unable to do
+ * the one thing it was built for. A published object type declares the columns it
+ * holds, so a graph that reads a type back to enrich it receives every one of
+ * those columns — `SubwoReplica` hands over 44,720 rows all carrying `planName`,
+ * `planDescription` and `unitMel` with `null` in them, which is precisely the
+ * three columns the lookup exists to fill. Whether a column holds a *value* is a
+ * fact about the data and not about the graph, so the run decides it, per row:
+ * empty is filled and occupied fails the node, naming the row. See
+ * `withLookupFields`.
+ */
+function checkLookupDriving(node, driving, issues) {
+    if (typeof node.key === 'string' && node.key.length > 0 && !driving.has(node.key)) {
         issues.push({
             code: 'column-not-produced',
             nodeIds: [node.id],
-            message: missingColumnMessage(node, missing, known),
+            message: `Lookup "${node.name}" (${node.id}) matches on ${quotedColumns([node.key])}, and nothing feeding the rows it enriches produces that column. Something above this node closes the column set — a rename that drops what it does not name, or a source reading a published object type — so what reaches here is exactly ${quotedColumns(driving)}. A key column that is not there has no key on any row, so nothing would match and every row would come out with the enriched columns null.`,
         });
     }
 }
+/** The reference key and every field source, against the reference side only. */
+function checkLookupReference(node, reference, issues) {
+    const wanted = [
+        ...(typeof node.referenceKey === 'string' && node.referenceKey.length > 0
+            ? [node.referenceKey]
+            : []),
+        ...Object.keys(node.fields ?? {}).filter((from) => from.length > 0),
+    ];
+    const missing = wanted.filter((column) => !reference.has(column));
+    if (missing.length === 0)
+        return;
+    issues.push({
+        code: 'column-not-produced',
+        nodeIds: [node.id, node.reference],
+        message: `Lookup "${node.name}" (${node.id}) reads ${quotedColumns(missing)} off its reference rows, and nothing on that side produces ${missing.length === 1 ? 'that column' : 'those columns'} — what reaches it is exactly ${quotedColumns(reference)}. A reference key that is not there means no reference row has a key, so nothing matches; a field that is not there lands as undefined on every row that did.`,
+    });
+}
 /** The sentence {@link checkColumnsProduced} says, per kind. */
 function missingColumnMessage(node, missing, known) {
     const quoted = (names) => [...names].map((column) => JSON.stringify(column)).join(', ');
     const consequence = node.kind === 'filter'
         ? 'A test on a column that is not there matches no row — not even a "does not equal" test — so this load would come out empty and every node would report success.'
-        : 'A rename of a column that is not there does nothing, so the column it was meant to produce is absent and a sink writing it commits NULL into every row.';
-    return `${node.kind === 'filter' ? 'Filter' : 'Rename'} "${node.name}" (${node.id}) names ${quoted(missing)}, and nothing upstream produces ${missing.length === 1 ? 'that column' : 'those columns'}. Something above this node closes the column set — a rename that drops what it does not name, or a source reading a published object type — so what reaches here is exactly ${quoted(known)}. ${consequence}`;
+        : node.kind === 'rename'
+            ? 'A rename of a column that is not there does nothing, so the column it was meant to produce is absent and a sink writing it commits NULL into every row.'
+            : // Both halves of an aggregate fail silently, and they fail differently,
+                // which is why this sentence names both rather than picking one.
+                'Grouping on a column that is not there puts every record into one null-keyed group, so a summary of sixteen thousand work orders comes out as a single row. Aggregating one that is not there answers null for every group, which a sink commits as a column of NULLs. Neither reports an error.';
+    const label = node.kind === 'filter' ? 'Filter' : node.kind === 'rename' ? 'Rename' : 'Aggregate';
+    return `${label} "${node.name}" (${node.id}) names ${quoted(missing)}, and nothing upstream produces ${missing.length === 1 ? 'that column' : 'those columns'}. Something above this node closes the column set — a rename that drops what it does not name, an aggregate, or a source reading a published object type — so what reaches here is exactly ${quoted(known)}. ${consequence}`;
 }
 function sortedEntries(config) {
     return Object.keys(config)
@@ -3328,13 +4393,27 @@ function isWorkflowNode(value) {
     }
     if (kind === 'rename')
         return isRenameNodeShape(value);
-    if (kind === 'source') {
-        const sourceKind = Reflect.get(value, 'sourceKind');
-        const config = Reflect.get(value, 'config');
-        return isConnectorKind(sourceKind) && typeof config === 'object' && config !== null;
-    }
+    if (kind === 'aggregate')
+        return isAggregateNodeShape(value);
+    if (kind === 'lookup')
+        return isLookupNodeShape(value);
+    if (kind === 'source')
+        return isSourceNodeShape(value);
     return isWorkflowNodeKindUnhandled(kind);
 }
+/**
+ * Everything a `source` node carries.
+ *
+ * Its own function beside the four kinds that already have one, and for the
+ * reason those have one: {@link isWorkflowNode} is a narrowing dispatcher, and a
+ * dispatcher that also carries its cases inline stops being readable at exactly
+ * the point a new kind is added to it.
+ */
+function isSourceNodeShape(value) {
+    const sourceKind = Reflect.get(value, 'sourceKind');
+    const config = Reflect.get(value, 'config');
+    return isConnectorKind(sourceKind) && typeof config === 'object' && config !== null;
+}
 /**
  * Everything a `rename` node carries.
  *
@@ -3351,6 +4430,52 @@ function isRenameNodeShape(value) {
         return false;
     return isWorkflowRenameColumns(Reflect.get(value, 'columns'));
 }
+/**
+ * Everything an `aggregate` node carries, through the one refusal list.
+ *
+ * The whole node rather than field by field, so a stored aggregate is read back
+ * under exactly the rule that would have refused to store it. Refused rather
+ * than repaired, the stance every guard in this file takes: an aggregate read
+ * back with one entry silently dropped is a load that commits a column of nulls
+ * under a name somebody put in an object type on purpose, and one read back with
+ * its `groupBy` dropped is a load that commits a single row.
+ */
+function isAggregateNodeShape(value) {
+    return (aggregateRefusals({
+        groupBy: Reflect.get(value, 'groupBy'),
+        aggregates: Reflect.get(value, 'aggregates'),
+        maxGroups: Reflect.get(value, 'maxGroups'),
+    }).length === 0);
+}
+/**
+ * Everything a `lookup` node carries.
+ *
+ * `reference` is checked as a non-empty string and no further, because whether
+ * it names a node that is actually wired in is a fact about the graph and this
+ * guard sees one node. `validateWorkflow` owns that, and refuses it loudly.
+ *
+ * An unrecognised `unmatched` is refused rather than defaulted, and this is the
+ * one where defaulting would be worst of the three kinds that have the same
+ * field: reading an unknown word back as `null` would turn a `fail` — which
+ * somebody chose because the reference is a prerequisite — into a load that
+ * commits nulls and reports success.
+ */
+function isLookupNodeShape(value) {
+    const unmatched = Reflect.get(value, 'unmatched');
+    if (unmatched !== undefined && !isWorkflowLookupUnmatched(unmatched))
+        return false;
+    const reference = Reflect.get(value, 'reference');
+    if (typeof reference !== 'string' || reference.length === 0)
+        return false;
+    // Read into an `unknown` before the guard, so the narrowing that follows is
+    // the guard's and not an assertion dressed as one.
+    const fields = Reflect.get(value, 'fields');
+    if (!isWorkflowLookupFields(fields))
+        return false;
+    const key = Reflect.get(value, 'key');
+    const referenceKey = Reflect.get(value, 'referenceKey');
+    return lookupConfigRefusals({ key, referenceKey, fields }).length === 0;
+}
 /**
  * Everything a `call` node carries, checked as strictly as a source's.
  *