@dudousxd/nestjs-catalog 0.22.0 → 0.23.0

package/dist/catalog.pipeline.js

@@ -9,7 +9,7 @@
  * systems each believing they decide when a load runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REDACTED_SECRET = exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_CALL_CONTRACT = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_BRANCH_LABELS = exports.NODE_KIND_IS_REUSABLE = exports.REUSABLE_NODE_KINDS = exports.WORKFLOW_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_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_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_LANGUAGES = exports.SOURCE_FORMATS = exports.CONNECTOR_KINDS = void 0;
 exports.isConnectorKind = isConnectorKind;
 exports.isSourceFormat = isSourceFormat;
 exports.unreachableSourceFormat = unreachableSourceFormat;
@@ -32,6 +32,11 @@ exports.unreachableFilterOperator = unreachableFilterOperator;
 exports.isWorkflowFilterValue = isWorkflowFilterValue;
 exports.isWorkflowFilterPredicate = isWorkflowFilterPredicate;
 exports.workflowFilterMatches = workflowFilterMatches;
+exports.isWorkflowRenameUnnamed = isWorkflowRenameUnnamed;
+exports.unreachableRenameUnnamed = unreachableRenameUnnamed;
+exports.workflowRenameUnnamed = workflowRenameUnnamed;
+exports.renameColumnRefusals = renameColumnRefusals;
+exports.isWorkflowRenameColumns = isWorkflowRenameColumns;
 exports.isReusableNodeKind = isReusableNodeKind;
 exports.nodeKindIsReusable = nodeKindIsReusable;
 exports.unreachableReusableNodeKind = unreachableReusableNodeKind;
@@ -50,6 +55,8 @@ exports.workflowNarrowedTypes = workflowNarrowedTypes;
 exports.workflowRunOrder = workflowRunOrder;
 exports.workflowNodeRuns = workflowNodeRuns;
 exports.workflowGraphHash = workflowGraphHash;
+exports.workflowFilterColumns = workflowFilterColumns;
+exports.workflowKnownColumns = workflowKnownColumns;
 exports.isWorkflowNode = isWorkflowNode;
 exports.isWorkflowEdge = isWorkflowEdge;
 exports.supportsWorkflows = supportsWorkflows;
@@ -59,6 +66,7 @@ exports.supportsTransformRevisions = supportsTransformRevisions;
 exports.supportsTransformPins = supportsTransformPins;
 exports.supportsReusableNodes = supportsReusableNodes;
 exports.supportsWorkflowStages = supportsWorkflowStages;
+exports.supportsStagePayloads = supportsStagePayloads;
 exports.supportsLoadExpectations = supportsLoadExpectations;
 exports.isPipelineStore = isPipelineStore;
 // The revision shape is declared beside the audit trail rather than here,
