@dudousxd/nestjs-catalog 0.16.0-preview.0 → 0.17.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.WORKFLOW_PREDICATE_KINDS = 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_LANGUAGES = 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.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_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_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
 exports.isConnectorKind = isConnectorKind;
 exports.isTransformLanguage = isTransformLanguage;
 exports.isWorkflowSkipReason = isWorkflowSkipReason;
@@ -20,12 +20,20 @@ exports.workflowRowY = workflowRowY;
 exports.isWorkflowPredicateKind = isWorkflowPredicateKind;
 exports.unreachablePredicateKind = unreachablePredicateKind;
 exports.isWorkflowIfPredicate = isWorkflowIfPredicate;
+exports.isWorkflowFilterPredicateKind = isWorkflowFilterPredicateKind;
+exports.unreachableFilterPredicateKind = unreachableFilterPredicateKind;
+exports.isWorkflowFilterOperator = isWorkflowFilterOperator;
+exports.unreachableFilterOperator = unreachableFilterOperator;
+exports.isWorkflowFilterValue = isWorkflowFilterValue;
+exports.isWorkflowFilterPredicate = isWorkflowFilterPredicate;
+exports.workflowFilterMatches = workflowFilterMatches;
 exports.isWorkflowBranchLabel = isWorkflowBranchLabel;
 exports.isWorkflowStatus = isWorkflowStatus;
 exports.isWorkflowExecutionMode = isWorkflowExecutionMode;
 exports.readWorkflowCallOutput = readWorkflowCallOutput;
 exports.callableWorkflowBlock = callableWorkflowBlock;
 exports.validateWorkflow = validateWorkflow;
+exports.workflowNarrowedTypes = workflowNarrowedTypes;
 exports.workflowRunOrder = workflowRunOrder;
 exports.workflowNodeRuns = workflowNodeRuns;
 exports.workflowGraphHash = workflowGraphHash;
