@dudousxd/nestjs-catalog 0.16.0 → 0.18.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_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.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_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;
@@ -27,6 +27,13 @@ exports.unreachableFilterOperator = unreachableFilterOperator;
 exports.isWorkflowFilterValue = isWorkflowFilterValue;
 exports.isWorkflowFilterPredicate = isWorkflowFilterPredicate;
 exports.workflowFilterMatches = workflowFilterMatches;
+exports.isReusableNodeKind = isReusableNodeKind;
+exports.nodeKindIsReusable = nodeKindIsReusable;
+exports.unreachableReusableNodeKind = unreachableReusableNodeKind;
+exports.applyReusableNode = applyReusableNode;
+exports.isReusableNodeBody = isReusableNodeBody;
+exports.reusableNodeBodyOf = reusableNodeBodyOf;
+exports.describeVersionPin = describeVersionPin;
 exports.isWorkflowBranchLabel = isWorkflowBranchLabel;
 exports.isWorkflowStatus = isWorkflowStatus;
 exports.isWorkflowExecutionMode = isWorkflowExecutionMode;
@@ -41,9 +48,17 @@ exports.isWorkflowNode = isWorkflowNode;
 exports.isWorkflowEdge = isWorkflowEdge;
 exports.supportsWorkflows = supportsWorkflows;
 exports.supportsTransformRevisions = supportsTransformRevisions;
+exports.supportsTransformPins = supportsTransformPins;
+exports.supportsReusableNodes = supportsReusableNodes;
 exports.supportsWorkflowStages = supportsWorkflowStages;
 exports.supportsLoadExpectations = supportsLoadExpectations;
 exports.isPipelineStore = isPipelineStore;
