@dudousxd/nestjs-catalog 0.17.0 → 0.19.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,14 @@ 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.describeLiveVersion = describeLiveVersion;
 exports.isWorkflowBranchLabel = isWorkflowBranchLabel;
 exports.isWorkflowStatus = isWorkflowStatus;
 exports.isWorkflowExecutionMode = isWorkflowExecutionMode;
@@ -40,10 +48,20 @@ exports.workflowGraphHash = workflowGraphHash;
 exports.isWorkflowNode = isWorkflowNode;
 exports.isWorkflowEdge = isWorkflowEdge;
 exports.supportsWorkflows = supportsWorkflows;
+exports.supportsWorkflowReleases = supportsWorkflowReleases;
+exports.liveWorkflowVersion = liveWorkflowVersion;
 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 +785,239 @@ 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.`,
+    };
+}
+/**
+ * The same question about a whole graph: does it follow its latest save, or does
+ * it run a version somebody chose?
+ *
+ * Shares {@link VersionPinCopy} and its two labels with
+ * {@link describeVersionPin} deliberately. A console that said "pinned to v6"
+ * about a transform node and invented different words for a graph would be two
+ * vocabularies for one idea, and the reader would have to work out whether they
+ * meant the same thing — which is the confusion the whole notion of a pin exists
+ * to remove.
+ *
+ * The *detail* differs, and only where the facts do. Two of them:
+ *
+ * - A node's pin can outlive the revision it names, because `catalog_revision`
+ *   is capped. A graph's cannot: releases are never evicted, precisely because
+ *   the one a live pointer names is the graph production is running. So this
+ *   copy makes no eviction caveat, and must not acquire one.
+ * - Following the latest is *cheap* for a node — everybody moves together, which
+ *   is often the point. For a graph it means editing is deploying, which is the
+ *   hazard this field was added to remove. So the unpinned sentence here is a
+ *   warning where the node's is a trade-off.
+ */
+function describeLiveVersion(workflow) {
+    if (workflow.liveVersion === undefined) {
+        return {
+            pinned: false,
+            label: 'follows the latest',
+            detail: `This graph runs whatever its latest save holds, currently v${workflow.version}. Editing it is therefore the same act as deploying it: the next scheduled window runs what was last saved, with nobody having decided that it should. Releasing a version and setting it live is what separates the two.`,
+        };
+    }
+    return {
+        pinned: true,
+        label: `running v${workflow.liveVersion}`,
+        detail: workflow.liveVersion === workflow.version
+            ? `This graph runs the released v${workflow.liveVersion}, which is also its latest save. Editing it from here changes nothing about what runs until a new version is released and set live.`
+            : `This graph runs the released v${workflow.liveVersion} while its latest save is v${workflow.version}. The edits since then are stored and are not running; setting a newer release live is what deploys them, and setting an older one live is a rollback.`,
+    };
+}
 /**
  * Which side of an {@link WorkflowIfNode} a wire leaves by.
  *
@@ -980,6 +1231,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 +1425,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 +2061,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 +2120,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 +2239,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 +2301,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}.
  *
@@ -1983,6 +2393,43 @@ function supportsWorkflows(store) {
         // is the surface a scheduling incident already came through once.
         typeof store.saveWorkflowSchedule === 'function');
 }
+/**
+ * Whether this store can mint a release and be pointed at one.
+ *
+ * All four asked for by name, for the reason `supportsWorkflows` asks for
+ * `publishWorkflow` and `saveWorkflowSchedule` by name rather than assuming they
+ * arrive together: a store with the mint and not the pointer would narrow
+ * cleanly here, let somebody release a graph, and then fail on the call that was
+ * supposed to make it run.
+ *
+ * {@link getWorkflowAt} is the one whose absence is least visible and most
+ * expensive. A store that could hold a `liveVersion` and not resolve it would
+ * point a scheduled load at a version it cannot produce — and the only place
+ * that shows up is a cron window that stops firing.
+ */
+function supportsWorkflowReleases(store) {
+    return (typeof store.releaseWorkflow === 'function' &&
+        typeof store.listWorkflowReleases === 'function' &&
+        typeof store.getWorkflowAt === 'function' &&
+        typeof store.setLiveWorkflowVersion === 'function');
+}
+/**
+ * Which version of this graph a run gets when the caller names none.
+ *
+ * The one implementation of "follow the latest unless something is live", shared
+ * by the scheduler and by the manual run route so the two cannot disagree about
+ * what a cron does and what the button next to it does. That divergence is not
+ * hypothetical: the schedule used to live on the connector and on the workflow
+ * at once, and the whole of `ConnectorScheduler`'s docblock is about what it
+ * cost to have two copies of one answer.
+ *
+ * Not a fallback in the defensive sense. `liveVersion` absent is a stated
+ * position — this graph follows its head — and this function is where that
+ * position is turned into a number, not where a missing value is patched over.
+ */
+function liveWorkflowVersion(workflow) {
+    return workflow.liveVersion ?? workflow.version;
+}
 /**
  * Whether this store keeps a transform's history.
  *
@@ -1992,6 +2439,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/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, CatalogWorkflowRelease, 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, liveWorkflowVersion, REDACTED_SECRET, TRANSFORM_LANGUAGES, readWorkflowCallOutput, WORKFLOW_CALL_CONTRACT, applyReusableNode, reusableNodeBodyOf, isReusableNodeBody, isReusableNodeKind, REUSABLE_NODE_KINDS, NODE_KIND_IS_REUSABLE, nodeKindIsReusable, unreachableReusableNodeKind, describeLiveVersion, describeVersionPin, } from './catalog.pipeline';
 /**
  * The workflow validator, shipped to the browser deliberately.
  *