@@ -296,6 +304,8 @@ exports.WORKFLOW_NODE_KINDS = [
     'if',
     /** Drops the rows that fail a declarative test. See {@link WorkflowFilterNode}. */
     'filter',
+    /** Renames columns, declaratively. See {@link WorkflowRenameNode}. */
+    'rename',
 ];
 /** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
 function isWorkflowNodeKind(value) {
@@ -960,6 +970,116 @@ function orderedHolds(operator, held, wanted) {
         return held < wanted;
     return held <= wanted;
 }
+/* --- rename -------------------------------------------------------------- */
+/**
+ * What happens to a column the rename does not name.
+ *
+ * Two words rather than a boolean, because the two are genuinely different
+ * nodes and a boolean called `drop` would read as a modifier on one node. See
+ * {@link WorkflowRenameNode.unnamed} for what each costs.
+ */
+exports.WORKFLOW_RENAME_UNNAMED = [
+    /** Passed through untouched. The default, and the metadata-only case. */
+    'keep',
+    /** Removed. The output columns are exactly the map's targets. */
+    'drop',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowRenameUnnamed(value) {
+    return exports.WORKFLOW_RENAME_UNNAMED.some((each) => each === value);
+}
+/**
+ * The exhaustiveness guard for {@link WORKFLOW_RENAME_UNNAMED}.
+ *
+ * {@link unreachableNodeKind}, one level down, and for the identical reason: the
+ * two words decide whether a batch is rewritten or only re-labelled, and a third
+ * one added without a branch would silently pick whichever the last `if` was.
+ */
+function unreachableRenameUnnamed(value, where) {
+    throw new Error(`${where} does not handle the rename disposition ${JSON.stringify(value)}. The list and every decision made per entry are meant to move together.`);
+}
+/**
+ * How many columns one rename may name.
+ *
+ * The same argument {@link WORKFLOW_FILTER_MAX_VALUES} makes: the map travels in
+ * the graph and into the graph fingerprint, and past a few hundred entries the
+ * thing being expressed is a schema mapping that belongs in a stored object
+ * rather than in a node. It is also the bound that keeps
+ * {@link isWorkflowRenameColumns} — which is run on JSON out of a column — from
+ * being a place to hand a service a million-key object.
+ */
+exports.WORKFLOW_RENAME_MAX_COLUMNS = 500;
+/** {@link WorkflowRenameNode.unnamed}, resolved. One reader of the default. */
+function workflowRenameUnnamed(node) {
+    return node.unnamed ?? 'keep';
+}
+/**
+ * Every reason a rename map cannot be stored, as sentences, or empty.
+ *
+ * One function, called by {@link validateWorkflow}, by the HTTP boundary and by
+ * the canvas, for the reason `validateWorkflow` itself is shared: a screen that
+ * checked a target name against its own copy of the pattern is a screen that
+ * eventually accepts something the server refuses, halfway through a save.
+ *
+ * All of them rather than the first, exactly as
+ * {@link refuseUnpublishablePropertyNames} argues: a map of forty columns typed
+ * in one sitting is usually wrong about several in the same way.
+ */
+function renameColumnRefusals(columns) {
+    const refusals = [];
+    const entries = Object.entries(columns);
+    if (entries.length === 0) {
+        refusals.push('It renames nothing. An empty map is refused rather than stored: with unnamed columns kept it is a node that draws as configured and does nothing, and with them dropped it deletes every column of every row.');
+        return refusals;
+    }
+    if (entries.length > exports.WORKFLOW_RENAME_MAX_COLUMNS) {
+        refusals.push(`It names ${entries.length} columns, and at most ${exports.WORKFLOW_RENAME_MAX_COLUMNS} may be renamed in one node. Past that the thing being expressed is a schema mapping rather than a rename.`);
+    }
+    const targets = new Map();
+    for (const [from, to] of entries) {
+        if (from.length === 0) {
+            refusals.push('One entry renames a column with no name, so there is nothing for it to find.');
+            continue;
+        }
+        if (typeof to !== 'string' || !exports.WORKFLOW_FILTER_COLUMN_PATTERN.test(to)) {
+            refusals.push(`${JSON.stringify(from)} is renamed to ${JSON.stringify(to)}, which is not a name a column can have: letters, digits and underscore, starting with a letter or an underscore. A load looks every field up as \`row[name]\`, so a column this service cannot name downstream is one that loads NULL into every row and reports success.`);
+            continue;
+        }
+        targets.set(to, [...(targets.get(to) ?? []), from]);
+    }
+    for (const [to, sources] of targets) {
+        if (sources.length < 2)
+            continue;
+        refusals.push(`${sources.map((from) => JSON.stringify(from)).join(' and ')} are both renamed to ${JSON.stringify(to)}. Two columns cannot share one name, and picking a winner would be a rule about which of somebody's data survives.`);
+    }
+    return refusals;
+}
+/**
+ * Whether a stored rename map is one this build can run.
+ *
+ * Refused rather than repaired, the stance {@link isWorkflowFilterPredicate}
+ * takes about a predicate and for the same reason one step further along: a
+ * rename read back with one entry silently dropped is a graph that commits a
+ * column of NULLs under a name nobody can now explain.
+ *
+ * `Object.entries` rather than a `for…in`, so an inherited key cannot enter the
+ * map, and the values are checked one by one rather than trusted from the type.
+ */
+function isWorkflowRenameColumns(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    if (entries.every(([, to]) => typeof to === 'string')) {
+        const columns = {};
+        for (const [from, to] of entries) {
+            if (typeof to !== 'string')
+                return false;
+            columns[from] = to;
+        }
+        return renameColumnRefusals(columns).length === 0;
+    }
+    return false;
+}
 /* --- reusable nodes ------------------------------------------------------ */
 /**
  * The node kinds that can be saved once and used in several graphs.
@@ -1013,6 +1133,11 @@ function isReusableNodeKind(value) {
  *   may not have, and a filter is worse: {@link WorkflowFilterNode.narrows} is
  *   an acknowledgement about *this* graph's sinks, so a shared one would carry
  *   somebody else's acknowledgement into a graph they never saw.
+ * - `rename` — the same argument as `if` and `filter`, and the sharpest version
+ *   of it: a rename map names the source's own spelling of its columns, so it is
+ *   *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.
  */
 exports.NODE_KIND_IS_REUSABLE = {
     source: true,
@@ -1021,6 +1146,7 @@ exports.NODE_KIND_IS_REUSABLE = {
     call: false,
     if: false,
     filter: false,
+    rename: false,
 };
 /** Whether this kind can be saved as a reusable node. Reads {@link NODE_KIND_IS_REUSABLE}. */
 function nodeKindIsReusable(kind) {
@@ -1425,6 +1551,29 @@ exports.WORKFLOW_ISSUE_CODES = [
     'filter-predicate-invalid',
     'filter-narrows-unacknowledged',
     'filter-narrows-nothing',
+    /**
+     * A rename whose map cannot be stored: empty, too big, or naming a target that
+     * is not a column name or that two source columns share. Every one of those is
+     * detectable from the node alone, which is the point of the node — see
+     * {@link renameColumnRefusals} for the sentences.
+     */
+    'rename-invalid',
+    /**
+     * A node naming a column that nothing upstream can produce.
+     *
+     * The one thing a declarative rename buys the *validator*, and it is the whole
+     * reason the node is data rather than code. A rename with
+     * `unnamed: 'drop'` has an output column set that is known exactly from its
+     * config — its targets, and nothing else, whatever it was handed. So a filter
+     * or a second rename downstream of one, naming a column outside that set, is
+     * provably wrong at the moment the graph is saved instead of at the moment the
+     * load comes out empty.
+     *
+     * Reported only where the set is *closed*. See {@link workflowKnownColumns}
+     * for exactly how far that reaches and for what it deliberately does not
+     * claim.
+     */
+    'column-not-produced',
     /**
      * A version pin that is not a version — `0`, `2.5`, `"3"`, `-1`.
      *
@@ -1496,6 +1645,9 @@ function validateWorkflow(graph) {
         return issues;
     }
     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);
     return issues;
 }
 /**
@@ -1851,8 +2003,31 @@ function nodeIsUnconfigured(node) {
         return ifIsUnconfigured(node);
     if (node.kind === 'filter')
         return filterIsUnconfigured(node);
+    if (node.kind === 'rename')
+        return renameIsUnconfigured(node);
     return undefined;
 }
+/**
+ * A rename whose map this service will not store.
+ *
+ * The refusals come from {@link renameColumnRefusals} rather than being restated
+ * here, so the canvas, the HTTP boundary and this validator say the same
+ * sentence about the same map. Every one of them is a *silent* failure if it
+ * were let through: an empty map is a node that does nothing or a node that
+ * deletes every column, a target that is not a column name loads NULL into every
+ * row and reports success, and two columns renamed onto one name means one of
+ * them is gone and nothing says which.
+ */
+function renameIsUnconfigured(node) {
+    const refusals = renameColumnRefusals(node.columns ?? {});
+    if (refusals.length === 0)
+        return undefined;
+    return {
+        code: 'rename-invalid',
+        nodeIds: [node.id],
+        message: `Rename "${node.name}" (${node.id}) cannot be stored as it is. ${refusals.join(' ')}`,
+    };
+}
 /**
  * A filter whose test cannot decide anything.
  *
@@ -2440,6 +2615,8 @@ function canonicalNode(node) {
             [...(node.narrows ?? [])].sort(),
         ]);
     }
+    if (node.kind === 'rename')
+        return canonicalRename(node);
     if (node.kind === 'sink') {
         return JSON.stringify([
             node.id,
@@ -2451,6 +2628,28 @@ function canonicalNode(node) {
     }
     return unreachableNodeKind(node, 'workflowGraphHash');
 }
+/**
+ * A rename, canonicalised.
+ *
+ * Sorted by source column, so a canvas that rewrites the object in a different
+ * order is not an edit — the rule `sortedEntries` applies to a source's config,
+ * and it is safe here for a reason specific to this node: the map is applied
+ * *simultaneously*, so its order changes nothing about the result.
+ *
+ * `unnamed` is appended only when it is `drop`, exactly as `edge.branch` is
+ * appended only when there is a label. Every rename that keeps its unnamed
+ * columns — whether it says so or says nothing — hashes to one string, so
+ * normalising the field on a canvas cannot renumber a graph. It is in there at
+ * all because it decides which columns reach the sink.
+ */
+function canonicalRename(node) {
+    return JSON.stringify([
+        node.id,
+        node.kind,
+        sortedEntries(node.columns),
+        ...(workflowRenameUnnamed(node) === 'drop' ? ['drop'] : []),
+    ]);
+}
 /**
  * The reusable reference, as zero, one or two trailing hash components.
  *
@@ -2552,6 +2751,207 @@ function canonicalFilterPredicate(predicate) {
     }
     return unreachableFilterPredicateKind(predicate, 'workflowGraphHash');
 }
+/* --- what the graph knows about columns ---------------------------------- */
+/**
+ * Every column a filter predicate names, once each, in the order they appear.
+ *
+ * Its own function rather than a walk inlined into the validator, because two
+ * things want it — the refusal below and anything on a screen that wants to say
+ * which columns a node depends on — and a second copy of a tree walk is a second
+ * copy that forgets the `oneOf` branch.
+ */
+function workflowFilterColumns(predicate) {
+    const found = [];
+    const visit = (each) => {
+        if (each.kind === 'all' || each.kind === 'any') {
+            for (const child of each.children)
+                visit(child);
+            return;
+        }
+        if (!found.includes(each.column))
+            found.push(each.column);
+    };
+    visit(predicate);
+    return found;
+}
+/**
+ * The columns that can reach this node, when the graph knows — and `undefined`
+ * when it does not.
+ *
+ * ## What this is for
+ *
+ * It is the one thing a declarative rename buys that a transform cannot, and it
+ * is worth being precise about how far it reaches rather than overselling it.
+ *
+ * With a JS transform, the catalog cannot know what columns come out — the
+ * answer is inside a function body — which is why the property-name rule in
+ * `property-names.ts` fires at publish time and why a mismatch between a
+ * property and a record key is discovered as a column of NULLs. A rename is
+ * **data**, so for one arrangement the answer is exact:
+ *
+ * > A rename with `unnamed: 'drop'` produces its targets and **nothing else**,
+ * > whatever it was handed.
+ *
+ * That set is *closed* — an upper bound that holds regardless of what is
+ * upstream — and it survives every node that does not touch columns. So a filter
+ * or a second rename downstream of one can be told, at authoring time, that it
+ * names a column which cannot be there.
+ *
+ * ## What it deliberately does not claim
+ *
+ * - **It is an upper bound, not the output.** A target only appears in a row
+ *   whose input actually held the source column. So a column *inside* the set
+ *   may still be absent, and nothing here says otherwise.
+ * - **A `keep` rename tells you nothing on its own.** Its output is its input
+ *   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.
+ * - **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
+ *   `targetType` and nothing else, so the property list would have to be
+ *   threaded into a validator that is pure and dependency-free on purpose. What
+ *   is built instead is the run log, which prints the columns a rename produced.
+ *
+ * Cycles answer `undefined` rather than looping. `validateWorkflow` refuses a
+ * 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) {
+    const nodes = graph.nodes ?? [];
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const { incoming } = buildAdjacency(nodes, graph.edges ?? []);
+    const answered = new Map();
+    const open = new Set();
+    const outOf = (id) => {
+        if (answered.has(id))
+            return answered.get(id);
+        // A loop. Answered as unknown and remembered, so the walk terminates and so
+        // that a second question about the same node does not re-enter it.
+        if (open.has(id))
+            return undefined;
+        const node = byId.get(id);
+        if (!node)
+            return undefined;
+        open.add(id);
+        const produced = producedColumns(node, () => intoNode(id));
+        open.delete(id);
+        answered.set(id, produced);
+        return produced;
+    };
+    const intoNode = (id) => {
+        const feeds = incoming.get(id) ?? [];
+        if (feeds.length === 0)
+            return undefined;
+        const union = new Set();
+        for (const from of feeds) {
+            const upstream = outOf(from);
+            // One unknown input makes the whole position unknown: the rows arrive
+            // concatenated, so a column any one of them carries is a column this node
+            // can see.
+            if (upstream === undefined)
+                return undefined;
+            for (const column of upstream)
+                union.add(column);
+        }
+        return union;
+    };
+    return intoNode(nodeId);
+}
+/**
+ * What one node passes on, given what reaches it.
+ *
+ * The upstream set is a thunk rather than a value because the one case that
+ * makes this function worth having does not need it: a rename that drops its
+ * unnamed columns answers from its own config, so the walk stops there rather
+ * than climbing to a source it would learn nothing from.
+ *
+ * Ends in {@link unreachableNodeKind}, so a node kind added without an answer
+ * 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) {
+    if (node.kind === 'rename') {
+        if (workflowRenameUnnamed(node) === 'drop')
+            return new Set(Object.values(node.columns ?? {}));
+        const known = upstream();
+        if (known === undefined)
+            return undefined;
+        const renamed = new Set();
+        for (const column of known)
+            renamed.add(node.columns?.[column] ?? column);
+        return renamed;
+    }
+    // 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') {
+        return undefined;
+    }
+    return unreachableNodeKind(node, '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.
+ *
+ * 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
+ * an absent column is false under the three-valued logic
+ * {@link workflowFilterMatches} implements, *including the inverses* — so the
+ * load comes out empty and every node reports success. A rename of a column that
+ * cannot exist renames nothing, so the target is absent, and a sink writing it
+ * 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) {
+    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')
+            continue;
+        const named = node.kind === 'filter'
+            ? workflowFilterColumns(node.predicate)
+            : Object.keys(node.columns ?? {});
+        if (named.length === 0)
+            continue;
+        const known = workflowKnownColumns(graph, node.id);
+        if (known === undefined)
+            continue;
+        const missing = named.filter((column) => column.length > 0 && !known.has(column));
+        if (missing.length === 0)
+            continue;
+        issues.push({
+            code: 'column-not-produced',
+            nodeIds: [node.id],
+            message: missingColumnMessage(node, missing, known),
+        });
+    }
+}
+/** 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}`;
+}
 function sortedEntries(config) {
     return Object.keys(config)
         .sort()
@@ -2607,6 +3007,8 @@ function isWorkflowNode(value) {
             ? isWorkflowFilterPredicate(Reflect.get(value, 'predicate'))
             : false;
     }
+    if (kind === 'rename')
+        return isRenameNodeShape(value);
     if (kind === 'source') {
         const sourceKind = Reflect.get(value, 'sourceKind');
         const config = Reflect.get(value, 'config');
@@ -2614,6 +3016,22 @@ function isWorkflowNode(value) {
     }
     return isWorkflowNodeKindUnhandled(kind);
 }
+/**
+ * Everything a `rename` node carries.
+ *
+ * `unnamed` absent is accepted and always will be — it is what every rename
+ * written before the field existed carries, and it means `keep`. A value that is
+ * present and unrecognised is refused rather than defaulted, for the reason an
+ * unrecognised `edge.branch` is: reading it back as `keep` would turn a
+ * projection into a pass-through silently, and the sink would commit every
+ * column the author meant to remove.
+ */
+function isRenameNodeShape(value) {
+    const unnamed = Reflect.get(value, 'unnamed');
+    if (unnamed !== undefined && !isWorkflowRenameUnnamed(unnamed))
+        return false;
+    return isWorkflowRenameColumns(Reflect.get(value, 'columns'));
+}
 /**
  * Everything a `call` node carries, checked as strictly as a source's.
  *
@@ -2831,6 +3249,25 @@ function supportsReusableNodes(store) {
 function supportsWorkflowStages(store) {
     return typeof store.writeStage === 'function' && typeof store.readStage === 'function';
 }
+/**
+ * Whether this store will hand a staged batch over without decoding it.
+ *
+ * Both methods, never one: a rename that could read the payload and not write
+ * one back would have to decode its own output to store it, which is the rebuild
+ * the pair exists to avoid. The methods rather than a flag, the same argument
+ * {@link supportsWorkflows} makes.
+ *
+ * A store that answers no is not broken and nothing degrades except speed — the
+ * rename node falls back to `readStage`/`writeStage` and produces identical
+ * rows. Which path ran is said in the run log, because "this rename was
+ * metadata-only" is a claim, and a claim that could quietly stop being true is
+ * worse than no claim.
+ */
+function supportsStagePayloads(store) {
+    return (supportsWorkflowStages(store) &&
+        typeof store.readStagePayload === 'function' &&
+        typeof store.writeStagePayload === 'function');
+}
 /**
  * Whether an operator can set a load expectation on this deployment at all.
  *

package/dist/catalog.stage-encoding.d.ts

@@ -183,3 +183,75 @@ export declare function classifyStagePayload(stored: unknown): StagePayload;
  * here instead of falling through to a silent `[]`.
  */
 export declare function decodeStageRows(stored: unknown): Array<Record<string, unknown>>;
+/**
+ * A rename, reduced to what the encoding needs to know.
+ *
+ * A `Map` rather than the node's `Record`, because this runs once per shape and
+ * a `Map` lookup is what the loop below wants; and separate from
+ * `WorkflowRenameNode` so this file keeps knowing nothing about graphs.
+ */
+export interface StageRenamePlan {
+    /** Old name → new name, applied simultaneously. */
+    readonly columns: ReadonlyMap<string, string>;
+    /** Whether a column the plan does not name survives. See the node's docblock. */
+    readonly dropUnnamed: boolean;
+}
+/** What {@link renameStagePayload} did, in enough detail for a run to report it. */
+export interface StageRenameResult {
+    /** Ready to store, in the same column the batch came out of. */
+    readonly payload: ColumnarStageBatch;
+    readonly rows: number;
+    /**
+     * Whether **no value moved** — the batch came back columnar and only its
+     * `shapes` were rewritten.
+     *
+     * The claim the rename node is built on, reported rather than assumed: it is
+     * true for a pure rename over a columnar batch and false the moment unnamed
+     * columns are dropped, because dropping one removes a position from every
+     * `values` row. A run that says which one happened is a run whose cost can be
+     * explained afterwards.
+     */
+    readonly metadataOnly: boolean;
+    /** How many entries of `shapes` came out different from what went in. */
+    readonly shapesRewritten: number;
+    /** The plan's source columns that were present in at least one shape. */
+    readonly matched: ReadonlySet<string>;
+}
+/**
+ * Rename the columns of one staged batch.
+ *
+ * ## The metadata-only path, which is the whole point
+ *
+ * A columnar batch names its columns once per distinct key-set, in `shapes`, and
+ * carries the data in `values` as arrays that are *positional* — `values[i][3]`
+ * is whatever `shapes[shapeOf[i]][3]` is called. A positional array does not
+ * care what the key is called. So a pure rename rewrites `shapes` and hands back
+ * the **same `shapeOf` and the same `values` arrays, by reference**: a hundred
+ * thousand rows cost as many string comparisons as there are distinct key-sets,
+ * which for a real load is one or two.
+ *
+ * `dropUnnamed` breaks that and is allowed to. Removing a column removes a
+ * position, so every `values` row has to be rebuilt, and the result says so
+ * through {@link StageRenameResult.metadataOnly} rather than leaving the
+ * difference to be inferred from a stopwatch.
+ *
+ * ## Collisions
+ *
+ * A rename onto a name the shape already holds **throws**, naming both columns.
+ * The alternative is a shape with one name twice, which decodes to whichever
+ * value was written last — one of the author's two columns silently gone, with
+ * a green run. It is detected per shape rather than per row, so it fails on the
+ * first batch rather than at row ninety thousand.
+ *
+ * Under `dropUnnamed` there is nothing to collide with: a column the plan does
+ * not name is not in the output, so it cannot be occupying a name.
+ *
+ * ## A row-oriented batch
+ *
+ * Re-encoded first and then renamed by the one code path above, rather than
+ * given a second implementation that walks objects. Two implementations of "what
+ * does this rename mean" is how the fallback path ends up disagreeing with the
+ * fast one about a collision. The re-encode costs a pass and is reported as
+ * `metadataOnly: false`, which is the truth about the bytes.
+ */
+export declare function renameStagePayload(stored: unknown, plan: StageRenamePlan): StageRenameResult;