+// The revision shape is declared beside the audit trail rather than here,
+// because it is one shape over two subjects — a transform's code and a saved
+// query's SQL — and neither of them owns it. This is a type-only import, and the
+// edge only ever points this way: `catalog.workspace.ts` knows nothing about
+// pipelines.
+const catalog_workspace_1 = require("./catalog.workspace");
 /**
  * Where a connector pulls from.
  *
@@ -767,6 +782,201 @@ function orderedHolds(operator, held, wanted) {
         return held < wanted;
     return held <= wanted;
 }
+/* --- reusable nodes ------------------------------------------------------ */
+/**
+ * The node kinds that can be saved once and used in several graphs.
+ *
+ * Source and sink, and the reason is that those two are the only kinds whose
+ * *composition* is worth a name. A connection is already a shared object, and it
+ * answers "which database" — but nobody reaches for "the warehouse" when they
+ * draw a graph, they reach for "the nightly MVR pull from the warehouse", which
+ * is the connection **plus** the query, plus whether it reads everything or only
+ * what changed, plus what the thing is called. That composition had nowhere to
+ * live, so it was retyped per graph and the fourteenth copy was the one with the
+ * typo in the `WHERE` clause.
+ *
+ * A transform is deliberately **not** here, and that is not an omission: a
+ * transform is already a stored object referenced by id
+ * ({@link WorkflowTransformNode.transformId}), so a reusable transform node
+ * would be a second way to say the same thing. What it was missing is a version
+ * pin, which is {@link WorkflowTransformNode.transformVersion}, not this.
+ *
+ * `call`, `if` and `filter` are not here either, and the record below is where
+ * each of them says so — see {@link NODE_KIND_IS_REUSABLE}.
+ */
+exports.REUSABLE_NODE_KINDS = ['source', 'sink'];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isReusableNodeKind(value) {
+    return exports.REUSABLE_NODE_KINDS.some((kind) => kind === value);
+}
+/**
+ * Whether each node kind may be saved as a reusable node.
+ *
+ * A record over every kind rather than a shorter list of the two that can,
+ * because this codebase keeps being bitten by hand-maintained lists going quiet
+ * — most recently the add-node row that shipped the `filter` node with no way to
+ * create it. A kind added to {@link WORKFLOW_NODE_KINDS} without an entry here
+ * is a type error in this file naming the decision it has not made.
+ *
+ * The second `satisfies` is the other half of the same guard, in the other
+ * direction: anything named in {@link REUSABLE_NODE_KINDS} has to be `true`
+ * here, so the list and this table cannot come apart. Adding `'filter'` to that
+ * list without a `ReusableFilterBody` therefore fails to compile twice — once
+ * here, and once at every narrowing over {@link ReusableNodeBody}.
+ *
+ * Why each `false`:
+ *
+ * - `transform` — already a reference to a stored object. See
+ *   {@link REUSABLE_NODE_KINDS}.
+ * - `call` — already a reference to somebody else's registered workflow, pinned
+ *   by name and version. There is nothing left to name.
+ * - `if` and `filter` — a predicate is *about* the rows in front of it. A gate
+ *   saved under a name and dropped into another graph tests a column that graph
+ *   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.
+ */
+exports.NODE_KIND_IS_REUSABLE = {
+    source: true,
+    transform: false,
+    sink: true,
+    call: false,
+    if: false,
+    filter: false,
+};
+/** Whether this kind can be saved as a reusable node. Reads {@link NODE_KIND_IS_REUSABLE}. */
+function nodeKindIsReusable(kind) {
+    return exports.NODE_KIND_IS_REUSABLE[kind];
+}
+/**
+ * {@link unreachableNodeKind}, for reusable bodies, and for the identical
+ * reason: every branch over {@link ReusableNodeBody} ends here, so a body added
+ * to the union without a rule for folding it onto a node is a type error naming
+ * the file rather than a graph that saves and then runs a node nobody
+ * configured. It throws as well, because these arrive as JSON out of a column.
+ */
+function unreachableReusableNodeKind(body, where) {
+    const kind = typeof body === 'string' ? body : Reflect.get(Object(body), 'kind');
+    throw new Error(`${where} does not handle a reusable node body of kind ${JSON.stringify(kind)}. The reusable kinds and every decision made per kind are meant to move together.`);
+}
+/**
+ * Fold a reusable body onto the node that references it.
+ *
+ * The one implementation, called by the store when a graph is saved and by the
+ * runner when one is executed, so the node a canvas draws and the node that runs
+ * cannot describe different reads. Pure, and it takes the body rather than
+ * fetching one, for the reason `validateWorkflow` is pure: this file is imported
+ * by the browser entry point.
+ *
+ * ## What it refuses
+ *
+ * A sink body whose `targetType` differs from the one already on the node. That
+ * is not a tidiness check — it is the same shape as `WorkflowRunSteps.checkCall`
+ * and it is load-bearing for the same reason. A graph's sinks are checked
+ * against the author's write grants (`assertMayWriteTypes`) using the type on
+ * the node, at save time. If a reusable body could repoint that afterwards, then
+ * editing a shared sink would write into a type that nobody with access to this
+ * graph was ever granted — and it would do it on a schedule, with the graph's
+ * own diff showing nothing. So the disagreement fails, naming both types, and
+ * the repair is that the referencing graph is re-saved and re-checked.
+ *
+ * A mismatched *kind* is refused for the plainer reason that there is nothing
+ * sensible to do with it: a sink body on a source node is a reference somebody
+ * repointed at the wrong object, and folding half of it in would produce a node
+ * that is neither.
+ */
+function applyReusableNode(node, body) {
+    if (body.kind === 'source') {
+        if (node.kind !== 'source') {
+            throw new Error(reusableKindMismatch(node, body.kind));
+        }
+        return {
+            ...node,
+            sourceKind: body.sourceKind,
+            connectionId: body.connectionId,
+            config: body.config,
+            secretEnvVar: body.secretEnvVar,
+            mode: body.mode,
+        };
+    }
+    if (body.kind === 'sink') {
+        if (node.kind !== 'sink') {
+            throw new Error(reusableKindMismatch(node, body.kind));
+        }
+        if (node.targetType.length > 0 && node.targetType !== body.targetType) {
+            throw new Error(`Sink "${node.name}" (${node.id}) commits ${node.targetType}, and the reusable node it uses now commits ${body.targetType}. A graph is checked against the types its sinks write at the moment it is saved, so a shared sink is not allowed to repoint one afterwards — that would write into a type nobody here was granted. Re-save this graph to adopt ${body.targetType}, which checks the grants again, or pin this node to the version that still commits ${node.targetType}.`);
+        }
+        return { ...node, targetType: body.targetType, mode: body.mode };
+    }
+    return unreachableReusableNodeKind(body, 'applyReusableNode');
+}
+function reusableKindMismatch(node, bodyKind) {
+    return `Node "${node.name}" (${node.id}) is a ${node.kind} node and the reusable node it names is a ${bodyKind}. A reference that changed kind under a graph would leave a node that is neither, so this is refused rather than half-applied.`;
+}
+/** Whether a stored value is a reusable body this build can execute. */
+function isReusableNodeBody(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const kind = Reflect.get(value, 'kind');
+    if (kind === 'source') {
+        const config = Reflect.get(value, 'config');
+        return (isConnectorKind(Reflect.get(value, 'sourceKind')) &&
+            typeof config === 'object' &&
+            config !== null &&
+            !Array.isArray(config));
+    }
+    if (kind === 'sink') {
+        const targetType = Reflect.get(value, 'targetType');
+        return typeof targetType === 'string' && targetType.length > 0;
+    }
+    // Refused rather than defaulted, exactly as `isWorkflowNode` refuses a kind it
+    // does not know: a body read back as something this build has no rule for
+    // would be folded onto a node as nothing at all, and the node would then run
+    // whatever was cached on it while claiming to be an instance of the library's.
+    return false;
+}
+/**
+ * The body a node is currently carrying, ready to be saved under a name.
+ *
+ * The other direction of {@link applyReusableNode}, and the reason
+ * save-as-reusable cannot silently deep-copy: this is what gets stored, the node
+ * keeps a `useId` pointing at it, and nothing anywhere duplicates a graph.
+ *
+ * Answers `undefined` for a kind that cannot be reusable rather than throwing,
+ * because the caller is a route answering a person who pressed a button on a
+ * node — {@link nodeKindIsReusable} is what a screen asks before offering it,
+ * and the route repeats the question rather than trusting the screen asked.
+ */
+function reusableNodeBodyOf(node) {
+    if (node.kind === 'source') {
+        return {
+            kind: 'source',
+            sourceKind: node.sourceKind,
+            connectionId: node.connectionId,
+            config: node.config,
+            secretEnvVar: node.secretEnvVar,
+            mode: node.mode,
+        };
+    }
+    if (node.kind === 'sink') {
+        return { kind: 'sink', targetType: node.targetType, mode: node.mode };
+    }
+    return undefined;
+}
+function describeVersionPin(version, subject) {
+    if (version === undefined) {
+        return {
+            pinned: false,
+            label: 'follows the latest',
+            detail: `This node runs whatever ${subject} says today. An edit to it reaches this graph on the next run, with no new version of this graph and nothing in its diff — which is what you want when the point is that everybody moves together, and is worth pinning against when it is not.`,
+        };
+    }
+    return {
+        pinned: true,
+        label: `pinned to v${version}`,
+        detail: `This node runs v${version} of ${subject} and stays there while it is edited elsewhere. Moving to a newer version is an edit to this graph, so it has a diff and a version of its own. A pin to a version that has been superseded more than ${catalog_workspace_1.CATALOG_REVISION_LIMIT} times can no longer be produced, and the run fails saying so rather than quietly using the latest.`,
+    };
+}
 /**
  * Which side of an {@link WorkflowIfNode} a wire leaves by.
  *
@@ -980,6 +1190,15 @@ exports.WORKFLOW_ISSUE_CODES = [
     'filter-predicate-invalid',
     'filter-narrows-unacknowledged',
     'filter-narrows-nothing',
+    /**
+     * A version pin that is not a version — `0`, `2.5`, `"3"`, `-1`.
+     *
+     * One code for both pins, because they are one mistake: a threshold that
+     * cannot name a version can only ever fail to resolve, and it fails inside a
+     * durable step halfway through a load rather than on the canvas. The same
+     * argument `if-threshold-invalid` makes one field along.
+     */
+    'version-pin-invalid',
 ];
 /**
  * Everything that makes a graph unrunnable, in one pure function.
@@ -1165,8 +1384,74 @@ function checkNodeWiring(nodes, incoming, outgoing, issues) {
         const unconfigured = nodeIsUnconfigured(node);
         if (unconfigured)
             issues.push(unconfigured);
+        checkVersionPins(node, issues);
+    }
+}
+/**
+ * Every version pin on this node names a version that could exist.
+ *
+ * Both pins in one place, because they are one rule and splitting it is how one
+ * of the two ends up accepting `0`. Checked here rather than only at the HTTP
+ * boundary because `validateWorkflow` is what the canvas runs, so this is the
+ * difference between a refusal on the screen where the number was typed and a
+ * 400 after pressing Save.
+ *
+ * A pin has to be a whole number of at least one, matching what a version
+ * actually is: {@link CatalogTransform.version} and
+ * {@link CatalogReusableNode.version} both start at 1 and count up in ones.
+ * `"3"` — which is what an unparsed form field sends — is refused rather than
+ * coerced, for the reason `if-threshold-invalid` refuses it: a pin that no
+ * stored version can equal resolves to nothing, and it does so inside a durable
+ * step in the middle of a load.
+ *
+ * A `useVersion` with no `useId` is caught here too, as an invalid pin rather
+ * than as its own code: it pins a reference that does not exist, so the number
+ * can never be looked up.
+ */
+function checkVersionPins(node, issues) {
+    if (node.kind === 'transform') {
+        const invalid = badPin(node.transformVersion);
+        if (invalid) {
+            issues.push({
+                code: 'version-pin-invalid',
+                nodeIds: [node.id],
+                message: `Transform node "${node.name}" (${node.id}) is pinned to version ${invalid} of its code, and a version is a whole number of at least 1. Leave it unset for the node to follow the latest.`,
+            });
+        }
+        return;
+    }
+    if (!nodeKindIsReusable(node.kind))
+        return;
+    // Narrowed off the union rather than read off `node` with a property check,
+    // so a kind that becomes reusable without gaining the fields is a type error
+    // here and not a check that silently passes.
+    if (node.kind !== 'source' && node.kind !== 'sink')
+        return;
+    const invalid = badPin(node.useVersion);
+    if (invalid) {
+        issues.push({
+            code: 'version-pin-invalid',
+            nodeIds: [node.id],
+            message: `Node "${node.name}" (${node.id}) is pinned to version ${invalid} of the reusable node it uses, and a version is a whole number of at least 1. Leave it unset for the node to follow the latest.`,
+        });
+        return;
+    }
+    if (node.useVersion !== undefined && node.useId === undefined) {
+        issues.push({
+            code: 'version-pin-invalid',
+            nodeIds: [node.id],
+            message: `Node "${node.name}" (${node.id}) is pinned to version ${node.useVersion} but names no reusable node, so there is nothing for that version to be a version of.`,
+        });
     }
 }
