@dudousxd/nestjs-catalog 0.18.0 → 0.20.0

package/dist/catalog.pipeline.js

@@ -9,14 +9,19 @@
  * 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_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_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;
 exports.isTransformLanguage = isTransformLanguage;
 exports.isWorkflowSkipReason = isWorkflowSkipReason;
 exports.isWorkflowNodeKind = isWorkflowNodeKind;
 exports.unreachableNodeKind = unreachableNodeKind;
 exports.workflowColumnX = workflowColumnX;
 exports.workflowRowY = workflowRowY;
+exports.isWorkflowCallMode = isWorkflowCallMode;
+exports.unreachableCallMode = unreachableCallMode;
+exports.workflowCallMode = workflowCallMode;
 exports.isWorkflowPredicateKind = isWorkflowPredicateKind;
 exports.unreachablePredicateKind = unreachablePredicateKind;
 exports.isWorkflowIfPredicate = isWorkflowIfPredicate;
@@ -34,6 +39,7 @@ exports.applyReusableNode = applyReusableNode;
 exports.isReusableNodeBody = isReusableNodeBody;
 exports.reusableNodeBodyOf = reusableNodeBodyOf;
 exports.describeVersionPin = describeVersionPin;
+exports.describeLiveVersion = describeLiveVersion;
 exports.isWorkflowBranchLabel = isWorkflowBranchLabel;
 exports.isWorkflowStatus = isWorkflowStatus;
 exports.isWorkflowExecutionMode = isWorkflowExecutionMode;
