@dudousxd/nestjs-catalog 0.17.0 → 0.19.0

package/dist/catalog.pipeline.d.ts

@@ -7,7 +7,7 @@
  * schedules, retries and checkpoints, and writing a second one would mean two
  * systems each believing they decide when a load runs.
  */
-import type { CatalogRevision } from './catalog.workspace';
+import { type CatalogRevision } from './catalog.workspace';
 /**
  * Where a connector pulls from.
  *
@@ -903,7 +903,7 @@ export declare function workflowRowY(row: number): number;
  * vocabularies would let them disagree. Credentials stay out of the catalog
  * here exactly as they do everywhere else.
  */
-export interface WorkflowSourceNode extends WorkflowNodeBase {
+export interface WorkflowSourceNode extends WorkflowNodeBase, ReusableNodeRef {
     kind: 'source';
     /** Named `sourceKind` rather than `kind`, which the union already uses. */
     sourceKind: ConnectorKind;
@@ -925,6 +925,56 @@ export interface WorkflowTransformNode extends WorkflowNodeBase {
      * logic used at three points in a graph is versioned once and fixed once.
      */
     transformId: string;
+    /**
+     * Which version of that code to run. Absent follows the latest.
+     *
+     * ## The claim this field exists to make true
+     *
+     * The line above says a shared transform is "versioned once and fixed once",
+     * and until this field there was nothing here to fix it *to*. A transform node
+     * named a `transformId` and nothing else, `runTransform` resolved it with
+     * `getTransform`, and `getTransform` answers with whatever is in the row
+     * today. So editing a transform changed every graph that referenced it, at
+     * once, with nothing in anybody else's diff and nothing in their run history
+     * to explain the change — the graph's fingerprint does not move (see
+     * `workflowGraphHash`, which excludes the transform's version on purpose and
+     * still does) so there is not even a new graph version to look at.
+     *
+     * That was survivable only because almost nothing was shared. It stops being
+     * survivable the moment reusable nodes make sharing the point, which is why
+     * this landed with them rather than after them.
+     *
+     * The precedent is {@link WorkflowCallNode.callVersion}, whose docblock makes
+     * the same argument about somebody else's workflow: the version is authored,
+     * and a run that would have used a different one is refused rather than
+     * quietly run. This is that rule pointed at code stored in the same database.
+     *
+     * ## Why absent is allowed to mean "latest" rather than being backfilled
+     *
+     * Because that is what every graph already in a deployment means, exactly, and
+     * a backfill would be a behaviour change dressed as a migration. Pinning the
+     * live version at upgrade time freezes graphs whose authors have been relying
+     * on edits reaching them; pinning nothing but *refusing* an unpinned node
+     * stops every scheduled load on the deployment. Both are an upgrade that
+     * changes what runs, and neither is a decision this package gets to make for
+     * somebody. So absent keeps meaning precisely what it has always meant, and
+     * the repair is that following is now a **stated** position with a pinned
+     * alternative beside it, rather than the only position and an unstated one.
+     *
+     * What does change is that it is no longer silent: `describeTransformPin`
+     * turns either state into a sentence a screen can render, so "this follows
+     * whatever that code becomes" is something the author is told rather than
+     * something they find out.
+     *
+     * ## What a pin costs
+     *
+     * A pinned version is resolved out of `catalog_revision`, which is bounded per
+     * subject (`CATALOG_REVISION_LIMIT`). A pin to a version that has been evicted
+     * cannot be honoured, and the run fails saying so rather than falling back to
+     * the latest — a pin nobody could check is not a pin, which is the sentence
+     * `WorkflowRunSteps.checkCall` already stands on.
+     */
+    transformVersion?: number;
 }
 /**
  * Writes into an object type and commits.
@@ -937,9 +987,17 @@ export interface WorkflowTransformNode extends WorkflowNodeBase {
  * convenience that two workflows already provide. Branching inside the graph
  * stays fully supported; every path simply has to arrive here.
  */
-export interface WorkflowSinkNode extends WorkflowNodeBase {
+export interface WorkflowSinkNode extends WorkflowNodeBase, ReusableNodeRef {
     kind: 'sink';
-    /** Which object type the rows become. */
+    /**
+     * Which object type the rows become.
+     *
+     * Stays on the node even when the node is an instance of a reusable one, and
+     * that is the one field a reusable body may **not** move under a graph. See
+     * {@link ReusableNodeRef} — the write grants a graph was checked against are
+     * checked against this string, so a reusable sink that could repoint it would
+     * be a way to write a type the author was never granted.
+     */
     targetType: string;
     /**
      * Whether the commit replaces the dataset or merges into it. Exactly the
@@ -1586,6 +1644,304 @@ export interface WorkflowFilterNode extends WorkflowNodeBase {
  * a `transformId` and nothing catches it.
  */
 export type WorkflowNode = WorkflowSourceNode | WorkflowTransformNode | WorkflowSinkNode | WorkflowCallNode | WorkflowIfNode | WorkflowFilterNode;
+/**
+ * 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}.
+ */
+export declare const REUSABLE_NODE_KINDS: readonly ["source", "sink"];
+export type ReusableNodeKind = (typeof REUSABLE_NODE_KINDS)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isReusableNodeKind(value: unknown): value is ReusableNodeKind;
+/**
+ * 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.
+ */
+export declare const NODE_KIND_IS_REUSABLE: {
+    readonly source: true;
+    readonly transform: false;
+    readonly sink: true;
+    readonly call: false;
+    readonly if: false;
+    readonly filter: false;
+};
+/** Whether this kind can be saved as a reusable node. Reads {@link NODE_KIND_IS_REUSABLE}. */
+export declare function nodeKindIsReusable(kind: WorkflowNodeKind): boolean;
+/**
+ * What a node carries when it is an instance of a reusable one.
+ *
+ * ## By reference, and that is the whole feature
+ *
+ * The cheap version of "save this node" copies its fields into the next graph
+ * and forgets where they came from. It is cheaper in every way except the one
+ * that was asked for: "quantos workflows tão usando quais nós" is unanswerable
+ * about a copy, because after the copy there is nothing left that says the two
+ * nodes are the same node. So the id stays on the node, `GET
+ * reusable-nodes/:id/workflows` counts by it, and the count is exact rather than
+ * a guess at which configurations look alike.
+ *
+ * ## The fields stay on the node as well, and are not the authority
+ *
+ * A source node that names a reusable node still carries its own `sourceKind`,
+ * `config` and the rest. That is a **cache**, not a copy — the identical
+ * arrangement `toGraph` already documents for a source that names a connector:
+ * the fields are kept so that `validateWorkflow` stays pure and the canvas can
+ * draw the node without a round trip, and execution re-reads the stored object,
+ * so an edit takes effect on the next run.
+ *
+ * ## Which is exactly why {@link version} exists
+ *
+ * "An edit takes effect on the next run" is the useful behaviour and the
+ * dangerous one, and which of the two it is depends on whether the person
+ * editing knows who else is downstream. So the reference states its position:
+ *
+ * - **absent** — follows the latest. What a connector reference has always
+ *   meant, and the right default for "the warehouse pull" that four graphs
+ *   share and all four want fixed at once.
+ * - **present** — pinned. The reusable node may move on and this graph does not,
+ *   until somebody edits *this* graph, which is a new version of it with a diff
+ *   to read.
+ *
+ * Both are in the graph fingerprint, so changing position is an edit; neither is
+ * silent, which was the whole complaint. This is the same rule
+ * {@link WorkflowTransformNode.transformVersion} states for transforms, and it
+ * is stated twice on purpose rather than shared: they are two different stored
+ * objects and a reader arriving at either should not have to find the other.
+ */
+export interface ReusableNodeRef {
+    /**
+     * The reusable node this is an instance of, or absent for a node configured
+     * in place. Both remain first-class, indefinitely: a one-off source is not a
+     * failure to reuse something.
+     */
+    useId?: string;
+    /** The pinned version of that reusable node. Absent follows the latest. */
+    useVersion?: number;
+}
+/**
+ * The part of a source node that is worth saving under a name.
+ *
+ * Everything a source needs to read, and nothing that belongs to the graph it
+ * sits in. Absent here, on purpose: `id`, which has to be unique within one
+ * graph and is also a durable step name, and `position`, which is where somebody
+ * dragged the box on one canvas.
+ *
+ * `name` is absent too, and that is the less obvious one. A reusable node has a
+ * name — it is how "flip db sink" is a thing anybody can ask for — but it lives
+ * on {@link CatalogReusableNode} rather than in the body, because a graph is
+ * allowed to call its instance something else. Folding the name in would rename
+ * every node in every graph the moment somebody tidied up the library's naming,
+ * and a node's name is documented as cosmetic precisely so that it is nobody
+ * else's business.
+ */
+export interface ReusableSourceBody {
+    kind: 'source';
+    sourceKind: ConnectorKind;
+    connectionId?: string;
+    config: Record<string, unknown>;
+    secretEnvVar?: string;
+    mode?: 'full' | 'incremental';
+}
+/**
+ * The part of a sink node that is worth saving under a name.
+ *
+ * `targetType` is in here, so "the Mvr full reload" is a thing that can be named
+ * — and it is also the field {@link applyReusableNode} refuses to move under a
+ * graph that already committed to a different one. Both are true at once and
+ * they are not in tension: a graph adopting this body *takes* the type at the
+ * moment it is saved, and is grant-checked for it then. What may not happen is
+ * the type changing afterwards, under a graph whose author is not looking, into
+ * one they were never granted.
+ */
+export interface ReusableSinkBody {
+    kind: 'sink';
+    targetType: string;
+    mode?: 'full' | 'incremental';
+}
+export type ReusableNodeBody = ReusableSourceBody | ReusableSinkBody;
+/**
+ * {@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.
+ */
+export declare function unreachableReusableNodeKind(body: never, where: string): never;
+/**
+ * A node body saved once, under a name, and used from several graphs.
+ *
+ * Versioned exactly as a {@link CatalogTransform} is, and archived in the same
+ * `catalog_revision` table under its own subject — one table, one retention
+ * rule, which is the argument `RevisionRow` already makes for holding transforms
+ * and saved queries together. That is what makes
+ * {@link ReusableNodeRef.version} resolvable rather than merely a number: a
+ * graph pinned to v2 can still be handed v2's body after v3 exists.
+ *
+ * There is no library screen and there is deliberately not going to be one. A
+ * reusable node is offered where a node is added and its usage count is shown on
+ * the node itself, because the number changes a decision exactly at the moment
+ * somebody is about to change something four other graphs depend on — which is
+ * not a moment they spend on a listing page.
+ */
+export interface CatalogReusableNode {
+    id: string;
+    /**
+     * What people ask for it by — "flip db sink". Unique across reusable nodes,
+     * enforced in the store, because two of them called the same thing is a
+     * picker that cannot be used.
+     */
+    name: string;
+    description?: string;
+    /** Which node kind this stands for. Redundant with `body.kind` and indexed. */
+    kind: ReusableNodeKind;
+    body: ReusableNodeBody;
+    /**
+     * Counts saves that changed the **body**, exactly as a transform's counts
+     * saves that changed the code: renaming a reusable node is not a new version
+     * of it, and inflating the number would make a pin to it meaningless.
+     */
+    version: number;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * How many graphs use a reusable node, and which.
+ *
+ * Shaped after `GET connections/:id/workflows`, which answers the same question
+ * for a connection, because an operator asking either is about to do the same
+ * thing: change something and want to know who is downstream. A count on its own
+ * would be a number to be alarmed by; the list is what makes it actionable.
+ */
+export interface CatalogReusableNodeUse {
+    workflowId: string;
+    workflowName: string;
+    status: WorkflowStatus;
+    /** The node within that graph, and the position its reference states. */
+    nodeId: string;
+    nodeName: string;
+    /** The pinned version, or absent for a reference that follows the latest. */
+    pinnedVersion?: number;
+}
+/**
+ * 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.
+ */
+export declare function applyReusableNode(node: WorkflowNode, body: ReusableNodeBody): WorkflowNode;
+/** Whether a stored value is a reusable body this build can execute. */
+export declare function isReusableNodeBody(value: unknown): value is ReusableNodeBody;
+/**
+ * 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.
+ */
+export declare function reusableNodeBodyOf(node: WorkflowNode): ReusableNodeBody | undefined;
+/**
+ * What a node's version discipline is, as a sentence a screen can render.
+ *
+ * Here rather than in the console for the reason `describeDurability`'s siblings
+ * are: a screen that worked out its own wording would eventually describe
+ * "follows the latest" as though it were a pin, which is the misunderstanding
+ * this whole field exists to remove. One sentence, one place, and the console
+ * renders it.
+ */
+export interface VersionPinCopy {
+    pinned: boolean;
+    label: string;
+    detail: string;
+}
+export declare function describeVersionPin(version: number | undefined, subject: string): VersionPinCopy;
+/**
+ * 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.
+ */
+export declare function describeLiveVersion(workflow: CatalogWorkflow): VersionPinCopy;
 /**
  * Which side of an {@link WorkflowIfNode} a wire leaves by.
  *
@@ -1729,6 +2085,51 @@ export interface CatalogWorkflow {
     version: number;
     /** Fingerprint of the graph at this version. See {@link workflowGraphHash}. */
     graphHash: string;
+    /**
+     * Which released version a run of this graph gets when nobody names one.
+     *
+     * **Absent means follow the latest**, which is what every graph in every
+     * deployment does today and what every existing graph keeps doing until
+     * somebody points this at something. Absence is a real answer rather than a
+     * state waiting to be filled in — the same stance {@link WorkflowCallNode}
+     * takes from the other side, where a call that named no version would run
+     * whichever one is registered when the load happens.
+     *
+     * Present, it names a {@link CatalogWorkflowRelease} — and from that moment
+     * **editing this graph stops being deploying it**. A save bumps
+     * {@link version} as it always did; the next scheduled window still runs the
+     * released version this names, because a cron tick that executed whatever the
+     * canvas happened to hold is a deploy nobody performed. Moving it is
+     * {@link CatalogWorkflowReleaseStore.setLiveWorkflowVersion}, which is a
+     * deliberate act by a named principal, and moving it *backwards* is the whole
+     * of rollback.
+     *
+     * ## Why this is a column here and not a row in an environments table
+     *
+     * Because the row is already per-environment. Environments in this catalog are
+     * physically isolated — one database each, see `catalog.environment.ts` — so
+     * this `catalog_workflow` row exists once per environment already, and a
+     * second dimension keyed on the environment id would be a table whose every
+     * query filtered on a constant. The environment is the connection, and it has
+     * been since environments were added.
+     *
+     * That is also why the field is not called `productionVersion`. "Production"
+     * in this catalog is the *name of an environment* — see `CatalogEnvironment`
+     * in `catalog.environment.ts` — so a column called that, on a row which
+     * already lives inside exactly one environment, would read as naming a
+     * different one.
+     *
+     * ## Why it does not cross a promotion
+     *
+     * `planPromotion` is explicit that version numbers do not cross: a version
+     * counts edits made in the environment it lives in, so dev's v7 and
+     * production's v7 are unrelated numbers. A pointer *to* a version inherits
+     * that argument whole — carrying this field would point the target's live
+     * pointer at whatever its own seventh edit happened to be. So
+     * `PromotableWorkflow` does not carry it, and a promoted graph arrives
+     * following the latest, exactly as a newly created one does.
+     */
+    liveVersion?: number;
     /**
      * The type the sink writes.
      *
@@ -2088,7 +2489,7 @@ export interface CallableWorkflowBlock {
 }
 export declare function callableWorkflowBlock(ref: CallableWorkflowRef): CallableWorkflowBlock | undefined;
 /** Every way a graph can be refused. Exported so a canvas can key off the code. */
-export declare const WORKFLOW_ISSUE_CODES: readonly ["empty", "invalid-node-id", "duplicate-node-id", "edge-endpoint-missing", "self-edge", "duplicate-edge", "cycle", "no-source", "source-has-input", "no-sink", "duplicate-sink-type", "sink-has-output", "unreachable", "dead-end", "transform-not-named", "call-not-named", "if-not-named", "if-threshold-invalid", "if-needs-one-input", "branch-not-labelled", "branch-on-plain-edge", "filter-predicate-invalid", "filter-narrows-unacknowledged", "filter-narrows-nothing"];
+export declare const WORKFLOW_ISSUE_CODES: readonly ["empty", "invalid-node-id", "duplicate-node-id", "edge-endpoint-missing", "self-edge", "duplicate-edge", "cycle", "no-source", "source-has-input", "no-sink", "duplicate-sink-type", "sink-has-output", "unreachable", "dead-end", "transform-not-named", "call-not-named", "if-not-named", "if-threshold-invalid", "if-needs-one-input", "branch-not-labelled", "branch-on-plain-edge", "filter-predicate-invalid", "filter-narrows-unacknowledged", "filter-narrows-nothing", "version-pin-invalid"];
 export type WorkflowIssueCode = (typeof WORKFLOW_ISSUE_CODES)[number];
 export interface WorkflowValidationIssue {
     code: WorkflowIssueCode;
@@ -2385,6 +2786,172 @@ export interface CatalogWorkflowStore {
         enabled?: boolean;
     }, changedBy: string): Promise<CatalogWorkflow>;
 }
+/**
+ * One version of a graph, kept exactly as it was, because somebody said so.
+ *
+ * ## The archive `CatalogWorkflow` argues against, and why this is not it
+ *
+ * {@link CatalogWorkflow} states plainly that a graph is not revisioned, and the
+ * decisive reason it gives is the counter: {@link CatalogWorkflow.version} is
+ * bumped on **draft** edits by design, so archiving one body per version would
+ * store every autosave of a canvas somebody is still dragging boxes around on —
+ * and under a bounded archive that noise would evict the versions that actually
+ * ran. **That argument is correct and nothing here weakens it.** It is an
+ * argument against archiving *saves*, and this archives *releases*: a release is
+ * minted only by `releaseWorkflow`, which is a route a person presses, and a
+ * canvas autosave does not reach it. So the counter stays cheap to inflate, the
+ * archive stays keyed on a deliberate act, and the two now compose because they
+ * are counting different things.
+ *
+ * The second half of that docblock — that a graph is a structure and a line
+ * differ over serialised JSON would report a dragged box as a change — is also
+ * untouched. This is not a diff feature. It stores the graph so a version can be
+ * *run*, and diffing graphs remains a graph problem deserving a screen that
+ * draws one.
+ *
+ * ## Why not `catalog_revision`, which already archives versioned bodies
+ *
+ * Two reasons, and the second is the one that decides it.
+ *
+ * `CatalogRevision.body` is text a person typed — a transform's code, a saved
+ * query's SQL — and every route over it is built to render text. A graph is
+ * nodes and edges, and folding it into that column would put JSON nobody wrote
+ * in front of a differ built for source.
+ *
+ * The one that decides it is {@link CATALOG_REVISION_LIMIT}. That cap is right
+ * for code, for the reason its own docblock gives: revisions grow with how often
+ * somebody edits, which nobody meters. A release does not grow that way — it
+ * grows with how often somebody deliberately ships — and, crucially, a release
+ * is the thing a live pointer names. An eviction rule over this table could
+ * delete the graph that production is *currently running*, turning
+ * {@link CatalogWorkflow.liveVersion} into a pin nothing can honour and stopping
+ * a working pipeline on a retention policy. **So releases are never evicted.**
+ * That makes this an unbounded table, which this codebase is careful about — and
+ * it earns it on the same test `catalog_audit_event` and `catalog_connector_run`
+ * pass: one row per thing a person deliberately did, at a rate an operator can
+ * read off their own change process.
+ *
+ * ## Immutable, and there is no route that removes one
+ *
+ * Nothing edits a release and nothing deletes one. That is the strongest form of
+ * "refuse to delete the version that is live": there is no operation to refuse.
+ * The one exception is {@link CatalogWorkflowStore.deleteWorkflow}, which takes
+ * the graph, its connector and its whole run history — releases go with it,
+ * because nothing survives that could still name one. (The opposite call is made
+ * for a transform, whose revisions outlive it precisely *because* runs that ran
+ * them survive.)
+ */
+export interface CatalogWorkflowRelease {
+    /**
+     * `{workflowId}:{version}`, derived rather than random.
+     *
+     * The same construction `revisionKey` uses in the MikroORM store and for the
+     * same property: releasing the same version twice cannot append a second copy,
+     * because the second write would collide with the first rather than land
+     * beside it.
+     */
+    id: string;
+    workflowId: string;
+    /**
+     * The {@link CatalogWorkflow.version} this release IS.
+     *
+     * The same number, not a parallel sequence. A release sequence of its own was
+     * the alternative and it is worse in the one place it matters: a run records
+     * `workflowVersion`, so a second numbering would mean a run naming "v3" and an
+     * operator reading "release 3" could be two different graphs, which is exactly
+     * the ambiguity the edit counter was made cheap to avoid.
+     */
+    version: number;
+    /** Fingerprint of the graph as released. See {@link workflowGraphHash}. */
+    graphHash: string;
+    nodes: WorkflowNode[];
+    edges: WorkflowEdge[];
+    /** The type the sink committed at this version. */
+    targetType: string;
+    /** Whatever the releaser wanted to say about it. */
+    notes?: string;
+    releasedBy: string;
+    releasedAt: string;
+}
+/**
+ * Minting releases, and pointing at one.
+ *
+ * Its own interface mixed in optionally, for the reason {@link
+ * CatalogWorkflowStore} is: a store written against the previous shape must keep
+ * compiling, and "this deployment cannot hold releases" has to be a sentence a
+ * UI can say rather than a method missing at run time.
+ *
+ * The split from `CatalogWorkflowStore` is not only compatibility. These four
+ * are the only members in this file that can change *what a cron executes*
+ * without touching a graph, and keeping them behind their own predicate means a
+ * store can hold graphs without acquiring that power by accident.
+ */
+export interface CatalogWorkflowReleaseStore {
+    /**
+     * Freeze the graph as it currently stands, under its current version.
+     *
+     * **The only thing that mints one.** Not `saveWorkflow`, which is the autosave
+     * this whole feature exists to stop being a deploy; not `publishWorkflow`,
+     * which is idempotent and is called by a promotion apply — a release minted as
+     * a side effect of promoting configuration into an environment would be a
+     * release nobody in that environment chose.
+     *
+     * Refuses a draft, for the reason `WORKFLOW_STATUSES` already gives about what
+     * a connector may point at and what a promotion may carry: what gets shipped
+     * should be something a person declared finished.
+     *
+     * **Idempotent per version.** Releasing a graph whose current version is
+     * already released answers with the existing release rather than minting a
+     * second or overwriting its notes — the graph has not changed, so a second
+     * release would be a record of an event that did not happen, and re-attributing
+     * the first one would erase who actually shipped it.
+     */
+    releaseWorkflow(id: string, releasedBy: string, options?: {
+        notes?: string;
+    }): Promise<CatalogWorkflowRelease>;
+    /** Newest first. */
+    listWorkflowReleases(id: string): Promise<CatalogWorkflowRelease[]>;
+    /**
+     * The graph as it was at a released version, or `undefined`.
+     *
+     * `undefined` for a version that was never released as much as for a workflow
+     * that does not exist, and callers must treat the two the same way: **fail,
+     * never fall back to the latest.** Running the current graph because the named
+     * one could not be produced is precisely the substitution a pin is written
+     * down to prevent.
+     *
+     * Answers with a whole {@link CatalogWorkflow} rather than the bare release,
+     * because that is what a run needs: the released graph, carried on the row's
+     * present identity. The graph fields — nodes, edges, `targetType`,
+     * `graphHash`, `version` — come from the release. The operational ones —
+     * `name`, `status`, `schedule`, `enabled`, `liveVersion` — come from the row
+     * as it is now, because they are not part of what was released. A cron somebody
+     * changed this morning applies to the version that is live, not to whatever
+     * cron was on the row the day it was released.
+     */
+    getWorkflowAt(id: string, version: number): Promise<CatalogWorkflow | undefined>;
+    /**
+     * Point {@link CatalogWorkflow.liveVersion} at a released version — or clear it.
+     *
+     * One method for going live, for rolling back and for going back to following
+     * the latest, because they are one act with a different argument. Rollback in
+     * particular is not a separate mechanism to build and test: it is this call
+     * with a smaller number, and it works because the older graph is still stored.
+     *
+     * Refuses a version with no release behind it, naming what there is. A pointer
+     * accepted at a number nothing can produce would be a pipeline that stops at
+     * its next window, discovered by a load failing rather than by the person who
+     * typed it.
+     *
+     * `undefined` clears the pointer and takes the graph back to following the
+     * latest. Allowed rather than refused — it is the state every graph in every
+     * deployment is in, so refusing would strand anything that ever went live —
+     * and stated as a decision because it hands back exactly the hazard the
+     * pointer removes: from that moment, saving the graph changes what the next
+     * window runs.
+     */
+    setLiveWorkflowVersion(id: string, version: number | undefined, changedBy: string): Promise<CatalogWorkflow>;
+}
 /**
  * Where the rows between two nodes actually sit.
  *
@@ -2434,6 +3001,36 @@ export interface CatalogStageStore {
  * does, because a flag is a claim and a method is the thing itself.
  */
 export declare function supportsWorkflows(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogWorkflowStore;
+/**
+ * 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.
+ */
+export declare function supportsWorkflowReleases(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogWorkflowReleaseStore;
+/**
+ * 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.
+ */
+export declare function liveWorkflowVersion(workflow: CatalogWorkflow): number;
 /**
  * Whether this store keeps a transform's history.
  *
@@ -2441,6 +3038,34 @@ export declare function supportsWorkflows(store: CatalogPipelineStore): store is
  * flag is a claim and a method is the thing itself.
  */
 export declare function supportsTransformRevisions(store: CatalogPipelineStore): store is CatalogPipelineStore & Required<Pick<CatalogPipelineStore, 'listTransformRevisions'>>;
+/**
+ * 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.
+ */
+export declare function supportsTransformPins(store: CatalogPipelineStore): store is CatalogPipelineStore & Required<Pick<CatalogPipelineStore, 'getTransformAt'>>;
+/**
+ * The four reads and two writes a reusable node needs, as one derived type.
+ *
+ * `Required<Pick<...>>` rather than a second interface, which is the lesson
+ * {@link CatalogLoadExpectationStore} records: these are optional members OF the
+ * pipeline store, so writing them out again here would be a copy that can drift.
+ */
+export type CatalogReusableNodeStore = Required<Pick<CatalogPipelineStore, 'listReusableNodes' | 'getReusableNode' | 'getReusableNodeAt' | 'saveReusableNode' | 'deleteReusableNode' | 'reusableNodeUses'>>;
+/**
+ * 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.
+ */
+export declare function supportsReusableNodes(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogReusableNodeStore;
 export declare function supportsWorkflowStages(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogStageStore;
 /**
  * A store that really does hold operator-set expectations, all four members
@@ -2473,7 +3098,7 @@ export type CatalogLoadExpectationStore = Required<Pick<CatalogPipelineStore, 'l
  * an editor whose save has nowhere to go.
  */
 export declare function supportsLoadExpectations(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogLoadExpectationStore;
-export interface CatalogPipelineStore extends Partial<CatalogWorkflowStore>, Partial<CatalogStageStore> {
+export interface CatalogPipelineStore extends Partial<CatalogWorkflowStore>, Partial<CatalogWorkflowReleaseStore>, Partial<CatalogStageStore> {
     listConnectors(): Promise<CatalogConnector[]>;
     getConnector(id: string): Promise<CatalogConnector | undefined>;
     saveConnector(input: Omit<CatalogConnector, 'id' | 'createdAt' | 'updatedAt' | 'createdBy'> & {
@@ -2526,6 +3151,88 @@ export interface CatalogPipelineStore extends Partial<CatalogWorkflowStore>, Par
      * that bound costs.
      */
     listTransformRevisions?(id: string): Promise<CatalogRevision[]>;
+    /**
+     * The code at one particular version, which is what a pin resolves through.
+     *
+     * Separate from {@link listTransformRevisions} rather than left to a caller
+     * filtering that list, and the difference is the whole point: this is on the
+     * hot path of every pinned transform node of every run, and reading up to
+     * {@link CATALOG_REVISION_LIMIT} whole code bodies to keep one of them is a
+     * cost paid per node per run. It is also a different answer — the list falls
+     * back to a synthesised head for a subject that predates the revision table,
+     * and this must not, because "the only version we can produce is the current
+     * one" is exactly the case a pin needs to be told about rather than handed.
+     *
+     * `undefined` means the version cannot be produced: it predates the archive,
+     * or it has fallen off the far end of the per-subject cap. The runner turns
+     * that into a failed node rather than a fall-back to the latest, which is the
+     * same stand `WorkflowRunSteps.checkCall` takes — a pin nobody could check is
+     * not a pin.
+     *
+     * **Optional**, mixed in exactly as its neighbour above is and for the same
+     * reason. {@link supportsTransformPins} is how a caller asks; a store without
+     * it can still run graphs, and a graph with a pinned node is refused there
+     * with a sentence rather than by a method that is missing at run time.
+     */
+    getTransformAt?(id: string, version: number): Promise<CatalogTransform | undefined>;
+    /**
+     * Node bodies saved under a name and used from several graphs.
+     *
+     * **Optional**, mixed in for the reason every optional member here is: a store
+     * written against the previous shape of this interface still satisfies it, and
+     * a purely additive feature must not turn that into a compile error — or,
+     * worse, into a run-time discovery, since the `supports*` probes narrow
+     * structurally. {@link supportsReusableNodes} is how a caller asks.
+     *
+     * A deployment whose store implements none of these behaves exactly as it does
+     * today: every node is configured in place, which is what they all are.
+     */
+    listReusableNodes?(): Promise<CatalogReusableNode[]>;
+    getReusableNode?(id: string): Promise<CatalogReusableNode | undefined>;
+    /**
+     * The body at one particular version, for a reference that pinned one.
+     *
+     * The sibling of {@link getTransformAt}, with the same contract and the same
+     * `undefined`: a version the archive can no longer produce is reported as
+     * absent and never substituted with the latest.
+     */
+    getReusableNodeAt?(id: string, version: number): Promise<CatalogReusableNode | undefined>;
+    /**
+     * Bumps {@link CatalogReusableNode.version} when the **body** changed, and
+     * archives it, exactly as {@link saveTransform} does for code.
+     *
+     * Editing a reusable node that other graphs pin therefore creates a new
+     * version rather than refusing. Refusing was the other candidate and it is the
+     * wrong one: this is the only editor there is, so a refusal would strand
+     * whoever owns the node the moment anybody else pinned it, and would make
+     * pinning a way to take something hostage. Creating a version costs the pinned
+     * graphs nothing — they resolve through the archive and keep running the body
+     * they named — and what the editor gets instead of a refusal is the count of
+     * who is downstream, at the moment they are about to press save.
+     */
+    saveReusableNode?(input: Pick<CatalogReusableNode, 'name' | 'body'> & {
+        id?: string;
+        description?: string;
+    }, createdBy: string): Promise<CatalogReusableNode>;
+    /**
+     * Refuses while any graph still references it.
+     *
+     * The same refusal {@link deleteConnection} makes and for the same reason:
+     * deleting one out from under its graphs turns every one of them into a load
+     * that fails at run time, discovered on a schedule rather than at the moment
+     * somebody decided.
+     */
+    deleteReusableNode?(id: string): Promise<boolean>;
+    /**
+     * Which graphs use a reusable node, and at which node within each.
+     *
+     * On the store rather than derived in a controller from `listWorkflows`,
+     * unlike `connections/:id/workflows` which does exactly that. The difference
+     * is that this number is rendered *beside every entry of a picker*, so
+     * deriving it would mean parsing every graph in the deployment once per
+     * reusable node offered. A store can answer it from the rows it holds.
+     */
+    reusableNodeUses?(id: string): Promise<CatalogReusableNodeUse[]>;
     /**
      * Per-type load expectations as an operator set them.
      *