+/** The offending value, rendered, or `undefined` when the pin is fine or absent. */
+function badPin(version) {
+    if (version === undefined)
+        return undefined;
+    if (typeof version === 'number' && Number.isInteger(version) && version >= 1)
+        return undefined;
+    return JSON.stringify(version);
+}
 /**
  * Every wire out of an `if` names a branch, and no other wire does.
  *
@@ -1735,14 +2020,30 @@ function canonicalNode(node) {
             // Sorted keys, so a canvas that rewrites the object in a different order
             // does not look like an edit.
             sortedEntries(node.config),
+            // Appended only when there is a reference, exactly as `edge.branch` above
+            // is appended only when there is a label, and for the same reason: adding
+            // reusable nodes to this file must not renumber the version of a single
+            // graph that did not change. Every source drawn before they existed
+            // hashes to the string it always did.
+            ...canonicalReuse(node),
         ]);
     }
     if (node.kind === 'transform') {
-        // The transform's *version* is deliberately not in here. Editing a
-        // transform is already recorded as a new transform version, and folding it
-        // in would bump every graph that references it — which would say the wiring
-        // changed when it did not.
-        return JSON.stringify([node.id, node.kind, node.transformId]);
+        // The transform's *version as stored* is deliberately not in here, and that
+        // has not changed: editing a transform is recorded as a new transform
+        // version, and folding it in would bump every graph that references it,
+        // which would claim the wiring changed when it did not.
+        //
+        // What IS in here is the *pin* — which is the opposite choice for the
+        // opposite reason, and the same one `call` makes one branch down. Moving a
+        // node from v3 to v5, or off a pin onto the latest, changes what the load
+        // runs as surely as rewiring it does, and is a decision somebody made in
+        // this graph. Appended rather than always present, so an unpinned node —
+        // which is every transform node in every deployment today — hashes to
+        // exactly the string it always did.
+        return node.transformVersion === undefined
+            ? JSON.stringify([node.id, node.kind, node.transformId])
+            : JSON.stringify([node.id, node.kind, node.transformId, node.transformVersion]);
     }
     if (node.kind === 'call') {
         // The called version IS in here, and that is the opposite choice from a
@@ -1778,10 +2079,35 @@ function canonicalNode(node) {
         ]);
     }
     if (node.kind === 'sink') {
-        return JSON.stringify([node.id, node.kind, node.targetType, node.mode ?? 'full']);
+        return JSON.stringify([
+            node.id,
+            node.kind,
+            node.targetType,
+            node.mode ?? 'full',
+            ...canonicalReuse(node),
+        ]);
     }
     return unreachableNodeKind(node, 'workflowGraphHash');
 }
+/**
+ * The reusable reference, as zero, one or two trailing hash components.
+ *
+ * Zero when there is no reference, which is what makes this additive: every
+ * graph stored before reusable nodes existed produces the same canonical string
+ * it always did, so no version is renumbered by a deployment picking up this
+ * release. One when the reference follows the latest. Two when it is pinned.
+ *
+ * "Follows the latest" and "pinned to v1" hash differently, and they must:
+ * moving a node off a pin is a real change to what it will run next month, and a
+ * fingerprint that could not see it would let somebody unpin a shared sink with
+ * no version bump and no diff — which is precisely the silence this feature was
+ * built to end.
+ */
+function canonicalReuse(node) {
+    if (node.useId === undefined)
+        return [];
+    return node.useVersion === undefined ? [node.useId] : [node.useId, node.useVersion];
+}
 /**
  * The parts of a predicate that decide which branch runs.
  *
@@ -1872,13 +2198,13 @@ function fnv1a(input, offset) {
 function isWorkflowNode(value) {
     if (typeof value !== 'object' || value === null)
         return false;
-    const id = Reflect.get(value, 'id');
-    const name = Reflect.get(value, 'name');
     const kind = Reflect.get(value, 'kind');
-    if (typeof id !== 'string' || typeof name !== 'string')
-        return false;
     if (!isWorkflowNodeKind(kind))
         return false;
+    // Everything every kind carries, checked once before the narrowing below
+    // rather than inside the branches that could carry it. See {@link hasNodeBase}.
+    if (!hasNodeBase(value))
+        return false;
     if (kind === 'transform') {
         return typeof Reflect.get(value, 'transformId') === 'string';
     }
@@ -1934,6 +2260,49 @@ function isNarrowsList(value) {
         return true;
     return Array.isArray(value) && value.every((type) => typeof type === 'string');
 }
+/**
+ * A version pin as it comes back out of a JSON column: absent, or a whole number
+ * of at least one.
+ *
+ * The same rule {@link checkVersionPins} states, applied at the read boundary,
+ * because the two answer different questions about the same field. The validator
+ * tells an author their graph will not run; this decides whether a graph stored
+ * by some other build can be read at all. Absent is accepted and always will be
+ * — it is what every node written before pins existed carries, and it means
+ * "follows the latest", which is exactly what those nodes have always done.
+ */
+function isOptionalVersion(value) {
+    if (value === undefined)
+        return true;
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1;
+}
+/**
+ * Everything every node kind carries, whatever kind it is: its identity, and
+ * the things it points at outside itself.
+ *
+ * Checked once, before {@link isWorkflowNode} narrows per kind, rather than in
+ * the branches that could carry each field. The references are declared on two
+ * members of the union and a node arriving as JSON does not respect that, so a
+ * single check is both cheaper and stricter than two — and a kind that becomes
+ * reusable later inherits it rather than having to remember it.
+ *
+ * A pin read back as `"3"` or as `0` names no stored version, and the resolution
+ * happens inside a durable step in the middle of a load. So it is refused where
+ * a graph is read out of a column rather than surviving as far as the run that
+ * cannot honour it.
+ */
+function hasNodeBase(value) {
+    if (typeof Reflect.get(value, 'id') !== 'string')
+        return false;
+    if (typeof Reflect.get(value, 'name') !== 'string')
+        return false;
+    if (!isOptionalVersion(Reflect.get(value, 'transformVersion')))
+        return false;
+    if (!isOptionalVersion(Reflect.get(value, 'useVersion')))
+        return false;
+    const useId = Reflect.get(value, 'useId');
+    return useId === undefined || typeof useId === 'string';
+}
 /**
  * The narrowing counterpart of {@link unreachableNodeKind}.
  *
@@ -1992,6 +2361,35 @@ function supportsWorkflows(store) {
 function supportsTransformRevisions(store) {
     return typeof store.listTransformRevisions === 'function';
 }
+/**
+ * Whether this store can produce one particular version of a transform's code.
+ *
+ * Separate from {@link supportsTransformRevisions}, and not implied by it: one
+ * answers "can a screen show the history", the other "can a run honour a pin".
+ * A store could reasonably have the first and not the second, and folding them
+ * together would let a graph be saved with a pin this deployment cannot resolve
+ * — discovered mid-load rather than at the moment the pin was set.
+ */
+function supportsTransformPins(store) {
+    return typeof store.getTransformAt === 'function';
+}
+/**
+ * Whether this store can hold reusable nodes.
+ *
+ * All six, and never a subset. A store with `getReusableNode` but no
+ * `reusableNodeUses` could serve a picker and could not answer the question the
+ * feature exists for — and the shape of that failure is a console offering to
+ * share a node while being unable to say who already depends on it, which is
+ * worse than not offering at all.
+ */
+function supportsReusableNodes(store) {
+    return (typeof store.listReusableNodes === 'function' &&
+        typeof store.getReusableNode === 'function' &&
+        typeof store.getReusableNodeAt === 'function' &&
+        typeof store.saveReusableNode === 'function' &&
+        typeof store.deleteReusableNode === 'function' &&
+        typeof store.reusableNodeUses === 'function');
+}
 function supportsWorkflowStages(store) {
     return typeof store.writeStage === 'function' && typeof store.readStage === 'function';
 }