@@ -147,10 +155,22 @@ function isWorkflowSkipReason(value) {
  * The kinds that were considered and rejected, since a small vocabulary is only
  * defensible if the omissions are:
  *
- * - **filter** — a transform whose code returns a subset of what it was given.
- *   It needs no new execution path, only a different body, and adding the kind
- *   would mean two ways to drop rows and two places to look when rows go
- *   missing.
+ * - **filter** — *this entry used to be a rejection, and it is worth leaving the
+ *   reversal visible rather than editing the history out.* The argument was that
+ *   a transform whose code returns a subset already filters, so the kind bought
+ *   a second way to drop rows and a second place to look when rows went missing.
+ *   That argument is sound about *code* and it is the reason
+ *   {@link WorkflowFilterNode} does not take any: what changed is that the
+ *   predicate is a **closed structure** rather than a body, and a closed
+ *   structure can be read by something other than a JavaScript engine. Only a
+ *   declarative predicate can be translated into a `WHERE` and pushed into the
+ *   query the source already runs, and that is not a micro-optimisation — a
+ *   transform filtering `obj_pribuybuylistdetail` reads all 7,637,391 rows off
+ *   disk, over the network, and into JS objects of ~80 properties each before
+ *   anything decides they were unwanted. See {@link WorkflowFilterNode} for what
+ *   is actually built today (an in-memory, per-batch pass) and for where the
+ *   pushdown seam is, which is a promise about a shape rather than a claim about
+ *   a measurement.
  * - **branch / split (unconditional)** — already expressible, and still is: a
  *   node with two outbound edges is read by both successors, each of which
  *   filters differently. There is nothing for an *unconditional* split to do.
@@ -184,6 +204,8 @@ exports.WORKFLOW_NODE_KINDS = [
     'call',
     /** Sends the rows down one of its outbound branches. See {@link WorkflowIfNode}. */
     'if',
+    /** Drops the rows that fail a declarative test. See {@link WorkflowFilterNode}. */
+    'filter',
 ];
 /** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
 function isWorkflowNodeKind(value) {
@@ -356,6 +378,395 @@ function isWorkflowPredicateKindUnhandled(kind) {
     void kind;
     return false;
 }
+/* ---------------------------------------------------------------------------
+ * The filter node, and the predicate language it drops rows by.
+ * ------------------------------------------------------------------------- */
+/**
+ * The shapes a {@link WorkflowFilterPredicate} can take.
+ *
+ * Two leaf kinds plus a presence test plus two ways to combine them, and the
+ * list is closed for the same reason {@link WORKFLOW_PREDICATE_KINDS} is: every
+ * decision made per kind ends in {@link unreachableFilterPredicateKind}, so a
+ * sixth shape is a build failure naming the files that owe it an answer rather
+ * than a filter that saves, draws, and quietly keeps everything.
+ *
+ * **There is deliberately no `not`.** Every leaf carries its own inverse
+ * ({@link WORKFLOW_FILTER_OPERATORS} pairs each operator with one, `oneOf` has
+ * `notIn`, `present` has `isNotNull`) and `all`/`any` are duals, so De Morgan
+ * already writes any negation with the kinds here. A `not` node would be a
+ * second spelling of every predicate — two shapes to read when a load comes out
+ * short, and a UI with a checkbox nobody agrees on the placement of. The one
+ * case it does not cover is stated on {@link workflowFilterMatches}: a value the
+ * test cannot compare fails *both* a form and its inverse, on purpose.
+ *
+ * **There is deliberately no free-form expression and no code.** That is the
+ * whole argument for the node existing — see {@link WorkflowFilterNode}.
+ */
+exports.WORKFLOW_FILTER_PREDICATE_KINDS = [
+    /** One column against one value. See {@link WorkflowFilterComparison}. */
+    'compare',
+    /** One column against a list. See {@link WorkflowFilterOneOf}. */
+    'oneOf',
+    /** Whether a column has a value at all. See {@link WorkflowFilterPresence}. */
+    'present',
+    /** Every child holds. See {@link WorkflowFilterGroup}. */
+    'all',
+    /** At least one child holds. See {@link WorkflowFilterGroup}. */
+    'any',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowFilterPredicateKind(value) {
+    return exports.WORKFLOW_FILTER_PREDICATE_KINDS.some((kind) => kind === value);
+}
+/**
+ * {@link unreachablePredicateKind}, for the filter language, and for the
+ * identical reason.
+ *
+ * It throws as well as failing to compile: a predicate arrives as JSON out of a
+ * column, so a graph saved by a newer build and read by an older one is a thing
+ * that happens, and returning a default for a shape this build has no rule for
+ * would mean silently keeping — or silently dropping — every row.
+ */
+function unreachableFilterPredicateKind(predicate, where) {
+    const kind = typeof predicate === 'string' ? predicate : Reflect.get(Object(predicate), 'kind');
+    throw new Error(`${where} does not handle a filter predicate of kind ${JSON.stringify(kind)}. The predicate kinds and every decision made per kind are meant to move together.`);
+}
+/**
+ * What a {@link WorkflowFilterComparison} does with its column and its value.
+ *
+ * Ten, in five inverse pairs, and the pairing is the reason there is no `not`
+ * kind. Each one has an obvious single-expression form in both dialects this
+ * repository speaks, which is not a coincidence — it is the constraint the list
+ * was chosen under, so that the day a predicate is pushed into a source query
+ * the translation is a `switch` and not a design.
+ *
+ * The omissions, since a closed list is only defensible if they are:
+ *
+ * - **`between`** — `all` of a `greaterThanOrEqual` and a `lessThanOrEqual`, in
+ *   one more click and with no second shape to validate, hash and translate.
+ * - **`endsWith`** — asked for far less than the other two, and unlike them it
+ *   has no index that could ever serve it in either dialect, so offering it in a
+ *   palette would advertise something that is a full scan by construction.
+ *   `contains` covers it at the same cost.
+ * - **regular expressions** — the dialects disagree about the syntax, the
+ *   engines disagree about the semantics, and a predicate whose meaning depends
+ *   on which database answered it is a predicate that cannot be pushed down
+ *   without changing what the load returns. That is the one property this list
+ *   exists to hold.
+ * - **case-insensitive variants** — collation is a property of the column in
+ *   both dialects, so a `equalsIgnoreCase` evaluated in memory and the same
+ *   predicate evaluated in a `WHERE` would legitimately disagree. Normalise in a
+ *   transform, where the disagreement is visible.
+ */
+exports.WORKFLOW_FILTER_OPERATORS = [
+    'equals',
+    'notEquals',
+    'greaterThan',
+    'lessThanOrEqual',
+    'greaterThanOrEqual',
+    'lessThan',
+    'contains',
+    'notContains',
+    'startsWith',
+    'notStartsWith',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowFilterOperator(value) {
+    return exports.WORKFLOW_FILTER_OPERATORS.some((operator) => operator === value);
+}
+/**
+ * {@link unreachableFilterPredicateKind}, one level further down.
+ *
+ * An operator added to the list without a rule for evaluating it, describing it
+ * or hashing it is a type error naming the file — not a comparison that silently
+ * answers false for every row, which is a filter that drops the whole dataset
+ * and reports success.
+ */
+function unreachableFilterOperator(operator, where) {
+    throw new Error(`${where} does not handle the filter operator ${JSON.stringify(operator)}. The operator list and every decision made per operator are meant to move together.`);
+}
+/** Whether a stored value is one this language can compare against. */
+function isWorkflowFilterValue(value) {
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    // `NaN` and the infinities are refused rather than kept: every comparison
+    // against `NaN` is false, so a predicate holding one is a filter that drops
+    // every row while looking perfectly well configured, and `Infinity` does not
+    // survive a JSON round trip at all — it comes back as `null`.
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/**
+ * The column names a predicate may name.
+ *
+ * **The same pattern `boundStatement` requires of a watermark column**, and that
+ * is the point rather than a coincidence: an identifier cannot be bound by any
+ * driver, so pushing a predicate into a query means quoting the column into the
+ * SQL, and a name carrying a quote, a dot or a space is refused rather than
+ * escaped. Requiring it *now*, while the predicate is only ever evaluated in
+ * memory, is what stops a graph being authored today that could never be pushed
+ * down tomorrow.
+ *
+ * The cost, and it is real: a source whose column is called `Part Number` cannot
+ * be filtered directly. Rename it in a transform first — which is a node that
+ * already exists and whose output is a column this can name.
+ */
+exports.WORKFLOW_FILTER_COLUMN_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+/**
+ * How deep `all`/`any` may nest.
+ *
+ * A bound rather than a trust, because a predicate arrives as JSON out of a
+ * column and every function that walks one is recursive: a graph carrying a
+ * thousand-deep tree would be a stack overflow inside a durable step rather than
+ * a refusal naming the node. Six is past anything a person builds in a form and
+ * far short of anything that costs a frame to walk.
+ */
+exports.WORKFLOW_FILTER_MAX_DEPTH = 6;
+/**
+ * How many values one {@link WorkflowFilterOneOf} may list.
+ *
+ * Bounded because the list travels in the graph, into the graph fingerprint, and
+ * eventually into an `IN (...)` — and past a few hundred entries all three of
+ * those stop being reasonable and the thing being expressed is a join against
+ * another dataset rather than a filter. Wire that dataset in as a second source
+ * and join it in a transform, which is the node that can.
+ */
+exports.WORKFLOW_FILTER_MAX_VALUES = 500;
+/**
+ * Narrow a stored filter predicate, refusing rather than repairing.
+ *
+ * The same contract {@link isWorkflowIfPredicate} has and for a sharper version
+ * of the same reason: a gate read back without its test picks a branch nobody
+ * authored, and a *filter* read back without its test decides which rows exist.
+ * Repairing a broken predicate — dropping an unreadable child out of an `all`,
+ * say — would silently widen or narrow what a load publishes, which is precisely
+ * the failure the node is built to make visible.
+ *
+ * Depth is carried rather than tracked globally so that the bound is on the
+ * *tree*, not on how many predicates have been checked: two sibling branches
+ * five deep are fine, and one branch seven deep is not.
+ */
+function isWorkflowFilterPredicate(value, depth = 0) {
+    if (depth > exports.WORKFLOW_FILTER_MAX_DEPTH)
+        return false;
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const kind = Reflect.get(value, 'kind');
+    if (!isWorkflowFilterPredicateKind(kind))
+        return false;
+    if (kind === 'all' || kind === 'any') {
+        const children = Reflect.get(value, 'children');
+        if (!Array.isArray(children) || children.length === 0)
+            return false;
+        return children.every((child) => isWorkflowFilterPredicate(child, depth + 1));
+    }
+    const column = Reflect.get(value, 'column');
+    if (typeof column !== 'string' || !exports.WORKFLOW_FILTER_COLUMN_PATTERN.test(column))
+        return false;
+    return isFilterLeaf(value, kind);
+}
+/**
+ * The half of {@link isWorkflowFilterPredicate} that is about one condition.
+ *
+ * Split off because the two halves have nothing to do with each other: above is
+ * a tree walk with a depth bound, and this is three shapes checked field by
+ * field. Reached only with the column already accepted, which is why it does not
+ * check one.
+ */
+function isFilterLeaf(value, kind) {
+    const operator = Reflect.get(value, 'operator');
+    if (kind === 'present') {
+        return operator === 'isNull' || operator === 'isNotNull';
+    }
+    if (kind === 'oneOf') {
+        const values = Reflect.get(value, 'values');
+        if (operator !== 'in' && operator !== 'notIn')
+            return false;
+        return (Array.isArray(values) &&
+            values.length > 0 &&
+            values.length <= exports.WORKFLOW_FILTER_MAX_VALUES &&
+            values.every((entry) => isWorkflowFilterValue(entry)));
+    }
+    if (kind === 'compare') {
+        return isWorkflowFilterOperator(operator) && isWorkflowFilterValue(Reflect.get(value, 'value'));
+    }
+    return isWorkflowFilterPredicateKindUnhandled(kind);
+}
+/** The narrowing counterpart of {@link unreachableFilterPredicateKind}. */
+function isWorkflowFilterPredicateKindUnhandled(kind) {
+    void kind;
+    return false;
+}
+/**
+ * Whether one row passes a predicate.
+ *
+ * Pure, allocation-free on the common path, and in core rather than in the
+ * runner so that the console can describe — and one day preview — exactly what
+ * the load will do, from the same function that does it. It is called once per
+ * row, so everything about it is arranged to be cheap: no closures built per
+ * row, no array built per row, and `note` is optional so a caller that does not
+ * want the diagnostics pays nothing for them.
+ *
+ * ## Null is unknown, and unknown does not pass
+ *
+ * A column that is `null`, `undefined`, or simply absent from the row fails
+ * **every** `compare` and **every** `oneOf`, *including the negative forms*.
+ * `status notEquals "CLOSED"` does not pass a row with no status.
+ *
+ * That is SQL's three-valued logic rather than JavaScript's, and it is chosen
+ * deliberately over the more intuitive JS answer for one reason: this predicate
+ * is meant to become a `WHERE`, and the day it does, the database will answer
+ * this way. A filter that kept those rows in memory and dropped them once pushed
+ * down would be a performance change that quietly altered what a type contains —
+ * which is the one thing a pushdown must never be able to do. {@link
+ * WorkflowFilterPresence} is how absence is tested on purpose.
+ *
+ * ## A value it cannot compare fails both a test and its inverse
+ *
+ * `qty greaterThan 10` against a `qty` holding `"n/a"` is not false because the
+ * string is small; there is no ordering between a string and a number that any
+ * two systems would agree on. Rather than invent one, the leaf answers false and
+ * calls `note` with the column, and the runner turns those counts into a line on
+ * the run: *"12,431 rows held a value in `qty` the test could not compare."*
+ *
+ * A row nothing can judge is therefore dropped rather than kept. That is the
+ * direction with a backstop — the sink's row-count bound sees the shrink, and a
+ * full sink refuses to commit nothing at all — whereas keeping unjudged rows
+ * would publish them into the type with nothing anywhere to notice.
+ */
+function workflowFilterMatches(predicate, row, note) {
+    if (predicate.kind === 'all' || predicate.kind === 'any') {
+        // One loop for both, because they differ only in which answer is decisive:
+        // an `all` stops at the first false and an `any` stops at the first true.
+        //
+        // **Short-circuiting is why `note` may under-count**, and that is the right
+        // trade rather than an accident: an `any` that matched on its first child
+        // never looks at the second, so a value it could not have compared there is
+        // not reported. Evaluating every child to make the diagnostics complete
+        // would run every comparison against every row for a count nobody acts on
+        // per row — and this function is called seven million times.
+        const decisive = predicate.kind === 'any';
+        for (const child of predicate.children) {
+            if (workflowFilterMatches(child, row, note) === decisive)
+                return decisive;
+        }
+        return !decisive;
+    }
+    return matchFilterLeaf(predicate, row, note);
+}
+/** One condition against one row. Split from the recursion above, which is all it is. */
+function matchFilterLeaf(predicate, row, note) {
+    // `Object.hasOwn` rather than a bare index, because `row` is somebody else's
+    // record and a column named `constructor` would otherwise reach up the
+    // prototype chain and compare against a function.
+    const held = Object.hasOwn(row, predicate.column)
+        ? Reflect.get(row, predicate.column)
+        : undefined;
+    if (predicate.kind === 'present') {
+        const missing = held === null || held === undefined;
+        return predicate.operator === 'isNull' ? missing : !missing;
+    }
+    // Three-valued logic — see the docblock above. Not noted, because an absent
+    // value is an ordinary fact about data rather than a predicate that does not
+    // fit it.
+    if (held === null || held === undefined)
+        return false;
+    if (predicate.kind === 'oneOf')
+        return matchFilterList(predicate, held, note);
+    if (predicate.kind === 'compare')
+        return compareFilterValue(predicate, held, note);
+    return unreachableFilterPredicateKind(predicate, 'workflowFilterMatches');
+}
+/** One `IN`/`NOT IN`, over a value already known to be present. */
+function matchFilterList(predicate, held, note) {
+    if (!isWorkflowFilterValue(held)) {
+        note?.(predicate.column);
+        return false;
+    }
+    const found = predicate.values.includes(held);
+    return predicate.operator === 'in' ? found : !found;
+}
+/**
+ * One leaf comparison, with the type rules written out once.
+ *
+ * Split from {@link workflowFilterMatches} so the recursion above stays readable
+ * and so the ten operators are answered in one place that ends in
+ * {@link unreachableFilterOperator}.
+ */
+function compareFilterValue(predicate, held, note) {
+    const operator = predicate.operator;
+    const wanted = predicate.value;
+    if (operator === 'equals' || operator === 'notEquals') {
+        // Same type or nothing. `"5" === 5` is false in JavaScript and `'5' = 5` is
+        // *true* in MySQL, so a cross-type equality is precisely a comparison whose
+        // answer would change under pushdown — reported rather than picked.
+        if (typeof held !== typeof wanted) {
+            note?.(predicate.column);
+            return false;
+        }
+        return operator === 'equals' ? held === wanted : held !== wanted;
+    }
+    if (operator === 'greaterThan' ||
+        operator === 'greaterThanOrEqual' ||
+        operator === 'lessThan' ||
+        operator === 'lessThanOrEqual') {
+        // Ordered types only, and both sides the same one. Booleans are excluded on
+        // purpose: `true > false` is an answer JavaScript will give and no reader of
+        // a filter ever meant to ask for.
+        const ordered = (typeof held === 'number' && typeof wanted === 'number') ||
+            (typeof held === 'string' && typeof wanted === 'string');
+        if (!ordered) {
+            note?.(predicate.column);
+            return false;
+        }
+        return orderedHolds(operator, held, wanted);
+    }
+    // The four string tests. A non-string on either side is not coerced: coercing
+    // would make `contains` match the digits of a number, which is a full scan
+    // producing rows nobody asked for rather than a comparison.
+    if (typeof held !== 'string' || typeof wanted !== 'string') {
+        note?.(predicate.column);
+        return false;
+    }
+    return textHolds(operator, held, wanted);
+}
+/**
+ * The four string tests, over two values already known to be strings.
+ *
+ * Split out for the same reason {@link orderedHolds} is: the type rule and the
+ * comparison are separate concerns, and keeping them in one function put a
+ * chain of ten operators and three type rules into one place the linter would
+ * not hold in one head — which is a fair description of how a comparison ends up
+ * silently answering the wrong way.
+ */
+function textHolds(operator, held, wanted) {
+    if (operator === 'contains')
+        return held.includes(wanted);
+    if (operator === 'notContains')
+        return !held.includes(wanted);
+    if (operator === 'startsWith')
+        return held.startsWith(wanted);
+    if (operator === 'notStartsWith')
+        return !held.startsWith(wanted);
+    return unreachableFilterOperator(operator, 'workflowFilterMatches');
+}
+/**
+ * The four orderings, over two values already known to be the same ordered type.
+ *
+ * Its own function so the type check above and the comparison here are separate
+ * concerns rather than one branch doing both. Generic over the pair so that
+ * `held` and `wanted` are compared as the *same* type — the signature is what
+ * stops a future edit passing a string and a number to `>`, which is the exact
+ * silent coercion the caller went to trouble to rule out.
+ */
+function orderedHolds(operator, held, wanted) {
+    if (operator === 'greaterThan')
+        return held > wanted;
+    if (operator === 'greaterThanOrEqual')
+        return held >= wanted;
+    if (operator === 'lessThan')
+        return held < wanted;
+    return held <= wanted;
+}
 /**
  * Which side of an {@link WorkflowIfNode} a wire leaves by.
  *
@@ -566,6 +977,9 @@ exports.WORKFLOW_ISSUE_CODES = [
     'if-needs-one-input',
     'branch-not-labelled',
     'branch-on-plain-edge',
+    'filter-predicate-invalid',
+    'filter-narrows-unacknowledged',
+    'filter-narrows-nothing',
 ];
 /**
  * Everything that makes a graph unrunnable, in one pure function.
@@ -609,6 +1023,7 @@ function validateWorkflow(graph) {
     checkNodeWiring(nodes, incoming, outgoing, issues);
     checkEndpoints(originators, sinks, issues);
     checkBranches(edges, byId, issues);
+    checkFilterNarrowing({ nodes, edges }, originators, outgoing, issues);
     const looped = findCycle(nodes, incoming, outgoing);
     if (looped) {
         issues.push({
@@ -808,8 +1223,156 @@ function nodeIsUnconfigured(node) {
         return callIsUnnamed(node);
     if (node.kind === 'if')
         return ifIsUnconfigured(node);
+    if (node.kind === 'filter')
+        return filterIsUnconfigured(node);
     return undefined;
 }
+/**
+ * A filter whose test cannot decide anything.
+ *
+ * The whole predicate, checked by the same guard that reads one back out of a
+ * database, rather than a field-by-field re-implementation here. That is not
+ * only tidiness: the failures it catches are all *silent* ones and they point in
+ * opposite directions — an empty `all` keeps every row so the filter does
+ * nothing, an empty `any` drops every row so the load comes out empty, and a
+ * predicate whose operator this build does not recognise would do neither
+ * because {@link workflowFilterMatches} throws inside a step. A canvas has to
+ * say so before any of that.
+ */
+function filterIsUnconfigured(node) {
+    if (isWorkflowFilterPredicate(node.predicate))
+        return undefined;
+    return {
+        code: 'filter-predicate-invalid',
+        nodeIds: [node.id],
+        message: `Filter "${node.name}" (${node.id}) has no test this service can run. A filter tests bare column names (letters, digits and underscore, starting with a letter or underscore) against plain values, combined with "all" and "any"; a group has to have at least one condition in it, a list at least one value and no more than ${exports.WORKFLOW_FILTER_MAX_VALUES}, and the whole tree may nest ${exports.WORKFLOW_FILTER_MAX_DEPTH} deep. An empty "all" keeps every row and an empty "any" drops every row, which is why neither is stored.`,
+    };
+}
+/**
+ * That every filter names the published types it narrows, and names no others.
+ *
+ * See {@link WorkflowFilterNode.narrows} for the argument. This is the rule
+ * that turns dragging a filter onto a working `source → sink` wire into a graph
+ * that refuses to save until somebody writes down the name of the type they are
+ * about to shrink.
+ *
+ * Run after the structural checks and after the cycle check would have returned,
+ * so the reachability walks below are over a graph that has both ends and no
+ * loop.
+ */
+function checkFilterNarrowing(graph, originators, outgoing, issues) {
+    const rootIds = originators.map((one) => one.id);
+    for (const node of graph.nodes) {
+        if (node.kind !== 'filter')
+            continue;
+        const required = workflowNarrowedTypes(graph, node.id, {
+            originators: rootIds,
+            outgoing,
+        }).sort();
+        const declared = [...new Set(node.narrows ?? [])].sort();
+        const missing = required.filter((type) => !declared.includes(type));
+        if (missing.length > 0)
+            issues.push(filterNarrowsUnacknowledged(node, missing));
+        const spurious = declared.filter((type) => !required.includes(type));
+        if (spurious.length > 0)
+            issues.push(filterNarrowsNothing(node, spurious));
+    }
+}
+/** The refusal that stops a filter quietly shrinking a type somebody else reads. */
+function filterNarrowsUnacknowledged(node, missing) {
+    const one = missing.length === 1;
+    return {
+        code: 'filter-narrows-unacknowledged',
+        nodeIds: [node.id],
+        message: `Filter "${node.name}" (${node.id}) is the only thing feeding the sink that commits ${listTypes(missing)}, and that sink replaces the whole snapshot. So whatever this filter drops disappears from ${one ? 'that type' : 'those types'} the moment this graph runs — and the run reports success, because from its point of view nothing went wrong. If that is what you mean, acknowledge it on the node by naming ${one ? 'the type' : 'the types'}. If you meant to build something new out of a subset, point the sink at a different object type; if you meant to add rows rather than replace them, set the sink to incremental.`,
+    };
+}
+/** The opposite refusal: an acknowledgement the graph no longer backs up. */
+function filterNarrowsNothing(node, spurious) {
+    const one = spurious.length === 1;
+    return {
+        code: 'filter-narrows-nothing',
+        nodeIds: [node.id],
+        message: `Filter "${node.name}" (${node.id}) says it narrows ${listTypes(spurious)}, and it does not: nothing it drops is missing from ${one ? 'that snapshot' : 'those snapshots'}, either because rows also reach the sink by another path or because the sink merges rather than replaces. An acknowledgement that nothing reads is worse than none, because the canvas draws it and the next reader believes it.`,
+    };
+}
+/** `"A"`, `"A" and "B"`, `"A", "B" and "C"` — for a message, not for a machine. */
+function listTypes(types) {
+    const quoted = types.map((type) => `"${type}"`);
+    if (quoted.length <= 1)
+        return quoted.join('');
+    return `${quoted.slice(0, -1).join(', ')} and ${quoted[quoted.length - 1]}`;
+}
+/**
+ * The object types whose whole published snapshot a node stands in front of.
+ *
+ * A sink is in this list when it commits in `full` mode — replacing what is
+ * served rather than merging into it — **and** removing the named node would
+ * make it unreachable from everything that originates rows. That second half is
+ * the load-bearing one: a filter on one of two paths into a sink narrows
+ * nothing, because the other path still delivers, and a rule that ignored it
+ * would demand an acknowledgement for a graph where nothing is lost.
+ *
+ * Removal-reachability rather than a dominator algorithm, deliberately. The
+ * graphs here are a screenful of boxes, this runs once per filter node, and the
+ * cheaper version would be a second, subtler implementation of "does this node
+ * decide whether that one runs" living next to `checkReachability` — which is
+ * exactly the kind of duplication that eventually disagrees with the walk the
+ * rest of this file does.
+ *
+ * Exported because the console needs the same answer to offer the right
+ * acknowledgements, and a canvas that computed its own would offer a set the
+ * server then refuses.
+ *
+ * `precomputed` exists only so the validator, which has already built the
+ * adjacency it needs, does not build it twice per filter node. Callers outside
+ * this file pass a graph and nothing else.
+ */
+function workflowNarrowedTypes(graph, nodeId, precomputed) {
+    const nodes = graph.nodes ?? [];
+    const outgoing = precomputed?.outgoing ?? buildAdjacency(nodes, graph.edges ?? []).outgoing;
+    const originators = precomputed?.originators ?? nodes.filter((node) => originatesRows(node)).map((node) => node.id);
+    // Everything still reachable once this node is taken out. A source that *is*
+    // the node cannot originate anything, which falls out of the filter below
+    // rather than needing its own case.
+    const roots = originators.filter((id) => id !== nodeId);
+    const reachableWithout = walk(roots, stripNode(outgoing, nodeId));
+    const types = [];
+    for (const node of nodes) {
+        if (!narrowedByRemoval(node, reachableWithout))
+            continue;
+        const type = node.targetType.trim();
+        if (type.length > 0 && !types.includes(type))
+            types.push(type);
+    }
+    return types;
+}
+/**
+ * Whether this node is a full-mode sink that the removed node was the only way
+ * to reach.
+ *
+ * A sink with no explicit mode is a **full** sink — the same default `runSink`
+ * applies, read the same way here, because a graph that validated under one
+ * meaning of the absent field and ran under the other is precisely the failure
+ * this whole check exists to prevent.
+ */
+function narrowedByRemoval(node, reachableWithout) {
+    if (node.kind !== 'sink')
+        return false;
+    if ((node.mode ?? 'full') === 'incremental')
+        return false;
+    return !reachableWithout.has(node.id);
+}
+/** The same adjacency with one node's outgoing edges cut, leaving the original alone. */
+function stripNode(outgoing, nodeId) {
+    const without = new Map();
+    for (const [from, targets] of outgoing) {
+        if (from === nodeId)
+            continue;
+        without.set(from, targets.filter((to) => to !== nodeId));
+    }
+    return without;
+}
 /**
  * A gate whose test cannot decide anything.
  *
@@ -1200,6 +1763,20 @@ function canonicalNode(node) {
     if (node.kind === 'if') {
         return JSON.stringify([node.id, node.kind, ...canonicalPredicate(node.predicate)]);
     }
+    if (node.kind === 'filter') {
+        // `narrows` is in here as well as the predicate, and that is a decision
+        // rather than completeness. It changes nothing about what the node computes
+        // — but it is the acknowledgement that a published type is about to become a
+        // subset, and a run that happened before anybody acknowledged that must stay
+        // distinguishable from one that happened after. Sorted, so ticking the same
+        // two boxes in the other order is not an edit.
+        return JSON.stringify([
+            node.id,
+            node.kind,
+            canonicalFilterPredicate(node.predicate),
+            [...(node.narrows ?? [])].sort(),
+        ]);
+    }
     if (node.kind === 'sink') {
         return JSON.stringify([node.id, node.kind, node.targetType, node.mode ?? 'full']);
     }
@@ -1226,6 +1803,46 @@ function canonicalPredicate(predicate) {
     }
     return unreachablePredicateKind(predicate, 'workflowGraphHash');
 }
+/**
+ * The parts of a filter predicate that decide which rows survive.
+ *
+ * Which is all of them, so this is a faithful canonicalisation rather than a
+ * selection — every field of every kind changes what a load publishes. What it
+ * adds over `JSON.stringify` of the predicate is order-independence where order
+ * is meaningless and order-*dependence* where it is not: the children of an
+ * `all` are sorted, because `A and B` and `B and A` are the same filter and a
+ * canvas that rewrites the array must not look like an edit; the `values` of a
+ * `oneOf` are sorted for the same reason. The kind and the operator lead, so no
+ * two shapes can canonicalise to the same string.
+ *
+ * `values` is deliberately *not* deduplicated. A duplicate changes nothing about
+ * the result, but removing one here would make the hash disagree with what is
+ * stored, and the fingerprint is meant to answer "is this the same graph" rather
+ * than "is this an equivalent graph".
+ */
+function canonicalFilterPredicate(predicate) {
+    if (predicate.kind === 'all' || predicate.kind === 'any') {
+        return JSON.stringify([
+            predicate.kind,
+            predicate.children.map((child) => canonicalFilterPredicate(child)).sort(),
+        ]);
+    }
+    if (predicate.kind === 'oneOf') {
+        return JSON.stringify([
+            predicate.kind,
+            predicate.column,
+            predicate.operator,
+            [...predicate.values].map((value) => JSON.stringify(value)).sort(),
+        ]);
+    }
+    if (predicate.kind === 'present') {
+        return JSON.stringify([predicate.kind, predicate.column, predicate.operator]);
+    }
+    if (predicate.kind === 'compare') {
+        return JSON.stringify([predicate.kind, predicate.column, predicate.operator, predicate.value]);
+    }
+    return unreachableFilterPredicateKind(predicate, 'workflowGraphHash');
+}
 function sortedEntries(config) {
     return Object.keys(config)
         .sort()
@@ -1286,6 +1903,11 @@ function isWorkflowNode(value) {
         // means half the graph runs on a decision nobody made.
         return isWorkflowIfPredicate(Reflect.get(value, 'predicate'));
     }
+    if (kind === 'filter') {
+        return isNarrowsList(Reflect.get(value, 'narrows'))
+            ? isWorkflowFilterPredicate(Reflect.get(value, 'predicate'))
+            : false;
+    }
     if (kind === 'source') {
         const sourceKind = Reflect.get(value, 'sourceKind');
         const config = Reflect.get(value, 'config');
@@ -1293,6 +1915,25 @@ function isWorkflowNode(value) {
     }
     return isWorkflowNodeKindUnhandled(kind);
 }
+/**
+ * Whether a stored `narrows` is one this build can read.
+ *
+ * Checked as strictly as the predicate beside it, and it has to be:
+ * {@link WorkflowFilterNode.narrows} is what stands between "filter into the
+ * type that already exists" and a published snapshot quietly becoming a subset.
+ * A value that is not a list of strings is refused rather than dropped, because
+ * dropping it turns a graph somebody acknowledged into one that never was — and
+ * `validateWorkflow` would then refuse it with a message about a field they did
+ * fill in.
+ *
+ * Absent is accepted, because that is what every filter narrowing nothing looks
+ * like and what every node stored before this field existed is.
+ */
+function isNarrowsList(value) {
+    if (value === undefined)
+        return true;
+    return Array.isArray(value) && value.every((type) => typeof type === 'string');
+}
 /**
  * The narrowing counterpart of {@link unreachableNodeKind}.
  *