@dudousxd/nestjs-catalog 0.13.0 → 0.15.0

package/dist/catalog.pipeline.d.ts

@@ -27,6 +27,37 @@ export type ConnectorKind = (typeof CONNECTOR_KINDS)[number];
  * entirely. Anything narrowing a stored value narrows against *this*.
  */
 export declare function isConnectorKind(value: unknown): value is ConnectorKind;
+/**
+ * What a published workflow runs as. **Not an authored object.**
+ *
+ * This used to be the thing somebody created: a screen, a `POST connectors`, a
+ * kind and a config and a schedule typed into a form. It is not that any more,
+ * and every route that let anybody make one directly has been removed. A
+ * connector is now minted by {@link CatalogWorkflowStore.publishWorkflow} and
+ * exists for the four jobs a graph cannot do for itself:
+ *
+ * - **It is the mutex key.** `singleton: { key: connectorMutexKey }` on the
+ *   durable workflow serialises runs per connector id, which is what stops two
+ *   workers loading one type at once.
+ * - **It is the run's owner.** `ConnectorRun.connectorId` is how `listRuns`
+ *   groups a history, so a stable id across edits of the graph is what makes
+ *   "what has this pipeline done" answerable at all.
+ * - **It holds the watermark.** `state`, keyed by source-node id — see
+ *   {@link CatalogConnector.state}.
+ * - **It answers "which connectors write this type".** `targetType` is kept
+ *   equal to the workflow's sink type, so that query keeps working.
+ *
+ * Everything else on it is derived. `kind`, `config`, `connectionId` and
+ * `secretEnvVar` are **not read** on a connector that has a `workflowId`, and
+ * every connector has one now; they survive only because a row adopted from
+ * before this change still carries what it was configured with, and throwing
+ * that away would destroy the evidence of what a load used to do.
+ *
+ * The reason for keeping a record at all rather than running graphs directly is
+ * that all four jobs above need an identity that outlives an edit. A graph's
+ * version changes when anybody drags a node; the thing a run belongs to must
+ * not.
+ */
 export interface CatalogConnector {
     id: string;
     name: string;
@@ -54,28 +85,39 @@ export interface CatalogConnector {
     /** The transform that turns source records into rows of `targetType`. */
     transformId?: string;
     /**
-     * The workflow that turns source records into rows of `targetType`, when one
-     * transform is not enough.
+     * The graph this connector runs. **The only thing that says what it does.**
+     *
+     * Optional in the type and mandatory in practice: `publishWorkflow` sets it on
+     * every connector it mints, and adoption sets it on every connector that
+     * predates this change. It stays optional here because a store read must be
+     * able to represent a row written before adoption ran without asserting
+     * something about it that is not yet true — narrowing this to `string` would
+     * turn "we have not migrated yet" into a type error at the read.
      *
      * Mutually exclusive with {@link transformId}, and the store refuses a
      * connector that sets both: two answers to "what shapes this data" means the
      * runner picks one, and which one it picked is invisible until the load comes
-     * out wrong. A connector with a `transformId` and no `workflowId` behaves
-     * exactly as it did before workflows existed.
+     * out wrong.
      *
-     * When this is set, the connector's own `kind`, `config`, `connectionId` and
+     * When this is set the connector's own `kind`, `config`, `connectionId` and
      * `secretEnvVar` are **not read**: the workflow's source nodes say where the
-     * data comes from, and letting the connector also say would be two authorities
-     * for one question. `targetType` stays meaningful and is kept equal to the
-     * workflow's sink type by {@link CatalogPipelineStore.saveConnector}, so every
-     * existing "which connectors write this type" answer keeps working.
-     *
-     * `state` keeps its meaning too, but is keyed by node id when a workflow runs:
-     * a graph with two sources has two watermarks, and one flat blob would let
-     * them overwrite each other.
+     * data comes from, and letting the connector also say would be two
+     * authorities for one question. `targetType` is kept equal to the workflow's
+     * sink type, so every existing "which connectors write this type" answer
+     * keeps working.
      */
     workflowId?: string;
-    /** Cron-ish, interpreted by whatever schedules it. Empty means manual only. */
+    /**
+     * A **copy** of {@link CatalogWorkflow.schedule}, and nothing reads it.
+     *
+     * Kept, and kept honest by the store, for exactly one reason: it is the
+     * evidence of what a connector was doing before its schedule moved onto the
+     * graph. The authority is the workflow, {@link CatalogWorkflowStore} writes
+     * this from there on every publish, and the scheduler deliberately does not
+     * consult it — see the note on `ConnectorScheduler`, which used to read this
+     * field and now reads workflows, because a second copy of a column is how the
+     * two come to disagree the first time somebody edits one.
+     */
     schedule?: string;
     /**
      * Whether a run replaces the dataset or adds to it.
@@ -113,6 +155,13 @@ export interface CatalogConnector {
      * is a consequence. Mixing them means a person editing a connector can
      * silently rewind or skip data, and a diff of the config stops meaning what
      * somebody decided.
+     *
+     * **Keyed by source-node id**, because a graph with two sources has two
+     * watermarks and one flat blob would let them overwrite each other. A
+     * connector adopted from before workflows existed had a flat blob, and
+     * adoption re-keys it under the id of the single source node it was wrapped
+     * into — losing that would make the first run after an upgrade re-read an
+     * incremental source from the beginning.
      */
     state?: Record<string, unknown>;
     enabled: boolean;
@@ -508,12 +557,13 @@ export interface WorkflowNodeOutcome {
 /**
  * What a node can be.
  *
- * Three kinds, and they are exactly the three verbs the existing connector
- * runner already performs in sequence: fetch, transform, publish. Nothing here
- * is a kind this service cannot execute, which is the same rule
- * {@link CONNECTOR_KINDS} follows — a kind that exists in the type and throws
- * at run time is worse than one that is absent, because the first looks
- * supported in a palette.
+ * The first three are exactly the three verbs the existing connector runner
+ * already performs in sequence: fetch, transform, publish. The fourth hands a
+ * position in the graph to a durable workflow that already exists in the
+ * deployment. Nothing here is a kind this service cannot execute, which is the
+ * same rule {@link CONNECTOR_KINDS} follows — a kind that exists in the type
+ * and throws at run time is worse than one that is absent, because the first
+ * looks supported in a palette.
  *
  * The kinds that were considered and rejected, since a small vocabulary is only
  * defensible if the omissions are:
@@ -531,8 +581,17 @@ export interface WorkflowNodeOutcome {
  *   A `merge` kind would have had to carry a strategy field whose values the
  *   runner would have to implement one by one, and an unimplemented strategy in
  *   a dropdown is the failure this list exists to avoid.
+ * - **call a durable *step*** — the sibling of {@link WorkflowCallNode} that
+ *   somebody will eventually come looking for, and it cannot be built. A
+ *   durable step has no global identity: it is dispatched by a routing name
+ *   that a worker subscribes to, and within a run it is addressed by its `seq`
+ *   — a position in one workflow's history. There is no "run step X" entry
+ *   point on the engine to call, no lifecycle of its own to await, and nothing
+ *   to cancel. A workflow is the smallest thing that is addressable from
+ *   outside a run, which is why `call` names one and not a step. If a step is
+ *   what you want, the thing to call is a one-step workflow wrapping it.
  */
-export declare const WORKFLOW_NODE_KINDS: readonly ["source", "transform", "sink"];
+export declare const WORKFLOW_NODE_KINDS: readonly ["source", "transform", "sink", "call"];
 export type WorkflowNodeKind = (typeof WORKFLOW_NODE_KINDS)[number];
 /** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
 export declare function isWorkflowNodeKind(value: unknown): value is WorkflowNodeKind;
@@ -620,13 +679,77 @@ export interface WorkflowSinkNode extends WorkflowNodeBase {
      */
     mode?: 'full' | 'incremental';
 }
+/**
+ * Hands this position in the graph to a durable workflow that already exists.
+ *
+ * The node the canvas cannot write the body of: the work happens in a workflow
+ * somebody else registered, possibly in another SDK, and this node is the wire
+ * from a graph to it. It runs as a **tracked child run** of the catalog's own
+ * durable run — `ctx.startChild` then `ctx.child` — so the child has its own
+ * lifetime, its own retries and its own history, and the catalog's run is
+ * suspended at zero compute while it goes.
+ *
+ * ## Why the version is stored and not resolved
+ *
+ * A call names {@link callName} **and** {@link callVersion}, and the pair is
+ * part of the graph fingerprint. Storing only the name would mean the person
+ * who owns that workflow can change what your load does by registering a new
+ * version — a behaviour change in your pipeline with nothing in your diff to
+ * point at. So the version is authored, and a run that would have used a
+ * different one is refused rather than silently run: see
+ * `WorkflowRunSteps.checkCall`, which is where the pin is actually enforced,
+ * and which documents exactly how strong the enforcement is.
+ *
+ * ## What crosses the boundary
+ *
+ * The same thing that crosses every other boundary here: **handles, never
+ * rows.** The child receives a {@link WorkflowCallEnvelope} — the run id, this
+ * node's id, and the {@link WorkflowStageRef}s of its inputs — and reads the
+ * rows out of the stage store itself if it wants them. A child that produces
+ * rows for the graph writes them into the stage store under *this node's* id
+ * and returns their shape, which {@link readWorkflowCallOutput} narrows.
+ *
+ * There is no shared type between a catalog node and an arbitrary durable
+ * workflow, and this model does not pretend there is. What it does instead is
+ * make the mismatch loud: the envelope is one documented shape, the accepted
+ * answers are two documented shapes, and anything else fails the node naming
+ * the workflow, the version and the child run id.
+ *
+ * ## `config` is not a credential store
+ *
+ * Named `config` rather than `input` so it travels the same path a source
+ * node's config does — sealed under `encryptCredentials`, refused in plaintext
+ * without it — because a parameter bag that reaches a worker over a queue is
+ * exactly the shape a password ends up in. Prefer naming an env var the callee
+ * already reads.
+ */
+export interface WorkflowCallNode extends WorkflowNodeBase {
+    kind: 'call';
+    /**
+     * The workflow's registered name, on the wire — the string `engine.start`
+     * takes. A class reference is unavailable by construction: the point of this
+     * node is calling something the catalog does not compile against, including a
+     * body that lives in Python.
+     */
+    callName: string;
+    /**
+     * The registered **version**, as the durable engine spells it: a string, and
+     * `'1'` for anything registered without one.
+     *
+     * Not to be confused with {@link CatalogWorkflow.version}, which counts edits
+     * to *this* graph and is a number. This one identifies somebody else's code.
+     */
+    callVersion: string;
+    /** Parameters the author typed, handed to the child under `input`. */
+    config: Record<string, unknown>;
+}
 /**
  * A discriminated union, so narrowing a node is `node.kind === "sink"` and
  * never a type assertion. This is why the kind list is not simply a string on
  * one node shape with every field optional: that shape lets a source node carry
  * a `transformId` and nothing catches it.
  */
-export type WorkflowNode = WorkflowSourceNode | WorkflowTransformNode | WorkflowSinkNode;
+export type WorkflowNode = WorkflowSourceNode | WorkflowTransformNode | WorkflowSinkNode | WorkflowCallNode;
 /**
  * One wire.
  *
@@ -742,6 +865,31 @@ export interface CatalogWorkflow {
      * a connector claims to write something else.
      */
     targetType: string;
+    /**
+     * Cron-ish, interpreted by whatever schedules it. Empty means manual only.
+     *
+     * **Authored here, on the graph, and nowhere else.** It used to live on the
+     * connector, which was defensible while a connector was a thing somebody
+     * created and is not now that one is minted: a schedule is a statement about
+     * a pipeline, and the pipeline is the graph. The connector keeps a copy for
+     * evidence — see {@link CatalogConnector.schedule} — and `ConnectorScheduler`
+     * reads this field rather than that one, so there is one authority.
+     *
+     * Only a `ready` graph is scheduled. A draft carrying a cron is a load nobody
+     * declared finished, and the scheduler says so out loud rather than skipping
+     * it quietly; that silence is the exact shape of the incident this field's
+     * predecessor caused.
+     */
+    schedule?: string;
+    /**
+     * Whether this graph runs at all.
+     *
+     * Both halves of the old `isScheduled` test now live on the workflow, because
+     * splitting them across two rows is what made "my connector is enabled but
+     * nothing runs" a question with two places to look. Defaults true: a graph
+     * somebody went to the trouble of publishing is one they meant to run.
+     */
+    enabled: boolean;
     createdBy: string;
     createdAt: string;
     updatedAt: string;
@@ -814,6 +962,15 @@ export interface WorkflowNodeStepInput {
      * graph. Empty for a source node, which reads from a system instead.
      */
     inputs: WorkflowStageRef[];
+    /**
+     * The operator's reason for expecting this load to lose rows. Read only by
+     * the sink, and absent on every scheduled run by construction.
+     *
+     * On the step input rather than fetched at the sink because a durable step
+     * has to be a pure function of what was checkpointed — see the note where
+     * this is passed in `CatalogWorkflowRunWorkflow`.
+     */
+    expectShrink?: string;
 }
 /** What a node step returns. Also ids and counters. */
 export interface WorkflowNodeStepOutput {
@@ -842,8 +999,112 @@ export interface WorkflowNodeStepOutput {
      */
     logs: string[];
 }
+/**
+ * The number in {@link WorkflowCallEnvelope.contract}.
+ *
+ * A version on the *shape the catalog sends*, separate from the version of the
+ * workflow being called, because the two change for different reasons and a
+ * callee written against one has to be able to say which. A callee that reads
+ * this and does not recognise it should refuse rather than guess — a failed
+ * child is a failed node with a name attached, and a guess is a load nobody can
+ * account for.
+ */
+export declare const WORKFLOW_CALL_CONTRACT = 1;
+/**
+ * What a {@link WorkflowCallNode} hands its child.
+ *
+ * One documented shape, and the whole of what the catalog promises a callee.
+ * Everything the catalog knows sits under `catalog`, and everything the author
+ * typed sits under `input`, so a parameter called `runId` cannot ever shadow
+ * the run id — which is the kind of collision that only shows up in production
+ * on somebody else's graph.
+ *
+ * Handles, never rows: `inputs` names the stages this node's inbound edges
+ * produced, in edge order, and the rows themselves stay in the stage store
+ * addressed by `(runId, nodeId, batch)` — one row per batch, keyed
+ * `runId#nodeId#batch`. A callee in another SDK reads them from there. Passing
+ * the rows would write the whole intermediate dataset into
+ * `durable_step_checkpoints` as the child's input, once per call and again on
+ * every replay, which is the measurement {@link WorkflowStageRef} exists for.
+ */
+export interface WorkflowCallEnvelope {
+    catalog: {
+        /** {@link WORKFLOW_CALL_CONTRACT} at the time the call was made. */
+        contract: number;
+        /** The catalog run, which is also the snapshot id and the stage key. */
+        runId: string;
+        /** The calling node. Also the id any rows for the graph must be staged under. */
+        nodeId: string;
+        workflowId: string;
+        /** The **graph's** version, not the callee's. See {@link WorkflowCallNode.callVersion}. */
+        workflowVersion: number;
+        principalId: string;
+        /** The stages this node reads, in inbound-edge order. Empty for a call with no input. */
+        inputs: WorkflowStageRef[];
+    };
+    /** {@link WorkflowCallNode.config}, verbatim. Opaque to the catalog. */
+    input: Record<string, unknown>;
+}
+/** What a called workflow may say it staged. Both counts, or neither. */
+export interface WorkflowCallOutput {
+    /** Batches written under `(runId, nodeId, 1..batches)`. */
+    batches: number;
+    rowCount: number;
+}
+/**
+ * Read a child's return value as staged rows — or as nothing, or refuse it.
+ *
+ * Three answers rather than two, because a call has two legitimate purposes and
+ * they must not be confused with a bug:
+ *
+ * - `undefined` — the child returned nothing this graph can read rows from. A
+ *   perfectly ordinary outcome for a workflow called for its effect, and the
+ *   node reports zero rows, out loud, in its logs. It is not silently treated
+ *   as success-with-data: a full sink that then receives nothing refuses to
+ *   commit an empty snapshot, which is the loud end of this path.
+ * - a {@link WorkflowCallOutput} — the child staged rows for this node.
+ * - a **throw** — the child answered with `batches`/`rowCount` that are not
+ *   usable counts. Half a contract is a bug in the callee, and reading it as
+ *   "no rows" would turn that bug into a load that quietly came out short.
+ *
+ * The catalog cannot check any of this before the graph runs; there is no
+ * 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.
+ */
+export declare function readWorkflowCallOutput(value: unknown): WorkflowCallOutput | undefined;
+/**
+ * One workflow a call node could name.
+ *
+ * Declared here with nothing producing it yet, and that is deliberate rather
+ * than premature: a picker needs a list, and **no such list exists**. The
+ * durable engine can answer `workflowBody(name, version)` for the process
+ * asking and nothing more — and a missing body is ambiguous, since it equally
+ * means a body registered in another SDK through `registerRemote` or a group
+ * resolved by convention against a live worker. Inferring the list from what
+ * one pod happens to know would produce a picker that omits exactly the
+ * cross-SDK workflows this node exists to call.
+ *
+ * So the node takes a name and a version as authored text today, and this is
+ * the shape a canvas should be handed the day a deployment can announce its
+ * registrations. One entry per **version**, never per name: a picker that
+ * listed names and resolved the version for you would undo the pin.
+ */
+export interface CallableWorkflowRef {
+    name: string;
+    version: string;
+    /** What it does, if the deployment publishes one. Shown beside the name. */
+    description?: string;
+    /**
+     * The worker group its turns are dispatched to, when it has one. The signal
+     * that says "this one's body is not in this process" — a Python workflow, or
+     * a separate TS worker — which is precisely what a caller cannot otherwise
+     * tell from a missing body.
+     */
+    group?: string;
+}
 /** 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"];
+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"];
 export type WorkflowIssueCode = (typeof WORKFLOW_ISSUE_CODES)[number];
 export interface WorkflowValidationIssue {
     code: WorkflowIssueCode;
@@ -956,8 +1217,14 @@ export interface CatalogWorkflowStore {
      * point at a ready graph, so a save that dropped the status would disable a
      * scheduled load with nothing said to anybody. Refusing puts the error in
      * front of the person who is editing, at the moment they edit. To park a
-     * broken idea on a live graph, {@link unpublishWorkflow} it first and be told
-     * which connectors that stops.
+     * broken idea on a live graph, {@link unpublishWorkflow} it first — which
+     * disables the connector it runs as, so the parking is visible rather than a
+     * graph that is quietly still on a cron.
+     *
+     * `schedule` and `enabled` are not inputs either, and for a different reason
+     * from the derived three: they are authored, but not *here*. See
+     * {@link saveWorkflowSchedule} for why a cron must not ride along on an
+     * autosave.
      *
      * `version`, `graphHash` and `targetType` are not inputs: the first two are
      * derived from the graph and the third from the sink, and accepting them from
@@ -981,24 +1248,114 @@ export interface CatalogWorkflowStore {
      *
      * Idempotent on an already-ready graph, because the honest answer to "publish
      * this thing that is published" is the graph, not an error.
+     *
+     * **Publishing is also what mints the connector.** That is the load-bearing
+     * half of "the workflow is the only thing anybody authors": there is no
+     * `POST connectors` any more, so this is the only way one comes into
+     * existence. The minted row carries this workflow's id, its sink's type, its
+     * schedule and its enabled flag, and it is the identity every later run,
+     * watermark and mutex is keyed on — so publishing an already-published graph
+     * must **update** that row rather than mint a second one, or a re-publish
+     * would orphan a pipeline's entire history.
      */
     publishWorkflow(id: string, publishedBy: string): Promise<CatalogWorkflow>;
     /**
-     * Take a graph back to `draft`.
+     * Take a graph back to `draft`, and stop what it was running.
      *
-     * **Refuses while any connector still runs it**, exactly as
-     * {@link deleteWorkflow} does and for the same reason: a connector may only
-     * point at a ready graph, so unpublishing one out from under a schedule breaks
-     * a load that was working, and the operator needs to know *which* connectors
-     * to point elsewhere first. Refusing here rather than cascading is deliberate —
-     * disabling somebody's connectors as a side effect of an edit to something
-     * else is precisely the silent action this status exists to prevent.
+     * This used to refuse while any connector still ran the graph, on the reasoning
+     * that unpublishing one out from under a schedule breaks a working load and the
+     * operator should point those connectors elsewhere first. That reasoning
+     * assumed a connector was an independently authored object that could be
+     * pointed somewhere; it no longer is. A published graph now has exactly one
+     * connector and it is this graph's own, so the old refusal would refuse
+     * every unpublish there is — a rule that always fires is not a rule.
+     *
+     * So the cascade the old docblock argued against is now the correct behaviour,
+     * and the thing it was protecting is protected differently: the connector is
+     * **disabled, not deleted**. Its id, its run history and its watermark all
+     * survive, so re-publishing resumes the same pipeline rather than starting a
+     * new one, and nothing silently keeps running in the meantime.
      */
     unpublishWorkflow(id: string, unpublishedBy: string): Promise<CatalogWorkflow>;
-    /** Refuses while any connector still runs it. */
+    /**
+     * Delete the graph and the connector it ran as.
+     *
+     * Cascading for the reason {@link unpublishWorkflow} gives — the connector is
+     * this graph's own and there is nowhere else to point it — and destructive
+     * here rather than disabling, because the graph is going too and a connector
+     * whose workflow does not exist is precisely the dangling row this cascade
+     * exists to avoid leaving behind.
+     */
     deleteWorkflow(id: string): Promise<boolean>;
-    /** Which connectors run it. Named, so a refusal can say. */
+    /**
+     * The connector this graph runs as, as a list.
+     *
+     * A list rather than an optional single value, because that is what it
+     * honestly is: a store predating this change may hold several connectors
+     * pointing at one graph, and answering with the first would hide the rest from
+     * the operator who has to reconcile them. A graph published under the current
+     * rules has exactly one.
+     */
     connectorsUsingWorkflow(id: string): Promise<CatalogConnector[]>;
+    /**
+     * Set when this graph runs, and whether it runs.
+     *
+     * Its own method rather than fields on {@link saveWorkflow}, and for the
+     * reason `saveConnectorState` is separate from `saveConnector`: a canvas
+     * autosaves. A cron folded into the save every drag of a node passes through
+     * is a cron that a stale editor tab can silently revert, and the symptom would
+     * be a load that stopped running with a diff nobody made.
+     *
+     * Writes through to the minted connector's copy in the same call, so the two
+     * cannot be observed disagreeing.
+     */
+    saveWorkflowSchedule(id: string, input: {
+        schedule?: string;
+        enabled?: boolean;
+    }, changedBy: string): Promise<CatalogWorkflow>;
+    /**
+     * Wrap a connector that predates workflows into the graph it always was.
+     *
+     * **The upgrade path, and the reason removing `POST connectors` does not
+     * orphan anything.** A deployment upgrading into this change has connectors
+     * that were authored directly — a kind, a config, optionally one transform,
+     * and a target type — and no route can edit them any more. Three outcomes
+     * were possible: migrate them, leave them readable but frozen, or make
+     * somebody rebuild each by hand. This is the first, and it is chosen because
+     * the shape was already exactly representable: a connector *is* a
+     * single-source, single-sink graph with at most one transform in the middle,
+     * and it has been describable as one since `workflowId` existed.
+     *
+     * ## What is preserved, and why each matters
+     *
+     * - **The connector id.** It is the mutex key, the owner of every
+     *   `ConnectorRun` and the holder of the watermark. Minting a fresh connector
+     *   and leaving the old one would split one pipeline's history in two and
+     *   leave nothing serialising the halves against each other.
+     * - **The watermark, re-keyed.** A plain connector kept a flat `state`; a
+     *   graph keys it by source-node id. Carrying the blob over unchanged would
+     *   leave the new source node with no watermark at all, and the first run
+     *   after the upgrade would re-read an incremental source from the beginning —
+     *   which is not data loss, but is a surprise measured in hours on a large
+     *   source.
+     * - **The schedule**, moved to the graph, which is where it is authored now.
+     *
+     * ## What changes, stated plainly
+     *
+     * The graph is published as `ready` without a person having declared it
+     * finished, because refusing to publish would leave the pipeline not running —
+     * an upgrade that silently stops twelve loads is a worse outcome than one that
+     * carries a decision forward on the operator's behalf. It is validated first
+     * and the adoption is **refused** if the wrap does not validate, so nothing is
+     * published that could not have been drawn.
+     *
+     * Idempotent: a connector that already has a `workflowId` is left alone and
+     * answered `undefined`. That is what makes it safe to run at every boot.
+     */
+    adoptConnector(connectorId: string, adoptedBy: string): Promise<{
+        workflow: CatalogWorkflow;
+        connector: CatalogConnector;
+    } | undefined>;
 }
 /**
  * Where the rows between two nodes actually sit.