package/dist/catalog.workspace.d.ts

@@ -302,8 +302,30 @@ export interface CatalogTraceSpan {
      * second answer to a question that already has one.
      */
     principalId?: string;
-    /** The event payload, verbatim — the same bytes the flat trail shows. */
-    detail: Record<string, unknown>;
+    /**
+     * The event payload, verbatim — the same bytes the flat trail shows.
+     *
+     * Optional, and which call you made decides whether it is there:
+     * {@link CatalogTraceStore.getTrace} carries it, {@link
+     * CatalogTraceStore.listTraces} does not.
+     *
+     * The asymmetry is the whole point. A payload is arbitrary JSON of unbounded
+     * width, and a page of traces carries every span of every trace on it — a
+     * real 50-trace page measured 28,022 spans, of which the payloads alone were
+     * 4.3 MB of a 10.4 MB answer, read from the database, parsed, and serialised
+     * again on a screen that re-polls every ten seconds. None of it was drawn:
+     * the list renders a waterfall, which needs when each event happened and
+     * whether it failed, and the payload is read only when somebody expands a
+     * trace — at which point there is exactly one trace to fetch it for.
+     *
+     * So the list is not missing anything it showed before. `failed` and `error`
+     * are still derived from the payload, in the database rather than from these
+     * bytes, and a consumer that needs the payload asks `getTrace` for the one
+     * trace it needs it for. Guard it rather than assuming it: a `??  {}` on a
+     * list span is correct, and dereferencing it is the one thing this shape
+     * makes unsafe.
+     */
+    detail?: Record<string, unknown>;
     occurredAt: string;
     /** Milliseconds from the first event of the trace. Where the bar starts. */
     offsetMs: number;

package/dist/client.d.ts

@@ -153,8 +153,8 @@ export declare const catalogRoutes: {
     readonly traces: () => string;
     readonly trace: (id: string) => string;
 };
-export type { CatalogConnection, CatalogConnector, ConnectionCheck, CatalogTransform, CatalogWorkflow, CatalogWorkflowCapabilities, ConnectorKind, ConnectorRun, TransformLanguage, TransformResult, CallableWorkflowRef, WorkflowBranchLabel, WorkflowCallEnvelope, WorkflowCallNode, WorkflowCallOutput, WorkflowEdge, WorkflowExecutionMode, WorkflowFilterAll, WorkflowFilterAny, WorkflowFilterComparison, WorkflowFilterGroup, WorkflowFilterNode, WorkflowFilterOneOf, WorkflowFilterOperator, WorkflowFilterPredicate, WorkflowFilterPredicateKind, WorkflowFilterPresence, WorkflowFilterValue, WorkflowGraph, WorkflowEnvPredicate, WorkflowIfNode, WorkflowIfPredicate, WorkflowIssueCode, WorkflowNode, WorkflowNodeKind, WorkflowNodeOutcome, WorkflowPredicateKind, WorkflowRowCountPredicate, WorkflowRunOrderEntry, WorkflowSinkNode, WorkflowSkipReason, WorkflowSourceNode, WorkflowStageRef, WorkflowTransformNode, WorkflowValidationIssue, } from './catalog.pipeline';
-export { CONNECTOR_KINDS, isConnectorKind, isTransformLanguage, isWorkflowEdge, isWorkflowNode, REDACTED_SECRET, TRANSFORM_LANGUAGES, readWorkflowCallOutput, WORKFLOW_CALL_CONTRACT, } from './catalog.pipeline';
+export type { CatalogConnection, CatalogConnector, ConnectionCheck, CatalogTransform, CatalogWorkflow, CatalogWorkflowCapabilities, ConnectorKind, ConnectorRun, TransformLanguage, TransformResult, CallableWorkflowRef, WorkflowBranchLabel, WorkflowCallEnvelope, WorkflowCallNode, WorkflowCallOutput, WorkflowEdge, WorkflowExecutionMode, WorkflowFilterAll, WorkflowFilterAny, WorkflowFilterComparison, WorkflowFilterGroup, WorkflowFilterNode, WorkflowFilterOneOf, WorkflowFilterOperator, WorkflowFilterPredicate, WorkflowFilterPredicateKind, WorkflowFilterPresence, WorkflowFilterValue, WorkflowGraph, WorkflowEnvPredicate, WorkflowIfNode, WorkflowIfPredicate, WorkflowIssueCode, WorkflowNode, WorkflowNodeKind, WorkflowNodeOutcome, WorkflowPredicateKind, WorkflowRowCountPredicate, WorkflowRunOrderEntry, WorkflowSinkNode, WorkflowSkipReason, WorkflowSourceNode, WorkflowStageRef, WorkflowTransformNode, WorkflowValidationIssue, CatalogReusableNode, CatalogReusableNodeUse, ReusableNodeBody, ReusableNodeKind, ReusableNodeRef, ReusableSinkBody, ReusableSourceBody, VersionPinCopy, } from './catalog.pipeline';
+export { CONNECTOR_KINDS, isConnectorKind, isTransformLanguage, isWorkflowEdge, isWorkflowNode, REDACTED_SECRET, TRANSFORM_LANGUAGES, readWorkflowCallOutput, WORKFLOW_CALL_CONTRACT, applyReusableNode, reusableNodeBodyOf, isReusableNodeBody, isReusableNodeKind, REUSABLE_NODE_KINDS, NODE_KIND_IS_REUSABLE, nodeKindIsReusable, unreachableReusableNodeKind, describeVersionPin, } from './catalog.pipeline';
 /**
  * The workflow validator, shipped to the browser deliberately.
  *

package/dist/client.js

@@ -11,8 +11,8 @@
  * types are.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isWorkflowFilterValue = exports.isWorkflowFilterPredicateKind = exports.isWorkflowFilterPredicate = exports.isWorkflowFilterOperator = exports.isWorkflowBranchLabel = exports.WORKFLOW_SKIP_REASONS = exports.WORKFLOW_FILTER_PREDICATE_KINDS = exports.WORKFLOW_FILTER_OPERATORS = exports.WORKFLOW_FILTER_MAX_VALUES = exports.WORKFLOW_FILTER_MAX_DEPTH = exports.WORKFLOW_FILTER_COLUMN_PATTERN = exports.WORKFLOW_PREDICATE_KINDS = exports.WORKFLOW_BRANCH_LABELS = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.workflowRowY = exports.workflowColumnX = exports.WORKFLOW_ROW_GAP = exports.WORKFLOW_NODE_WIDTH = exports.WORKFLOW_NODE_HEIGHT = exports.WORKFLOW_COLUMN_GAP = exports.WORKFLOW_CALL_CONTRACT = exports.readWorkflowCallOutput = exports.TRANSFORM_LANGUAGES = exports.REDACTED_SECRET = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = exports.UnsafeIdentifierError = exports.physicalColumn = exports.outputAlias = exports.isSafeIdentifier = exports.VALUELESS_FILTER_OPERATORS = exports.resolveObjectFilters = exports.parseObjectFilter = exports.offeredFilterOperators = exports.isCatalogFilterOperator = exports.filterOperatorsFor = exports.filterOperatorTakesValue = exports.encodeObjectFilter = exports.coerceFilterValue = exports.CATALOG_FILTER_OPERATORS = exports.CATALOG_FILTER_LIMIT = exports.CATALOG_REVISION_LIMIT = void 0;
-exports.DELETE_RECONCILIATION_STRATEGIES = exports.callableWorkflowBlock = exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.unreachablePredicateKind = exports.unreachableNodeKind = exports.unreachableFilterPredicateKind = exports.unreachableFilterOperator = exports.workflowNodeRuns = exports.workflowNarrowedTypes = exports.workflowFilterMatches = exports.isWorkflowSkipReason = exports.isWorkflowPredicateKind = exports.isWorkflowIfPredicate = void 0;
+exports.WORKFLOW_FILTER_MAX_DEPTH = exports.WORKFLOW_FILTER_COLUMN_PATTERN = exports.WORKFLOW_PREDICATE_KINDS = exports.WORKFLOW_BRANCH_LABELS = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.workflowRowY = exports.workflowColumnX = exports.WORKFLOW_ROW_GAP = exports.WORKFLOW_NODE_WIDTH = exports.WORKFLOW_NODE_HEIGHT = exports.WORKFLOW_COLUMN_GAP = exports.describeVersionPin = exports.unreachableReusableNodeKind = exports.nodeKindIsReusable = exports.NODE_KIND_IS_REUSABLE = exports.REUSABLE_NODE_KINDS = exports.isReusableNodeKind = exports.isReusableNodeBody = exports.reusableNodeBodyOf = exports.applyReusableNode = exports.WORKFLOW_CALL_CONTRACT = exports.readWorkflowCallOutput = exports.TRANSFORM_LANGUAGES = exports.REDACTED_SECRET = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = exports.UnsafeIdentifierError = exports.physicalColumn = exports.outputAlias = exports.isSafeIdentifier = exports.VALUELESS_FILTER_OPERATORS = exports.resolveObjectFilters = exports.parseObjectFilter = exports.offeredFilterOperators = exports.isCatalogFilterOperator = exports.filterOperatorsFor = exports.filterOperatorTakesValue = exports.encodeObjectFilter = exports.coerceFilterValue = exports.CATALOG_FILTER_OPERATORS = exports.CATALOG_FILTER_LIMIT = exports.CATALOG_REVISION_LIMIT = void 0;
+exports.DELETE_RECONCILIATION_STRATEGIES = exports.callableWorkflowBlock = exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.unreachablePredicateKind = exports.unreachableNodeKind = exports.unreachableFilterPredicateKind = exports.unreachableFilterOperator = exports.workflowNodeRuns = exports.workflowNarrowedTypes = exports.workflowFilterMatches = exports.isWorkflowSkipReason = exports.isWorkflowPredicateKind = exports.isWorkflowIfPredicate = exports.isWorkflowFilterValue = exports.isWorkflowFilterPredicateKind = exports.isWorkflowFilterPredicate = exports.isWorkflowFilterOperator = exports.isWorkflowBranchLabel = exports.WORKFLOW_SKIP_REASONS = exports.WORKFLOW_FILTER_PREDICATE_KINDS = exports.WORKFLOW_FILTER_OPERATORS = exports.WORKFLOW_FILTER_MAX_VALUES = void 0;
 exports.isDeleteReconciliationStrategy = isDeleteReconciliationStrategy;
 exports.pipelineExpectationRoutes = pipelineExpectationRoutes;
 // A value, not a type: a screen saying how far back the history goes should read
@@ -151,6 +151,28 @@ Object.defineProperty(exports, "TRANSFORM_LANGUAGES", { enumerable: true, get: f
 // runner does, so the two cannot disagree about what "no rows" looks like.
 Object.defineProperty(exports, "readWorkflowCallOutput", { enumerable: true, get: function () { return catalog_pipeline_1.readWorkflowCallOutput; } });
 Object.defineProperty(exports, "WORKFLOW_CALL_CONTRACT", { enumerable: true, get: function () { return catalog_pipeline_1.WORKFLOW_CALL_CONTRACT; } });
+// Reusable nodes, and the two directions a screen needs them in: the fold onto
+// a node, so a picker can show what choosing one will do without a round trip,
+// and the lift off a node, so "save this as reusable" sends the same body the
+// server would have derived. One implementation of each rather than a copy per
+// screen, for the reason `validateWorkflow` is shipped here at all — the
+// alternative is a console that shows one thing and a server that stores
+// another.
+Object.defineProperty(exports, "applyReusableNode", { enumerable: true, get: function () { return catalog_pipeline_1.applyReusableNode; } });
+Object.defineProperty(exports, "reusableNodeBodyOf", { enumerable: true, get: function () { return catalog_pipeline_1.reusableNodeBodyOf; } });
+Object.defineProperty(exports, "isReusableNodeBody", { enumerable: true, get: function () { return catalog_pipeline_1.isReusableNodeBody; } });
+Object.defineProperty(exports, "isReusableNodeKind", { enumerable: true, get: function () { return catalog_pipeline_1.isReusableNodeKind; } });
+Object.defineProperty(exports, "REUSABLE_NODE_KINDS", { enumerable: true, get: function () { return catalog_pipeline_1.REUSABLE_NODE_KINDS; } });
+// Which kinds may be offered a "save as reusable" affordance at all. Read
+// rather than restated, because a hand-written list on a screen is exactly how
+// the `filter` node shipped with no way to create it.
+Object.defineProperty(exports, "NODE_KIND_IS_REUSABLE", { enumerable: true, get: function () { return catalog_pipeline_1.NODE_KIND_IS_REUSABLE; } });
+Object.defineProperty(exports, "nodeKindIsReusable", { enumerable: true, get: function () { return catalog_pipeline_1.nodeKindIsReusable; } });
+Object.defineProperty(exports, "unreachableReusableNodeKind", { enumerable: true, get: function () { return catalog_pipeline_1.unreachableReusableNodeKind; } });
+// One wording for "pinned" and "follows the latest", so an inspector cannot
+// describe following as though it were pinning — which is the whole
+// misunderstanding the pin exists to end.
+Object.defineProperty(exports, "describeVersionPin", { enumerable: true, get: function () { return catalog_pipeline_1.describeVersionPin; } });
 /**
  * The workflow validator, shipped to the browser deliberately.
  *

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { type CatalogOverlayStore, FileCatalogOverlayStore, InMemoryCatalogOverl
 export { CATALOG_OVERLAY_STORE } from './catalog.overlay-store.token';
 export { MikroOrmCatalogRegistry } from './catalog.registry';
 export { CatalogRegistry } from './catalog.registry.base';
-export { CATALOG_PIPELINE_STORE, CODE_CONTEXT_CONTRACT, type CatalogCodeContext, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogLoadExpectations, type CatalogLoadExpectationStore, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type CallableWorkflowBlock, type CallableWorkflowDisagreement, type CallableWorkflowRef, callableWorkflowBlock, type ConnectorKind, type ConnectorRun, type DeleteReconciliation, isConnectorKind, isPipelineStore, isTransformLanguage, type LoadExpectation, type RowCountBound, type StoredLoadExpectation, readWorkflowCallOutput, REDACTED_SECRET, supportsLoadExpectations, supportsTransformRevisions, isWorkflowBranchLabel, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowFilterOperator, isWorkflowFilterPredicate, isWorkflowFilterPredicateKind, isWorkflowFilterValue, isWorkflowIfPredicate, isWorkflowNode, isWorkflowNodeKind, isWorkflowPredicateKind, isWorkflowSkipReason, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, unreachableFilterOperator, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, validateWorkflow, WORKFLOW_BRANCH_LABELS, WORKFLOW_CALL_CONTRACT, WORKFLOW_COLUMN_GAP, WORKFLOW_EXECUTION_MODES, WORKFLOW_FILTER_COLUMN_PATTERN, WORKFLOW_FILTER_MAX_DEPTH, WORKFLOW_FILTER_MAX_VALUES, WORKFLOW_FILTER_OPERATORS, WORKFLOW_FILTER_PREDICATE_KINDS, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_HEIGHT, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_NODE_WIDTH, WORKFLOW_PREDICATE_KINDS, WORKFLOW_ROW_GAP, WORKFLOW_SKIP_REASONS, WORKFLOW_STATUSES, type WorkflowBranchLabel, workflowColumnX, workflowRowY, type WorkflowCallEnvelope, type WorkflowCallNode, type WorkflowCallOutput, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowFilterAll, type WorkflowFilterAny, type WorkflowFilterComparison, type WorkflowFilterGroup, workflowFilterMatches, type WorkflowFilterNode, type WorkflowFilterOneOf, type WorkflowFilterOperator, type WorkflowFilterPredicate, type WorkflowFilterPredicateKind, type WorkflowFilterPresence, type WorkflowFilterValue, type WorkflowGraph, workflowGraphHash, type WorkflowEnvPredicate, type WorkflowIfNode, type WorkflowIfPredicate, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, workflowNarrowedTypes, type WorkflowNodeOutcome, workflowNodeRuns, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowRunOrderEntry, type WorkflowPredicateKind, type WorkflowRowCountPredicate, type WorkflowSinkNode, type WorkflowSkipReason, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
+export { CATALOG_PIPELINE_STORE, CODE_CONTEXT_CONTRACT, type CatalogCodeContext, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogLoadExpectations, type CatalogLoadExpectationStore, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type CallableWorkflowBlock, type CallableWorkflowDisagreement, type CallableWorkflowRef, callableWorkflowBlock, type ConnectorKind, type ConnectorRun, type DeleteReconciliation, isConnectorKind, isPipelineStore, isTransformLanguage, type LoadExpectation, type RowCountBound, type StoredLoadExpectation, readWorkflowCallOutput, REDACTED_SECRET, supportsLoadExpectations, supportsReusableNodes, supportsTransformPins, supportsTransformRevisions, applyReusableNode, type CatalogReusableNode, type CatalogReusableNodeStore, type CatalogReusableNodeUse, describeVersionPin, isReusableNodeBody, isReusableNodeKind, NODE_KIND_IS_REUSABLE, nodeKindIsReusable, REUSABLE_NODE_KINDS, type ReusableNodeBody, type ReusableNodeKind, type ReusableNodeRef, type ReusableSinkBody, type ReusableSourceBody, reusableNodeBodyOf, unreachableReusableNodeKind, type VersionPinCopy, isWorkflowBranchLabel, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowFilterOperator, isWorkflowFilterPredicate, isWorkflowFilterPredicateKind, isWorkflowFilterValue, isWorkflowIfPredicate, isWorkflowNode, isWorkflowNodeKind, isWorkflowPredicateKind, isWorkflowSkipReason, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, unreachableFilterOperator, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, validateWorkflow, WORKFLOW_BRANCH_LABELS, WORKFLOW_CALL_CONTRACT, WORKFLOW_COLUMN_GAP, WORKFLOW_EXECUTION_MODES, WORKFLOW_FILTER_COLUMN_PATTERN, WORKFLOW_FILTER_MAX_DEPTH, WORKFLOW_FILTER_MAX_VALUES, WORKFLOW_FILTER_OPERATORS, WORKFLOW_FILTER_PREDICATE_KINDS, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_HEIGHT, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_NODE_WIDTH, WORKFLOW_PREDICATE_KINDS, WORKFLOW_ROW_GAP, WORKFLOW_SKIP_REASONS, WORKFLOW_STATUSES, type WorkflowBranchLabel, workflowColumnX, workflowRowY, type WorkflowCallEnvelope, type WorkflowCallNode, type WorkflowCallOutput, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowFilterAll, type WorkflowFilterAny, type WorkflowFilterComparison, type WorkflowFilterGroup, workflowFilterMatches, type WorkflowFilterNode, type WorkflowFilterOneOf, type WorkflowFilterOperator, type WorkflowFilterPredicate, type WorkflowFilterPredicateKind, type WorkflowFilterPresence, type WorkflowFilterValue, type WorkflowGraph, workflowGraphHash, type WorkflowEnvPredicate, type WorkflowIfNode, type WorkflowIfPredicate, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, workflowNarrowedTypes, type WorkflowNodeOutcome, workflowNodeRuns, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowRunOrderEntry, type WorkflowPredicateKind, type WorkflowRowCountPredicate, type WorkflowSinkNode, type WorkflowSkipReason, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
 export { type ColumnarStageBatch, STAGE_ENCODING, STAGE_ENCODING_VERSION, type StagePayload, classifyStagePayload, decodeStageRows, encodeStageRows, isColumnarStageBatch, } from './catalog.stage-encoding';
 export * from './catalog.environment';
 export { QueryCache } from './catalog.query-cache';