@dudousxd/nestjs-catalog 0.25.0 → 0.27.0

package/dist/catalog.pipeline.js

@@ -9,8 +9,10 @@
  * 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.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_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_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;
 exports.isSourceFormat = isSourceFormat;
 exports.unreachableSourceFormat = unreachableSourceFormat;
 exports.isTransformLanguage = isTransformLanguage;
@@ -42,6 +44,16 @@ exports.unreachableRenameUnnamed = unreachableRenameUnnamed;
 exports.workflowRenameUnnamed = workflowRenameUnnamed;
 exports.renameColumnRefusals = renameColumnRefusals;
 exports.isWorkflowRenameColumns = isWorkflowRenameColumns;
+exports.isWorkflowAggregateFunction = isWorkflowAggregateFunction;
+exports.unreachableAggregateFunction = unreachableAggregateFunction;
+exports.workflowAggregateMaxGroups = workflowAggregateMaxGroups;
+exports.workflowAggregateSeparator = workflowAggregateSeparator;
+exports.workflowAggregateJoinMaxLength = workflowAggregateJoinMaxLength;
+exports.workflowAggregateNeedsColumn = workflowAggregateNeedsColumn;
+exports.workflowAggregateColumns = workflowAggregateColumns;
+exports.workflowAggregateOutputColumns = workflowAggregateOutputColumns;
+exports.aggregateRefusals = aggregateRefusals;
+exports.isWorkflowAggregates = isWorkflowAggregates;
 exports.isReusableNodeKind = isReusableNodeKind;
 exports.nodeKindIsReusable = nodeKindIsReusable;
 exports.unreachableReusableNodeKind = unreachableReusableNodeKind;