@@ -47,6 +53,8 @@ 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;
@@ -90,6 +98,57 @@ exports.CONNECTOR_KINDS = [
 function isConnectorKind(value) {
     return exports.CONNECTOR_KINDS.some((kind) => kind === value);
 }
+/**
+ * How the bytes behind a `file` or `s3` connector are read as records.
+ *
+ * A list rather than a loose string, for the reason {@link CONNECTOR_KINDS} is
+ * one: this used to be compared against string literals in the parser and
+ * spelled out again in a dropdown, and the two had no way to disagree loudly.
+ * The parser's chain also *ended* in JSON, so a format it did not recognise was
+ * not refused — it was read as JSON, and a spreadsheet handed to `JSON.parse`
+ * fails with a syntax error that names a byte offset rather than the format.
+ *
+ * `xlsx` is the odd one and is named for what it is: the only member whose
+ * payload is binary. The other three are text, and everything that reads them
+ * decodes the bytes first. Anything deciding something *per format* narrows
+ * against this and answers {@link unreachableSourceFormat}.
+ */
+exports.SOURCE_FORMATS = [
+    /** Delimited text with a header row. The delimiter is configurable. */
+    'csv',
+    /** One JSON value per line. */
+    'ndjson',
+    /** A JSON document, optionally with the array nested in an envelope. */
+    'json',
+    /**
+     * A spreadsheet workbook — binary, and the only member that is.
+     *
+     * Named for the modern extension, but the reader identifies the container
+     * from its own bytes, so the legacy `.xls` and the macro-enabled `.xlsm` are
+     * this format too rather than three names for one decision.
+     */
+    'xlsx',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isSourceFormat(value) {
+    return exports.SOURCE_FORMATS.some((format) => format === value);
+}
+/**
+ * The format that never compiles quietly.
+ *
+ * The {@link unreachableNodeKind} of formats, and it exists for the same reason:
+ * a member added to {@link SOURCE_FORMATS} without a branch in the parser should
+ * be a type error naming the file, not a connector that offers a format in a
+ * dropdown and then reads the file as JSON.
+ *
+ * It throws as well as failing to compile, because a connector config is JSON
+ * that outlives the build that wrote it: a `format` stored by a newer deployment
+ * and read by an older one is possible, and falling back to a default for it
+ * would be exactly the silent path this closes.
+ */
+function unreachableSourceFormat(format, where) {
+    throw new Error(`${where} does not handle a source format of ${JSON.stringify(format)}. The format list and every decision made per format are meant to move together.`);
+}
 /**
  * TypeScript is Node's own type stripping, so it costs no compiler and no build
  * step — and types are erased, never checked. A transform with a wrong type
@@ -318,6 +377,109 @@ function workflowColumnX(column) {
 function workflowRowY(row) {
     return row * (exports.WORKFLOW_NODE_HEIGHT + exports.WORKFLOW_ROW_GAP);
 }
+/**
+ * What a {@link WorkflowCallNode} puts on the wire, and the whole of it.
+ *
+ * ## Why there is a second mode at all
+ *
+ * The catalog could not call a workflow that does not know about the catalog.
+ * A `call` node wraps the author's `config` in a {@link WorkflowCallEnvelope},
+ * so a workflow that already exists — one registered years before this package,
+ * whose body reads `data["proc"]` — receives `{catalog: {...}, input: {proc:
+ * ...}}` and dies on the first key it looks for. The only repair available was
+ * to edit the callee, which inverts the dependency exactly the wrong way round:
+ * every workflow anybody wanted to call would have to start depending on this
+ * package's contract, and a Python workflow registered in another repository
+ * would have to be changed to be reachable from a graph.
+ *
+ * ## Why the nesting is not being loosened instead
+ *
+ * The envelope nests for one stated reason, which is on {@link
+ * WorkflowCallEnvelope}: an author's parameter called `runId` must not be able
+ * to shadow the run id. That reason is sound and it is not being weakened. It
+ * simply does not reach the plain mode, because a plain call sends **no catalog
+ * metadata at all** — there is no `runId`, no `nodeId`, no contract number on
+ * the wire, so there is nothing a parameter could shadow. The flat payload is
+ * not the envelope with its guard removed; it is a different, smaller promise.
+ *
+ * ## What the plain mode costs, which is not small
+ *
+ * No `runId` and no `nodeId` means the callee has no key to stage rows under.
+ * Rows travel through the stage store addressed by `(runId, nodeId, batch)` —
+ * see {@link WorkflowStageRef} — and a callee that was told neither cannot
+ * write where the next node would read. So a plain call **cannot return rows to
+ * the graph**, and that is not a convention anybody could follow more carefully:
+ * it is arithmetic. `validateWorkflow` refuses a plain call with an outbound
+ * edge for exactly this reason (`call-plain-has-output`), and its return value
+ * is not read as a row count — see {@link readWorkflowCallOutput} for the shape
+ * that is deliberately *not* consulted on this path.
+ *
+ * A plain call is therefore for its **effect**: run the thing, and let something
+ * else in the graph produce what gets committed.
+ *
+ * ## Why a mode on the node rather than a second node kind or a boolean
+ *
+ * A boolean is the shape {@link WORKFLOW_PREDICATE_KINDS} argues against one
+ * level down, and for the reason it gives: a `plain?: boolean` beside a future
+ * third wire format is two optional flags whose combinations nobody defined, and
+ * every reader invents its own rule for which wins. A closed list with an
+ * exhaustiveness guard ({@link unreachableCallMode}) makes a third format a
+ * compile error naming the files that have to answer for it.
+ *
+ * A second node *kind* was the other candidate and it is too big. The kind list
+ * is deliberately small and every entry earns it by doing something no wiring
+ * can express (see {@link WORKFLOW_NODE_KINDS}). A plain call does the same
+ * thing a call does at the level the graph reasons about — it hands this
+ * position to a workflow somebody else registered, pinned by name and version.
+ * What differs is the payload. Splitting the kind would duplicate `callName`,
+ * `callVersion`, `config`, the pin check, the picker, the plan entry and the
+ * canvas node for a difference of one field, and every place that today writes
+ * `node.kind === 'call'` would have to remember to write both — which is the
+ * hand-maintained list going quiet that {@link NODE_KIND_IS_REUSABLE} exists to
+ * stop.
+ */
+exports.WORKFLOW_CALL_MODES = [
+    /**
+     * The child is handed a {@link WorkflowCallEnvelope}: the catalog's metadata
+     * under `catalog`, the author's parameters under `input`. The callee can stage
+     * rows back for the graph, and it has to have been written for this catalog.
+     */
+    'envelope',
+    /**
+     * The child is handed {@link WorkflowCallNode.config} verbatim, with nothing
+     * added and nothing wrapped. The callee needs to know nothing about the
+     * catalog — and cannot return rows to it.
+     */
+    'plain',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowCallMode(value) {
+    return exports.WORKFLOW_CALL_MODES.some((mode) => mode === value);
+}
+/**
+ * {@link unreachableNodeKind}, one level down, and for the identical reason.
+ *
+ * Every branch over {@link WorkflowCallMode} ends here, so a third wire format
+ * added to the list without a rule for building its payload, hashing it,
+ * validating it or reading its answer is a type error naming the file. It throws
+ * as well, because a mode arrives as JSON out of a column and a build older than
+ * the data is a thing that happens.
+ */
+function unreachableCallMode(mode, where) {
+    throw new Error(`${where} has no rule for the call mode ${JSON.stringify(mode)}. It was added to WORKFLOW_CALL_MODES without teaching this code what to put on the wire for it, and guessing would send a workflow a payload nobody authored.`);
+}
+/**
+ * The mode this call node runs in, with the default applied once.
+ *
+ * Absent means `'envelope'` — that is what every node stored before the field
+ * existed is, and reading it as anything else would silently change what a
+ * deployment's graphs already do. One function so that the store, the runner,
+ * the hash and the canvas cannot each carry their own `?? 'envelope'` and have
+ * one of them drift.
+ */
+function workflowCallMode(node) {
+    return node.callMode ?? 'envelope';
+}
 /**
  * The kinds of test an {@link WorkflowIfNode} can make.
  *
@@ -977,6 +1139,44 @@ function describeVersionPin(version, subject) {
         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.
  *
@@ -1128,6 +1328,18 @@ exports.WORKFLOW_CALL_CONTRACT = 1;
  * schema for a workflow's output anywhere in the durable contract, and no way
  * to reach one if there were. So the check is here, at the one moment the
  * answer exists, and it names what it saw.
+ *
+ * ## Not called at all for a plain call, which is a decision and not an omission
+ *
+ * A plain call is handed no run id and no node id, so its callee could not have
+ * staged anything under `(runId, nodeId, batch)` even if it wanted to. Running
+ * this over its answer would be worse than pointless in both directions: a
+ * callee that happens to return `{batches, rowCount}` meaning something else
+ * entirely would have this graph go and read a stage that does not exist, and a
+ * callee returning one of the two would fail the node over a key it was never
+ * told about. So the plain path reports zero rows unconditionally and reads
+ * nothing — see `WorkflowRunnerService.callOutput`, which is where that is
+ * enforced rather than merely intended.
  */
 function readWorkflowCallOutput(value) {
     if (typeof value !== 'object' || value === null)
@@ -1182,6 +1394,13 @@ exports.WORKFLOW_ISSUE_CODES = [
     'dead-end',
     'transform-not-named',
     'call-not-named',
+    /**
+     * A plain call wired into something. See {@link WORKFLOW_CALL_MODES}: a plain
+     * call is told no run id and no node id, so it has nowhere to stage rows and
+     * always passes on none — and every node that can sit downstream of a call
+     * consumes rows and nothing else.
+     */
+    'call-plain-has-output',
     'if-not-named',
     'if-threshold-invalid',
     'if-needs-one-input',
@@ -1238,11 +1457,17 @@ function validateWorkflow(graph) {
         return issues;
     const { outgoing, incoming } = buildAdjacency(nodes, edges);
     const originators = nodes.filter(originatesRows);
+    // Deliberately a *different* set from `originators` — see `runsWithoutInput`.
+    const roots = nodes.filter(runsWithoutInput);
     const sinks = nodes.filter((node) => node.kind === 'sink');
     checkNodeWiring(nodes, incoming, outgoing, issues);
     checkEndpoints(originators, sinks, issues);
     checkBranches(edges, byId, issues);
-    checkFilterNarrowing({ nodes, edges }, originators, outgoing, issues);
+    checkPlainCallOutputs(nodes, outgoing, byId, issues);
+    // `roots` rather than `originators`, because this walks the graph forwards to
+    // find which sinks a filter can narrow and a plain call is a perfectly
+    // ordinary ancestor of nothing at all — it just never contributes rows.
+    checkFilterNarrowing({ nodes, edges }, roots, outgoing, issues);
     const looped = findCycle(nodes, incoming, outgoing);
     if (looped) {
         issues.push({
@@ -1254,27 +1479,127 @@ function validateWorkflow(graph) {
         // only unreachable *because* of the cycle, which points at the wrong boxes.
         return issues;
     }
-    checkReachability(nodes, originators, sinks, incoming, outgoing, issues);
+    checkReachability(nodes, roots, sinks, incoming, outgoing, issues);
     return issues;
 }
+/**
+ * A plain call may not feed anything, and this is where that is refused.
+ *
+ * ## The rule, stated once
+ *
+ * **A call node in `plain` mode must have no outbound edge.** Not "must not feed
+ * a sink", not "must not be the only thing feeding a sink" — no outbound edge at
+ * all, and the reason it collapses that far is that there is no weaker version
+ * of it that means anything. Every node kind that can sit downstream of a call —
+ * transform, if, filter, sink — consumes rows and *only* rows. There is no
+ * ordering-only wire in this model. So "a plain call with downstream nodes
+ * expecting rows" and "a plain call with an outbound edge" are the same set.
+ *
+ * ## How it lands against the rest of the validator
+ *
+ * Three rules had to move for this one to be statable, and each moved in a way
+ * that is narrower than it looks:
+ *
+ * - **`no-source`.** A plain call is no longer something that "reads": see
+ *   {@link originatesRows}. Without that, a graph of `plain call → sink` would
+ *   have passed the check that a graph has something producing rows, and then
+ *   committed an empty snapshot over whatever was live. It is refused here
+ *   first, and would be refused by `no-source` even if this check were deleted.
+ * - **`dead-end` — every path reaches the sink.** A plain call reaches no sink
+ *   by construction, so it is exempt, and the exemption is exactly one node
+ *   wide: nothing can be *behind* a plain call, because a plain call has no
+ *   outbound edge, so no other node's route to the sink can run through one.
+ *   The message `dead-end` carries is "it would be computed and thrown away",
+ *   and that is precisely what a plain call is not — its effect is the point,
+ *   and it has already happened by the time the sink commits.
+ * - **the one-sink rule.** Untouched. A graph still needs a sink and still needs
+ *   something that originates rows, and a plain call is now neither, so plain
+ *   calls cannot be a graph on their own — the rows come from a source or from
+ *   an envelope call, exactly as before.
+ *
+ * What a legal plain call looks like, then: `source → sink` with `source →
+ * plainCall` beside it — the effect runs after the source and the load commits
+ * the source's rows — or a plain call with nothing wired to it at all, which
+ * runs at some point in the topological order and is reported like any other
+ * node. Wiring a source into a plain call that is the source's *only* outbound
+ * edge is still refused, by `dead-end`, pointed at the source: those rows really
+ * would be fetched and dropped.
+ */
+function checkPlainCallOutputs(nodes, outgoing, byId, issues) {
+    for (const node of nodes) {
+        if (node.kind !== 'call' || workflowCallMode(node) !== 'plain')
+            continue;
+        const fed = outgoing.get(node.id) ?? [];
+        if (fed.length === 0)
+            continue;
+        issues.push({
+            code: 'call-plain-has-output',
+            nodeIds: [node.id, ...fed],
+            message: `Call node "${node.name}" (${node.id}) is a plain call and is wired into ${listNodes(fed, byId)}, which cannot work. A plain call sends this node's parameters to ${node.callName || 'the workflow it calls'} verbatim and nothing else — no run id and no node id — so the workflow it calls is told no key to write rows under and this node always passes on zero. Everything downstream would run on an empty input and the load would commit an empty snapshot without anything failing. Unwire it: a plain call is run for its effect, and something else in this graph produces what gets committed. If the workflow you are calling is meant to produce rows for this graph, it needs the envelope instead, which is what tells it where to put them.`,
+        });
+    }
+}
+/** `"a" (n1) and "b" (n2)`, for a message that has to name several boxes. */
+function listNodes(ids, byId) {
+    return ids
+        .map((id) => {
+        const node = byId.get(id);
+        return node ? `"${node.name}" (${id})` : `"${id}"`;
+    })
+        .join(' and ');
+}
 /**
  * Whether a node can produce rows without anything wired into it.
  *
- * A source obviously can. A **call** node can too, and this is the one rule the
- * `call` kind changes rather than extends: the workflow it hands off to may
- * itself read from a system, so a graph of `call → sink` is a real pipeline and
- * refusing it for having "no source" would be false. What is not weakened is
+ * A source obviously can. An **envelope call** node can too, and this is the one
+ * rule the `call` kind changes rather than extends: the workflow it hands off to
+ * may itself read from a system, so a graph of `call → sink` is a real pipeline
+ * and refusing it for having "no source" would be false. What is not weakened is
  * that a graph still needs *something* that originates rows and *something*
  * that commits them — a graph of transforms alone is still refused.
  *
- * Every call node counts, not only the ones with no inbound edge, and that is
- * the conservative direction: it makes this the root set for reachability too,
- * so a mid-graph call node cannot make everything downstream of it look
- * unreachable when its own upstream is fine.
+ * A **plain** call is not one of them, and that is the load-bearing half of this
+ * function now. A plain call is told no run id and no node id, so it has no key
+ * to stage rows under and cannot produce any — see {@link WORKFLOW_CALL_MODES}.
+ * Counting it here would let `plain call → sink` past `no-source` and commit an
+ * empty snapshot over whatever was live, which is the exact silence this file is
+ * arranged against.
+ *
+ * ## This used to be the reachability root set as well, and no longer is
+ *
+ * It said so, and the reason it gave was that it made the root set conservative.
+ * The plain mode splits the two questions, because the answers genuinely differ:
+ * a plain call **runs** with nothing wired into it (so it is a root, and calling
+ * it unreachable would be false — it would run) and **produces nothing** (so it
+ * is not something that reads). One function answering both would have to be
+ * wrong about one of them. See {@link runsWithoutInput} for the other half.
  */
 function originatesRows(node) {
+    if (node.kind === 'source')
+        return true;
+    return node.kind === 'call' && workflowCallMode(node) === 'envelope';
+}
+/**
+ * Whether a node runs whether or not anything is wired into it.
+ *
+ * The root set for reachability, which used to be {@link originatesRows} and is
+ * now its own question — see the note there. Every call node is one of these,
+ * both modes: a call with no inbound edge sits at in-degree zero in the
+ * topological order and is dispatched like anything else, so reporting it as
+ * "not reachable from any source, so it would never run" would be a message that
+ * is simply untrue.
+ *
+ * Every call node rather than only the unwired ones, for the reason the old
+ * function gave: it keeps a mid-graph call node from making everything
+ * downstream of it look unreachable when its own upstream is fine.
+ */
+function runsWithoutInput(node) {
     return node.kind === 'source' || node.kind === 'call';
 }
+/** Whether this node is a call that can never hand rows back to the graph. */
+function isPlainCall(node) {
+    return node.kind === 'call' && workflowCallMode(node) === 'plain';
+}
 /**
  * Index the nodes by id, reporting the ids that cannot be used as one.
  *
@@ -1811,12 +2136,17 @@ function peelTails(leftover, outgoing) {
     }
     return leftover;
 }
-/** Nodes that nothing reading reaches, and nodes that reach no sink. */
-function checkReachability(nodes, originators, sinks, incoming, outgoing, issues) {
-    const reachableFromSources = walk(originators.map((node) => node.id), outgoing);
+/**
+ * Nodes that nothing reading reaches, and nodes that reach no sink.
+ *
+ * `roots` is {@link runsWithoutInput} and not {@link originatesRows}: this asks
+ * what would *run*, and a plain call runs whether anything feeds it or not.
+ */
+function checkReachability(nodes, roots, sinks, incoming, outgoing, issues) {
+    const reachableFromSources = walk(roots.map((node) => node.id), outgoing);
     const reachesASink = walk(sinks.map((sink) => sink.id), incoming);
     for (const node of nodes) {
-        if (originators.length > 0 && !reachableFromSources.has(node.id)) {
+        if (roots.length > 0 && !reachableFromSources.has(node.id)) {
             issues.push({
                 code: 'unreachable',
                 nodeIds: [node.id],
@@ -1824,6 +2154,15 @@ function checkReachability(nodes, originators, sinks, incoming, outgoing, issues
             });
             continue;
         }
+        // The one exemption the plain mode buys, and it is exactly one node wide.
+        // A plain call reaches no sink by construction — `call-plain-has-output`
+        // refuses it an outbound edge — so `dead-end` would fire on every one of
+        // them, with a message ("it would be computed and thrown away") that is
+        // false about it: the effect it was run for has happened. Nothing can hide
+        // behind this, because nothing can be downstream of a plain call, so no
+        // other node's route to the sink can run through one.
+        if (isPlainCall(node))
+            continue;
         if (sinks.length > 0 && !reachesASink.has(node.id)) {
             issues.push({
                 code: 'dead-end',
@@ -2059,6 +2398,13 @@ function canonicalNode(node) {
             node.callName,
             node.callVersion,
             sortedEntries(node.config),
+            // Appended only for the non-default mode, exactly as `edge.branch` above
+            // is appended only when there is a label. Every call node in every
+            // deployment today is an envelope call — whether it says so or says
+            // nothing — so every one of them hashes to the string it always did and
+            // no stored graph is renumbered by picking up this release. See
+            // `canonicalCallMode` for why the two spellings must fold together.
+            ...canonicalCallMode(workflowCallMode(node)),
         ]);
     }
     if (node.kind === 'if') {
@@ -2103,6 +2449,27 @@ function canonicalNode(node) {
  * no version bump and no diff — which is precisely the silence this feature was
  * built to end.
  */
+/**
+ * The call mode, as zero or one trailing hash component.
+ *
+ * Zero for `envelope`, and that is the opposite choice from {@link
+ * canonicalReuse} beside it — for the opposite reason. There, absent and present
+ * mean genuinely different things ("follow the latest" against "pinned to v1"),
+ * so they must hash differently. Here absent and `'envelope'` are one behaviour
+ * spelled two ways: a node that says `callMode: 'envelope'` puts precisely the
+ * same bytes on the wire as a node that says nothing. A fingerprint that told
+ * them apart would report an edit when a canvas normalised the field, which is
+ * the cosmetic version bump {@link workflowGraphHash} exists to not do.
+ *
+ * `plain` earns its component, because it changes what the child receives.
+ */
+function canonicalCallMode(mode) {
+    if (mode === 'envelope')
+        return [];
+    if (mode === 'plain')
+        return ['plain'];
+    return unreachableCallMode(mode, 'workflowGraphHash');
+}
 function canonicalReuse(node) {
     if (node.useId === undefined)
         return [];
@@ -2211,18 +2578,8 @@ function isWorkflowNode(value) {
     if (kind === 'sink') {
         return typeof Reflect.get(value, 'targetType') === 'string';
     }
-    if (kind === 'call') {
-        // Both strings, and the config object, exactly as strictly as a source's:
-        // a stored call node missing its version is a node that would run whatever
-        // is registered today, which is the failure the pin exists to remove — and
-        // a graph that half-narrows is a load that runs nine nodes of ten.
-        const config = Reflect.get(value, 'config');
-        return (typeof Reflect.get(value, 'callName') === 'string' &&
-            typeof Reflect.get(value, 'callVersion') === 'string' &&
-            typeof config === 'object' &&
-            config !== null &&
-            !Array.isArray(config));
-    }
+    if (kind === 'call')
+        return isCallNodeShape(value);
     if (kind === 'if') {
         // The predicate in full, refused rather than defaulted: a gate read back
         // without a test it recognises would have to invent one, and inventing one
@@ -2241,6 +2598,34 @@ function isWorkflowNode(value) {
     }
     return isWorkflowNodeKindUnhandled(kind);
 }
+/**
+ * Everything a `call` node carries, checked as strictly as a source's.
+ *
+ * Its own function rather than a branch of {@link isWorkflowNode}, which the
+ * complexity bound will not hold any more of — and the split is where it should
+ * be, because this is the kind with the most to check.
+ *
+ * A stored call node missing its version is a node that would run whatever is
+ * registered today, which is the failure the pin exists to remove, and a graph
+ * that half-narrows is a load that runs nine nodes of ten. A `callMode` that is
+ * present and unrecognised is refused rather than dropped, for the reason an
+ * unrecognised `edge.branch` is: reading it back as the default would turn a
+ * plain call into an envelope call silently, and the callee would be handed a
+ * payload nobody authored. Absent is accepted and always will be — it is what
+ * every call node written before the field existed carries, and it means the
+ * envelope, which is what those nodes have always sent.
+ */
+function isCallNodeShape(value) {
+    const callMode = Reflect.get(value, 'callMode');
+    if (callMode !== undefined && !isWorkflowCallMode(callMode))
+        return false;
+    const config = Reflect.get(value, 'config');
+    return (typeof Reflect.get(value, 'callName') === 'string' &&
+        typeof Reflect.get(value, 'callVersion') === 'string' &&
+        typeof config === 'object' &&
+        config !== null &&
+        !Array.isArray(config));
+}
 /**
  * Whether a stored `narrows` is one this build can read.
  *
@@ -2352,6 +2737,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.
  *

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, 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';
+export type { CatalogConnection, CatalogConnector, ConnectionCheck, CatalogTransform, CatalogWorkflow, CatalogWorkflowCapabilities, CatalogWorkflowRelease, ConnectorKind, ConnectorRun, TransformLanguage, TransformResult, CallableWorkflowRef, WorkflowBranchLabel, WorkflowCallEnvelope, WorkflowCallMode, 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, SourceFormat, VersionPinCopy, } from './catalog.pipeline';
+export { CONNECTOR_KINDS, isConnectorKind, isSourceFormat, isTransformLanguage, SOURCE_FORMATS, isWorkflowEdge, isWorkflowNode, liveWorkflowVersion, REDACTED_SECRET, TRANSFORM_LANGUAGES, readWorkflowCallOutput, WORKFLOW_CALL_CONTRACT, WORKFLOW_CALL_MODES, isWorkflowCallMode, unreachableCallMode, workflowCallMode, 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.
  *