@dudousxd/nestjs-catalog 0.16.0-preview.0 → 0.17.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/catalog.pipeline.d.ts

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