@@ -103,6 +115,45 @@ exports.CONNECTOR_KINDS = [
     's3',
     /** Records pasted into the config. For trying a transform against real shapes. */
     'inline',
+    /**
+     * The catalog's own data: the **current snapshot** of one object type.
+     *
+     * ## Why this is a kind and not a `sql` connector with a clever query
+     *
+     * Because that is what it was, and it was silently wrong. A workflow that
+     * needed rows the catalog already holds had exactly one way to get them — a
+     * `sql` connector naming the physical table, `SELECT … FROM obj_subworeplica`
+     * — and the store **retains every committed snapshot in that table**. So the
+     * read is not the dataset, it is every load that has ever run, stacked.
+     *
+     * Measured, with two snapshots present: the source read 89,440 rows against a
+     * type holding 44,720; the run finished `succeeded`; the rows *written* were
+     * unchanged at 16,119 because the downstream `GROUP BY` collapsed the
+     * duplicates; and every `SUM` doubled — `actualLaborCost` from 212,192,113 to
+     * 424,384,226. The row count, which is the one number anybody checks, did not
+     * move. The graph had been correct once, by the accident of exactly one
+     * snapshot existing at the time it was first run.
+     *
+     * Three things follow, and each of them is why this is a kind of its own
+     * rather than a documented convention about which table to name:
+     *
+     * - **The author names a type, not a table.** `obj_<type>` and `_snapshot_id`
+     *   are internal schema. A graph that spells them is coupled to a storage
+     *   layout it does not own and — as measured — quietly wrong about it.
+     * - **There is no URL and no credential.** Every other kind that reaches a
+     *   database needs an address and a secret, and pointing the catalog at its
+     *   own database meant an operator putting a connection URL on the pod and on
+     *   the secret allowlist: a credential that did not need to exist. This kind
+     *   reads through the store the process already holds.
+     * - **"Current" is resolved when the run starts**, by asking the store which
+     *   snapshot it serves, and a type with nothing committed is refused rather
+     *   than read as zero rows. See `fetchCatalog` in the pipeline package.
+     *
+     * Not connectable — see `CONNECTION_KINDS` in the react package. A connection
+     * is an address and a credential shared by several loads, and this kind has
+     * neither.
+     */
+    'catalog',
 ];
 /**
  * The type is derived from the list, not written beside it.
@@ -116,6 +167,59 @@ exports.CONNECTOR_KINDS = [
 function isConnectorKind(value) {
     return exports.CONNECTOR_KINDS.some((kind) => kind === value);
 }
+/**
+ * The connector kind that never compiles quietly.
+ *
+ * The {@link unreachableNodeKind} of source kinds, and it arrived with
+ * `'catalog'` for the reason that kind arrived: two of the places that decide
+ * something *per source kind* — the fetcher map and the column question below —
+ * were keyed by `string` or answered for `source` as a whole, so a sixth kind
+ * could be added and be picked up by neither. A palette that offers a kind
+ * nothing can read is the failure {@link CONNECTOR_KINDS} opens by describing,
+ * one level down.
+ *
+ * It throws as well as failing to compile, for the reason its sibling does: a
+ * connector's `kind` is a string in a database row, so one written by a newer
+ * deployment and read by an older one is possible, and returning a default for
+ * it would read the wrong system entirely.
+ */
+function unreachableConnectorKind(kind, where) {
+    throw new Error(`${where} does not handle a source of kind ${JSON.stringify(kind)}. The kind list and every decision made per kind are meant to move together.`);
+}
+/**
+ * The config key a `catalog` source names its object type in.
+ *
+ * A constant rather than a literal in four files, because it is the one field
+ * that kind has and it is written by a form, read by a fetcher, checked by a
+ * validator and hashed into the graph's fingerprint.
+ */
+exports.CATALOG_SOURCE_TYPE_KEY = 'objectType';
+/**
+ * Which object type a source reads, when it is a `catalog` source that names one.
+ *
+ * `undefined` covers both "not that kind" and "that kind, unconfigured", and the
+ * two callers want the same thing from both: a source that does not name a type
+ * is not one whose columns are known, and it is one the validator refuses. The
+ * string is trimmed, because a name that differs from a published type only by
+ * surrounding whitespace is a load that resolves nothing at run time and a
+ * refusal nobody can see the cause of.
+ */
+function workflowSourceObjectType(node) {
+    // Both fields read reflectively rather than promised by the signature, for two
+    // reasons that point the same way: the parameter has to accept any node of the
+    // union — a sink carries neither field — and a node arrives out of a JSON
+    // column, where a `config` can be anything at all.
+    if (Reflect.get(node, 'sourceKind') !== 'catalog')
+        return undefined;
+    const config = Reflect.get(node, 'config');
+    if (typeof config !== 'object' || config === null)
+        return undefined;
+    const named = Reflect.get(config, exports.CATALOG_SOURCE_TYPE_KEY);
+    if (typeof named !== 'string')
+        return undefined;
+    const trimmed = named.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
 /**
  * How the bytes behind a `file` or `s3` connector are read as records.
  *
@@ -438,6 +542,8 @@ exports.WORKFLOW_NODE_KINDS = [
     'filter',
     /** Renames columns, declaratively. See {@link WorkflowRenameNode}. */
     'rename',
+    /** Groups records and summarises each group. See {@link WorkflowAggregateNode}. */
+    'aggregate',
 ];
 /** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
 function isWorkflowNodeKind(value) {
@@ -1212,6 +1318,403 @@ 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.`);
+}
+/**
+ * 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;
+}
+/**
+ * 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 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;
+}
 /* --- reusable nodes ------------------------------------------------------ */
 /**
  * The node kinds that can be saved once and used in several graphs.
@@ -1270,6 +1773,13 @@ 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.
  */
 exports.NODE_KIND_IS_REUSABLE = {
     source: true,
@@ -1279,6 +1789,7 @@ exports.NODE_KIND_IS_REUSABLE = {
     if: false,
     filter: false,
     rename: false,
+    aggregate: false,
 };
 /** Whether this kind can be saved as a reusable node. Reads {@link NODE_KIND_IS_REUSABLE}. */
 function nodeKindIsReusable(kind) {
@@ -1667,6 +2178,16 @@ exports.WORKFLOW_ISSUE_CODES = [
     'unreachable',
     'dead-end',
     'transform-not-named',
+    /**
+     * A `catalog` source that does not say which object type it reads.
+     *
+     * The sibling of `transform-not-named`, and it earns a code of its own for the
+     * reason that one has one: the field is the *whole* of what the node does, and
+     * a node missing it fails inside a durable step halfway through a load rather
+     * than on the canvas. Refused rather than defaulted — there is no sensible
+     * type to guess, and guessing would read somebody else's data.
+     */
+    'source-type-not-named',
     'call-not-named',
     /**
      * A plain call wired into something. See {@link WORKFLOW_CALL_MODES}: a plain
@@ -1690,6 +2211,19 @@ 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 node naming a column that nothing upstream can produce.
      *
@@ -1732,8 +2266,16 @@ exports.WORKFLOW_ISSUE_CODES = [
  * point at nodes which do not exist produces a second page of consequences, and
  * burying the one real problem under them is how a validation message stops
  * being read.
+ *
+ * `knowledge` is optional and adds only refusals that could not otherwise be
+ * made: with it, a filter or a rename below a `catalog` source can be told it
+ * names a column the published type does not have. Omitting it is a supported
+ * call and the answer is a subset, never a different one — see
+ * {@link WorkflowColumnKnowledge}. The pure, dependency-free promise this
+ * function opens with is unchanged: the lookup is the caller's, and this reaches
+ * nothing.
  */
-function validateWorkflow(graph) {
+function validateWorkflow(graph, knowledge) {
     const issues = [];
     const nodes = graph.nodes ?? [];
     const edges = graph.edges ?? [];
@@ -1779,7 +2321,7 @@ function validateWorkflow(graph) {
     checkReachability(nodes, roots, sinks, incoming, outgoing, issues);
     // After the cycle check has returned, so the walk it does cannot meet a loop
     // on a graph this function has already accepted as acyclic.
-    checkColumnsProduced({ nodes, edges }, issues);
+    checkColumnsProduced({ nodes, edges }, issues, knowledge);
     return issues;
 }
 /**
@@ -2116,10 +2658,10 @@ function checkBranches(edges, byId, issues) {
 /**
  * A node that names none of the thing it exists to run.
  *
- * The two kinds that point at something outside themselves — a transform at
- * stored code, a call at a registered workflow — and both are reported the same
- * way because they are the same mistake: a box on the canvas with nothing
- * behind it, which looks finished and fails at run time.
+ * The kinds that point at something outside themselves — a transform at stored
+ * code, a call at a registered workflow, a `catalog` source at an object type —
+ * and they are reported the same way because they are the same mistake: a box on
+ * the canvas with nothing behind it, which looks finished and fails at run time.
  */
 function nodeIsUnconfigured(node) {
     if (node.kind === 'transform' && node.transformId.length === 0) {
@@ -2129,6 +2671,20 @@ function nodeIsUnconfigured(node) {
             message: `Transform node "${node.name}" (${node.id}) names no transform, so there is no code for it to run.`,
         };
     }
+    if (node.kind === 'source' && node.sourceKind === 'catalog') {
+        // Only this kind, and only from the config: every other kind's address is
+        // allowed to arrive from a named connection, so a blank field on the node is
+        // not evidence of anything. A `catalog` source has no connection to borrow
+        // from — the type name is the whole configuration — so a blank one is
+        // decidable here.
+        if (workflowSourceObjectType(node) === undefined) {
+            return {
+                code: 'source-type-not-named',
+                nodeIds: [node.id],
+                message: `Source "${node.name}" (${node.id}) reads from the catalog but does not say which object type, so there is nothing for it to read. Name the type on the node; there is no default, because a default would read somebody else's data.`,
+            };
+        }
+    }
     if (node.kind === 'call')
         return callIsUnnamed(node);
     if (node.kind === 'if')
@@ -2137,8 +2693,31 @@ function nodeIsUnconfigured(node) {
         return filterIsUnconfigured(node);
     if (node.kind === 'rename')
         return renameIsUnconfigured(node);
+    if (node.kind === 'aggregate')
+        return aggregateIsUnconfigured(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 rename whose map this service will not store.
  *
@@ -2749,6 +3328,8 @@ function canonicalNode(node) {
     }
     if (node.kind === 'rename')
         return canonicalRename(node);
+    if (node.kind === 'aggregate')
+        return canonicalAggregate(node);
     if (node.kind === 'sink') {
         return JSON.stringify([
             node.id,
@@ -2782,6 +3363,47 @@ 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]),
+    ]);
+}
 /**
  * The reusable reference, as zero, one or two trailing hash components.
  *
@@ -2938,9 +3560,23 @@ function workflowFilterColumns(predicate) {
  *   with some keys re-labelled, and its input is unknown unless something
  *   upstream closed it. So `undefined` propagates, and that is the honest
  *   answer rather than an empty set.
- * - **A source, a transform and a call are always unknown.** A source's shape is
- *   discovered against the live system rather than declared in the graph; a
- *   transform is a function body; a call is a workflow this graph does not own.
+ * - **A transform and a call are always unknown.** A transform is a function
+ *   body; a call is a workflow this graph does not own.
+ * - **A source is unknown, with one exception, and the exception needs a
+ *   lookup.** Every kind that reaches an outside system has a shape discovered
+ *   against that system rather than declared in the graph. A `catalog` source
+ *   is the one kind whose shape is *already published*: it names an object
+ *   type, and the type's properties are exactly the keys its records carry —
+ *   see `fetchCatalog`, which asks the store for those properties by name.
+ *
+ *   But the properties are not in the graph either. The graph holds a type
+ *   **name**; the columns live in the catalog's registry, which this function is
+ *   pure and dependency-free in order not to reach. So the answer is a lookup
+ *   the caller supplies — {@link WorkflowColumnKnowledge} — and with no lookup
+ *   the answer stays `undefined`. That is the honest shape of the claim: a
+ *   caller that can see the catalog gets column checking through a source, which
+ *   nothing else in this file can offer, and a caller that cannot see it is told
+ *   nothing rather than told an empty set.
  * - **It says nothing about a sink's declared properties.** That is the check
  *   worth wanting — "this sink writes a property no upstream node produces" —
  *   and it is *not* available here: a {@link WorkflowSinkNode} carries a
@@ -2952,7 +3588,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) {
+function workflowKnownColumns(graph, nodeId, knowledge) {
     const nodes = graph.nodes ?? [];
     const byId = new Map(nodes.map((node) => [node.id, node]));
     const { incoming } = buildAdjacency(nodes, graph.edges ?? []);
@@ -2969,7 +3605,7 @@ function workflowKnownColumns(graph, nodeId) {
         if (!node)
             return undefined;
         open.add(id);
-        const produced = producedColumns(node, () => intoNode(id));
+        const produced = producedColumns(node, () => intoNode(id), knowledge);
         open.delete(id);
         answered.set(id, produced);
         return produced;
@@ -3005,7 +3641,7 @@ function workflowKnownColumns(graph, nodeId) {
  * here is a compile error rather than a silent `undefined` — which would be the
  * *safe* wrong answer and would therefore never be noticed.
  */
-function producedColumns(node, upstream) {
+function producedColumns(node, upstream, knowledge) {
     if (node.kind === 'rename') {
         if (workflowRenameUnnamed(node) === 'drop')
             return new Set(Object.values(node.columns ?? {}));
@@ -3017,30 +3653,84 @@ function producedColumns(node, upstream) {
             renamed.add(node.columns?.[column] ?? column);
         return renamed;
     }
+    // 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.
     if (node.kind === 'filter' || node.kind === 'if')
         return upstream();
-    // A source's shape is discovered against the live system, a transform's is
-    // inside a function body, a call's belongs to a workflow this graph does not
-    // own, and nothing reads a sink's output. See {@link workflowKnownColumns}.
-    if (node.kind === 'source' ||
-        node.kind === 'transform' ||
-        node.kind === 'call' ||
-        node.kind === 'sink') {
+    // A source is the one kind whose answer depends on which *source* kind it is.
+    if (node.kind === 'source')
+        return sourceProducedColumns(node, knowledge);
+    // A transform's shape is inside a function body, a call's belongs to a workflow
+    // this graph does not own, and nothing reads a sink's output. See
+    // {@link workflowKnownColumns}.
+    if (node.kind === 'transform' || node.kind === 'call' || node.kind === 'sink') {
         return undefined;
     }
     return unreachableNodeKind(node, 'workflowKnownColumns');
 }
+/**
+ * What a source produces, per source kind.
+ *
+ * Exhaustive over {@link CONNECTOR_KINDS} rather than one blanket `undefined`
+ * for the whole node kind, and that is the point of the function existing: the
+ * blanket answer was correct for five kinds and became wrong for the sixth
+ * without anything failing to compile. Ending in
+ * {@link unreachableConnectorKind} makes the seventh a build error here.
+ *
+ * Four of the five outside systems answer `undefined` for the same reason: what
+ * an HTTP endpoint, a file, a bucket or a query produces is discovered against
+ * the live system, and the graph holds an address rather than a shape.
+ *
+ * `inline` answers `undefined` too, and that one is a judgement rather than an
+ * absence. The records are *in the config*, so their keys could be read off
+ * them — but they are a sample somebody pasted to try a transform against, and
+ * a set derived from a sample is not closed: the real load reads the same source
+ * with more records in it and no reason for them to share a key set. Treating
+ * three pasted objects as the definition of a column set would refuse a filter
+ * that is going to be right.
+ *
+ * `catalog` is the one that answers, when a caller supplied the lookup. Its
+ * records are the store's own rows, keyed by the property names of the type it
+ * names — `fetchCatalog` asks for exactly those and the store returns exactly
+ * those — so the set is closed in the sense {@link workflowKnownColumns}
+ * requires: an upper bound that holds whatever is upstream, since nothing is.
+ */
+function sourceProducedColumns(node, knowledge) {
+    const kind = node.sourceKind;
+    if (kind === 'http' || kind === 'sql' || kind === 'file' || kind === 's3' || kind === 'inline') {
+        return undefined;
+    }
+    if (kind === 'catalog') {
+        const named = workflowSourceObjectType(node);
+        if (named === undefined || knowledge === undefined)
+            return undefined;
+        const columns = knowledge.columnsOfType(named);
+        // Absent means "this caller cannot see a type by that name", which is not
+        // the same as a type with no columns and must not become an empty set — a
+        // graph read by a console that has not loaded its types would otherwise have
+        // every filter below the source refused.
+        return columns === undefined ? undefined : new Set(columns);
+    }
+    return unreachableConnectorKind(kind, 'workflowKnownColumns');
+}
 /**
  * That no node names a column the graph can prove is not there.
  *
- * Only where {@link workflowKnownColumns} answers, which is only downstream of a
- * rename that drops what it does not name. Everywhere else this is silent, and
- * that silence is correct rather than a gap being tolerated: refusing a column
- * the graph merely has no opinion about would make every filter downstream of a
- * transform unsaveable.
+ * Only where {@link workflowKnownColumns} answers: downstream of a rename that
+ * drops what it does not name, or — when the caller supplied a
+ * {@link WorkflowColumnKnowledge} — downstream of a `catalog` source, whose
+ * columns are the named type's published properties. Everywhere else this is
+ * silent, and that silence is correct rather than a gap being tolerated:
+ * refusing a column the graph merely has no opinion about would make every
+ * filter downstream of a transform unsaveable.
  *
  * A refusal rather than a warning, because both failures are silent and total.
  * A filter on a column that cannot exist matches no row — a comparison against
@@ -3051,19 +3741,17 @@ function producedColumns(node, upstream) {
  * commits NULL into every row. That is the exact shape `property-names.ts` was
  * written about, one node upstream of where it can be caught.
  */
-function checkColumnsProduced(graph, issues) {
+function checkColumnsProduced(graph, issues, knowledge) {
     for (const node of graph.nodes ?? []) {
         // 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')
+        if (node.kind !== 'filter' && node.kind !== 'rename' && node.kind !== 'aggregate')
             continue;
-        const named = node.kind === 'filter'
-            ? workflowFilterColumns(node.predicate)
-            : Object.keys(node.columns ?? {});
+        const named = columnsNamedBy(node);
         if (named.length === 0)
             continue;
-        const known = workflowKnownColumns(graph, node.id);
+        const known = workflowKnownColumns(graph, node.id, knowledge);
         if (known === undefined)
             continue;
         const missing = named.filter((column) => column.length > 0 && !known.has(column));
@@ -3076,13 +3764,33 @@ function checkColumnsProduced(graph, issues) {
         });
     }
 }
+/**
+ * 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 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'}. A rename above this node drops every column it does not name, 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)
@@ -3141,6 +3849,8 @@ function isWorkflowNode(value) {
     }
     if (kind === 'rename')
         return isRenameNodeShape(value);
+    if (kind === 'aggregate')
+        return isAggregateNodeShape(value);
     if (kind === 'source') {
         const sourceKind = Reflect.get(value, 'sourceKind');
         const config = Reflect.get(value, 'config');
@@ -3164,6 +3874,23 @@ 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 `call` node carries, checked as strictly as a source's.
  *