@uipath/maestro-builder-sdk 6.49.3 → 6.50.1

package/dist/case/check-cli.js

@@ -3,7 +3,8 @@
  * check-cli — fast static validation of <Name>.case.ts (no output file).
  *
  * Usage: node --experimental-strip-types check-cli.js <case.ts | BaseName> \
- *     [--library <library-json dir>] [--connectors-local <overlay dir>] [--bindings <bindings.json>]
+ *     [--library <library-json dir>] [--connectors-local <overlay dir>] [--bindings <bindings.json>] \
+ *     [-o <the plan compile writes>]
  * Exits 0 when clean (warnings allowed), 1 on any error.
  *
  * The library is opened exactly as `compile-cli` opens it (`openCliLibrary`), so
@@ -14,19 +15,18 @@ import { resolveCaseFile, loadBuiltCase } from './load.js';
 import { check } from './check.js';
 import { caseCheckOpts } from './cli-library.js';
 import { openCliLibrary } from '../core/cli-library.js';
-import { Bindings } from '../core/bindings.js';
-import { defaultBindingsFile } from '../workdir.js';
-import { flagValue, runWhenInvokedDirectly } from '../cli-run.js';
+import { caseCompileTarget } from './compile-cli.js';
+import { runWhenInvokedDirectly } from '../cli-run.js';
 import { ensureTypeScriptRuntime } from '../node-runtime.js';
 /** Flags that take a value: their argument is never the source positional. */
-const VALUE_FLAGS = new Set(['--library', '--connectors-local', '--bindings']);
-const USAGE = 'usage: check <case.ts | BaseName> [--library <dir>] [--connectors-local <dir>] [--bindings <file>]';
+const VALUE_FLAGS = new Set(['--library', '--connectors-local', '--bindings', '-o']);
+const USAGE = 'usage: check <case.ts | BaseName> [--library <dir>] [--connectors-local <dir>] [--bindings <file>] [-o <plan>]';
 export async function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.error(USAGE);
         return 2;
     }
-    const input = argv.find((a, i) => !a.startsWith('--') && !VALUE_FLAGS.has(argv[i - 1]));
+    const input = argv.find((a, i) => !a.startsWith('-') && !VALUE_FLAGS.has(argv[i - 1]));
     if (input === undefined) {
         console.error(USAGE);
         return 2;
@@ -34,8 +34,9 @@ export async function run(argv) {
     const file = resolveCaseFile(input);
     ensureTypeScriptRuntime();
     const built = await loadBuiltCase(file);
-    // bindings.json as `case compile` reads it, for the binding-label rules (#1034).
-    const bindings = new Bindings(flagValue(argv, '--bindings') ?? defaultBindingsFile());
+    // The bindings `case compile` reads, plan fallback included, for the
+    // binding-label rules (#1034): `-o` names the plan as it does for compile.
+    const { bindings } = caseCompileTarget(argv);
     const diags = check(built, caseCheckOpts(openCliLibrary(argv), bindings));
     reportDiagnostics(diags);
     for (const d of diags)

package/dist/case/compile-cli.d.ts

@@ -1,6 +1,27 @@
 #!/usr/bin/env node
+import { Bindings } from '../core/bindings.js';
 import { type CliExitCode } from '../cli-run.js';
 export declare function run(argv: string[]): Promise<CliExitCode>;
+/**
+ * The plan file `case compile` writes, and the bindings it resolves connection
+ * and folder labels against. `case check` reads the same pair, so the two agree
+ * on which labels are declared.
+ *
+ * The plan is `-o`, else the plan file the project in the working directory
+ * ships, else `caseplan.json`. The bindings are `--bindings` (default: the
+ * project's bindings.json), with that plan's own root bindings as a fallback
+ * when it exists. Recompiling into an existing plan (the brownfield loop:
+ * decompile, edit, compile back over the same file) then resolves the binding
+ * ids decompile names a connector's connection and folder by
+ * (`connection: "bOC1"`).
+ *
+ * @param argv - The command's arguments.
+ * @returns The output path and the bindings registry.
+ */
+export declare function caseCompileTarget(argv: string[]): {
+    out: string;
+    bindings: Bindings;
+};
 /**
  * Write the entry point's id onto its trigger, as `data.inputs.entryPointId`.
  *

package/dist/case/compile-cli.js

@@ -23,6 +23,7 @@ import { check } from './check.js';
 import { caseCheckOpts } from './cli-library.js';
 import { entryPointIO } from './entry-points.js';
 import { Bindings } from '../core/bindings.js';
+import { offlineBindingLabel } from './ids.js';
 import { openCliLibrary } from '../core/cli-library.js';
 import { defaultBindingsFile } from '../workdir.js';
 import { flagValue, runWhenInvokedDirectly } from '../cli-run.js';
@@ -54,8 +55,7 @@ export async function run(argv) {
     // which is what the three copies of these lines used to each decide for itself.
     // Opened BEFORE the check pass, which reads the same library (#1014).
     const library = openCliLibrary(argv);
-    const bindFile = flagValue(argv, '--bindings') ?? defaultBindingsFile();
-    const bindings = new Bindings(bindFile);
+    const { out, bindings } = caseCompileTarget(argv);
     const diags = check(built, caseCheckOpts(library, bindings));
     for (const d of diags)
         console.error(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}`);
@@ -66,7 +66,6 @@ export async function run(argv) {
         console.error(`compile: ${errors.length} error(s); not emitting.`);
         return 1;
     }
-    const out = flagValue(argv, '-o') ?? shippedCasePlanName('.') ?? 'caseplan.json';
     const shadow = shadowedOutputDiagnostic(out);
     if (shadow) {
         console.error(`  ✗ [${shadow.code}] ${shadow.message} Fix: ${shadow.suggestion}.`);
@@ -94,6 +93,30 @@ export async function run(argv) {
     reportResult({ path: resolve(out), stages, ...(triggers >= 0 ? { triggers } : {}), ...(resources >= 0 ? { resources } : {}) });
     return 0;
 }
+/**
+ * The plan file `case compile` writes, and the bindings it resolves connection
+ * and folder labels against. `case check` reads the same pair, so the two agree
+ * on which labels are declared.
+ *
+ * The plan is `-o`, else the plan file the project in the working directory
+ * ships, else `caseplan.json`. The bindings are `--bindings` (default: the
+ * project's bindings.json), with that plan's own root bindings as a fallback
+ * when it exists. Recompiling into an existing plan (the brownfield loop:
+ * decompile, edit, compile back over the same file) then resolves the binding
+ * ids decompile names a connector's connection and folder by
+ * (`connection: "bOC1"`).
+ *
+ * @param argv - The command's arguments.
+ * @returns The output path and the bindings registry.
+ */
+export function caseCompileTarget(argv) {
+    const out = flagValue(argv, '-o') ?? shippedCasePlanName('.') ?? 'caseplan.json';
+    const bindFile = flagValue(argv, '--bindings') ?? defaultBindingsFile();
+    // A row serialize minted offline (`{ id: 'b…', resourceKey: 'drive' }`) is a
+    // placeholder for the label `drive`, not a binding: it must not answer.
+    const minted = (row) => offlineBindingLabel(row) !== undefined;
+    return { out, bindings: new Bindings(bindFile).withFallback(existsSync(out) ? out : undefined, minted) };
+}
 /**
  * The file names a Case project's plan can have, in the order the packager
  * (`@uipath/packager-tool-case` `CasePlanFileNames`) picks the first one present.

package/dist/check.d.ts

@@ -29,6 +29,11 @@ export interface ListEnvelopeFields {
 export interface CheckOpts extends ConnectorCheckOpts, EventCheckOpts {
     /** Resolve the measured collection envelope for one connector operation. */
     listEnvelope?: (connector: string, operation: string, version?: string, object?: string) => ListEnvelopeFields | undefined;
+    /**
+     * The library's definition for one connector operation, the one compile places:
+     * whether it grants an error port is then the same answer in both rungs.
+     */
+    connectorDefinition?: (connector: string, operation: string, version?: string, object?: string) => unknown;
 }
 export declare function check(built: BuiltFlow, opts?: CheckOpts): Diagnostic[];
 /**

package/dist/check.js

@@ -230,7 +230,6 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
     // Step name → the read rule for its output, bound to its inputs. Filled from
     // OUTPUT_READ_RULES for every kind whose inputs take a `returns`.
     const outputReaders = new Map();
-    const connectorSteps = new Map();
     // Subflow step name → the child flow it runs. A subflow's output is the
     // OBJECT of the child's declared outputs, so a read of it is checked against
     // that child rather than waved through (see SUBFLOW_* below).
@@ -346,7 +345,7 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                         declared.add(v);
             }
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'error')
-                checkOnError(s, prevPortSource, diags, prevPortSource && checkedSteps.get(prevPortSource.name), carriedLookup([built, ...ancestors]));
+                checkOnError(s, prevPortSource, diags, prevPortSource && checkedSteps.get(prevPortSource.name), opts, carriedLookup([built, ...ancestors]));
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port.startsWith('branch-')) {
                 const want = s.port.slice('branch-'.length);
                 const prevSpec = prevAction?.spec;
@@ -465,12 +464,6 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                 else {
                     collectActionExprs(s, exprs, errorSource);
                 }
-                if (s.spec.kind === 'connector') {
-                    connectorSteps.set(s.name, s.spec);
-                    checkConnectorLookups(s.name, s.spec, opts, diags);
-                    checkConnectorSchema(s.name, s.spec, opts, diags);
-                    checkConnectorContract(s.name, s.spec, opts, diags);
-                }
                 // A custom FlowAction subclass has no `kind`: the family rules below
                 // don't apply, and it reports through its own diagnostics() hook.
                 const maybeCustom = s.spec;
@@ -715,7 +708,7 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                 // handle); it is not a legal source for anything else.
                 prevPortSource = s;
                 addExpr(s.collection.js, s.name);
-                checkLoopListEnvelope(s, connectorSteps, opts, diags);
+                checkLoopListEnvelope(s, registeredSteps, opts, diags);
                 if (s.options?.completionCondition)
                     addExpr(s.options.completionCondition.js, s.name);
                 // The same refusal serialize throws, from the same helper: an option or
@@ -1377,16 +1370,18 @@ function checkConnectorContract(step, spec, opts, diags) {
     coreCheckConnectorContract(where, spec, opts, report, step);
     checkBindingPresence(`connector "${step}"`, spec, (code, message) => report({ level: 'error', code, message }), { key: spec.key, action: spec.action });
 }
-/** Reject a wrapper hop when the runtime shape of a list has been measured. */
-function checkLoopListEnvelope(loop, connectors, opts, diags) {
+/**
+ * Reject a wrapper hop when the runtime shape of a list has been measured: the
+ * step the loop reads says what its list output looks like (`listShape`, a
+ * connector operation's measured envelope).
+ */
+function checkLoopListEnvelope(loop, registered, opts, diags) {
     const read = /^\$vars\.([^.]+)\.output\.([A-Za-z_$][\w$]*)$/.exec(loop.collection.js);
-    if (!read || !opts.listEnvelope)
+    if (!read)
         return;
     const [, step, field] = read;
-    const connector = connectors.get(step);
-    if (!connector)
-        return;
-    const measured = opts.listEnvelope(connector.key, connector.action, connector.version, connector.object);
+    const source = registered.get(step);
+    const measured = source?.impl.listShape?.(source.spec, opts);
     if (!measured || measured.envelope === field)
         return;
     const shape = measured.envelope === null
@@ -2723,6 +2718,12 @@ function checkRegisteredStep(entry, s, exprs, errorSource, opts, diags, typeOf,
             },
             options: opts,
             bindingLabels: (where, labels, use, target) => checkBindingLabels(where, labels, opts, (code, message) => diags.push({ level: 'error', code, step: s.name, message }), target, use),
+            connector: (c) => {
+                const spec = c;
+                checkConnectorLookups(s.name, spec, opts, diags);
+                checkConnectorSchema(s.name, spec, opts, diags);
+                checkConnectorContract(s.name, spec, opts, diags);
+            },
             resources: {
                 derivedNodeId: (id, what) => { if (!ledger.taken.has(id))
                     ledger.taken.set(id, what); },
@@ -2861,39 +2862,7 @@ function collectActionExprs(s, out, errorSource) {
             push(val);
         return;
     }
-    if (s.spec.kind === 'connector') {
-        // Same gap on the connector surface: `messageToSend: tmpl`…${v('typo')}``
-        // reached the runtime unchecked.
-        pushDeep(s.spec.inputs);
-    }
 }
-/**
- * The families with no definition this SDK can ask, and an error port anyway:
- * an Integration Service connector activity's definition comes from the
- * connector library, and every connector activity declares the `error` handle.
- *
- * Every other family is decided by a definition, never by a list:
- *
- *  - a bundled family by its bundled definition (`bundledActionNodeType` +
- *    `bundledDefinition`, #1011: `documentClassify` was missing from the old
- *    list although `uipath.document.classify@1.0` sets the flag);
- *  - a per-tenant family by the definition serialize synthesizes for it: a
- *    registered one (the process family, `agent` among it) through its node
- *    type's `errorPort`, which asks that definition, and `ixpExtract` through
- *    `perCallDefinition` (#1040: `publishedFunction` was refused here although
- *    `publishedFunctionDef` sets the flag).
- *
- * `publishedFunction`'s flag is measured, not assumed: on 2026-10-08 four
- * `flow debug` jobs on alpha/codereval called `acme-echo` with a non-string
- * `message` (null, object, number, array). In each, the function job failed
- * (`Python.FUNCTION_EXECUTION_ERROR`, category User, status 502), the node's
- * error boundary fired, and the handler's `err('message')` read
- * "Failure in the Orchestrator Job".
- *
- * A kind in none of these (`waitEvent`) has no error port: an event wait
- * resumes or does not.
- */
-const NO_DEFINITION_ERROR_PORT_KINDS = new Set(['connector']);
 /**
  * The ONERROR_NO_ERROR_PORT sentence for a typed step — a built-in family or a
  * registered node type — whose node type has no error port. One spelling for
@@ -2913,10 +2882,33 @@ const ERROR_ENVELOPE_FIELDS = ['code', 'message', 'detail', 'category', 'status'
  * `.onError(...)`-specific checks. The surface already refuses the structural
  * mistakes at build time (no previous step, two handlers on one node, an empty
  * handler); these are the ones only a checker can see.
+ *
+ * Whether the step has an error port at all: every family is decided by a
+ * definition, never by a list:
+ *
+ *  - a bundled family by its bundled definition (`bundledActionNodeType` +
+ *    `bundledDefinition`, #1011: `documentClassify` was missing from the old
+ *    list although `uipath.document.classify@1.0` sets the flag);
+ *  - a per-tenant family — every one is registered — through its node type's
+ *    `errorPort`, which asks the definition serialize synthesizes (#1040:
+ *    `publishedFunction` was refused here although `publishedFunctionDef` sets
+ *    the flag), or for a connector the library's definition, which check reads
+ *    through `connectorDefinition` and, without a library, assumes grants the
+ *    port, as every operation the library serves does.
+ *
+ * `publishedFunction`'s flag is measured, not assumed: on 2026-10-08 four
+ * `flow debug` jobs on alpha/codereval called `acme-echo` with a non-string
+ * `message` (null, object, number, array). In each, the function job failed
+ * (`Python.FUNCTION_EXECUTION_ERROR`, category User, status 502), the node's
+ * error boundary fired, and the handler's `err('message')` read
+ * "Failure in the Orchestrator Job".
+ *
+ * A kind in none of these (`waitEvent`) has no error port: an event wait
+ * resumes or does not.
  */
 function checkOnError(_handler, step, diags, 
 /** The step's registry record, when its kind is registered and its version resolved. */
-placed, carried) {
+placed, opts, carried) {
     // The builder refuses a handler with no eligible step before it, so a missing
     // source here means a hand-built `BuiltFlow`; there is nothing to say about it.
     if (!step)
@@ -2986,11 +2978,17 @@ placed, carried) {
             }
         }
         else if (impl.definition === 'per-tenant') {
-            const port = typeof impl.errorPort === 'function' ? impl.errorPort(spec) : impl.errorPort === true;
+            // The definition serialize will be supplied, when check's options can name
+            // it (a connector's, from the library); the type answers without it otherwise.
+            const def = impl.checkDefinition?.(placed.spec, opts);
+            const port = typeof impl.errorPort === 'function' ? impl.errorPort(spec, def) : impl.errorPort === true;
             if (!port) {
+                const named = def !== undefined && typeof def.nodeType === 'string' && typeof def.version === 'string';
                 diags.push({
                     level: 'error', code: 'ONERROR_NO_ERROR_PORT', step: step.name,
-                    message: declaredErrorPortRefusal(step.name, impl.typeName, impl.version),
+                    message: named
+                        ? declaredErrorPortRefusal(step.name, def.nodeType, def.version)
+                        : declaredErrorPortRefusal(step.name, impl.typeName, impl.version),
                 });
                 return;
             }
@@ -3025,7 +3023,7 @@ placed, carried) {
     // a carried definition); what is left is bundled, or has no definition here.
     const noPort = bundledDef !== undefined
         ? !definitionHasErrorPort(bundledDef)
-        : !bundledType && !NO_DEFINITION_ERROR_PORT_KINDS.has(spec.kind);
+        : !bundledType;
     if (noPort) {
         diags.push({
             level: 'error',

package/dist/cli-library.js

@@ -25,5 +25,13 @@ export function flowCheckOpts(library, bindings) {
                 return undefined; // an unresolvable operation is connectorResolveError's to report
             }
         },
+        connectorDefinition: (connector, operation, version, object) => {
+            try {
+                return library.resolve(connector, operation, version, object).v1def;
+            }
+            catch {
+                return undefined; // as above
+            }
+        },
     };
 }

package/dist/core/binding-messages.d.ts

@@ -27,6 +27,8 @@ export interface BindingsView {
     resolve(name?: string): string | undefined;
     declared?(): string[];
     entry?(name?: string): unknown;
+    /** True when only a recompile fallback row (the plan's own bindings) answers `name`. */
+    fromFallback?(name?: string): boolean;
 }
 export declare function bindingSelfNameMessage(where: string, name: string, attribute: 'connection' | 'folder', target?: PrepareTarget): string;
 /**

package/dist/core/binding-messages.js

@@ -81,6 +81,11 @@ export function undeclaredBinding(bindings, name) {
 export function bindingLabelRefusal(bindings, name, attribute, where, target) {
     if (!bindings)
         return undefined;
+    // A label that is exactly a row id of the plan being recompiled (what
+    // decompile emits) reuses that row. Those rows are not an author's
+    // bindings.json, so neither rule applies to them.
+    if (bindings.fromFallback?.(name))
+        return undefined;
     const resolved = bindings.resolve(name);
     if (resolved === name)
         return new BindingRefusal('BINDING_SELF_NAME', bindingSelfNameMessage(where, name, attribute, target));

package/dist/core/bindings.d.ts

@@ -1,11 +1,50 @@
 export declare class Bindings {
     private list;
+    /**
+     * Rows from {@link withFallback}: the root `bindings[]` of the plan being
+     * recompiled. Kept apart from `list` on purpose. They are not an author's
+     * bindings.json, so they never count as declared names and never feed the
+     * self-name / undeclared label rules. An offline plan's own rows are
+     * `{ id: 'slack', resourceKey: 'slack' }`; counted as declared they made the
+     * second offline compile refuse the connector's own label (BINDING_SELF_NAME).
+     */
+    private fallback;
     constructor(file?: string);
-    /** Resolve by binding `name` or `id`; returns its resourceKey (or default). */
+    /**
+     * Add the root bindings of another document (the plan being recompiled) as a
+     * fallback. A fallback row answers only a label that is exactly its `id`
+     * (what decompile emits), whose key is not that same id (a placeholder; see
+     * `fallbackRow`), and that the primary registry does not answer. It
+     * is never part of {@link declared}, and {@link fromFallback} lets the label
+     * rules skip it.
+     *
+     * @param file - A bindings.json, or any document with a root `bindings[]`
+     *   (a caseplan); a missing or unreadable file adds nothing.
+     * @param isPlaceholder - Recognises a row the document's own compiler minted
+     *   offline (a label with no real key behind it, under a minted id). Such a
+     *   row answers nothing, like a row whose key is its own id.
+     * @returns This registry, for chaining.
+     */
+    withFallback(file?: string, isPlaceholder?: (row: Record<string, unknown>) => boolean): this;
+    private primary;
+    /**
+     * The fallback row whose `id` is `name`. A row whose key is its own id
+     * (`{ id: 'drive', resourceKey: 'drive' }`, what an offline compile writes) is
+     * a placeholder, not an answer, so it is skipped: the label rules then judge
+     * `drive` against the author's bindings.json as they would without a fallback.
+     */
+    private fallbackRow;
+    /**
+     * True when only a fallback row answers `name`: the primary registry does not,
+     * and a fallback row's `id` is exactly `name`. The label rules
+     * (`bindingLabelRefusal`) accept such a label as is.
+     */
+    fromFallback(name?: string): boolean;
+    /** Resolve by binding `name` or `id` (fallback rows: `id` only); returns its resourceKey (or default). */
     resolve(name?: string): string | undefined;
-    /** Every symbolic name the file declares — what an author CAN write in `connection:` / `folder:`. */
+    /** Every symbolic name the bindings.json declares — what an author CAN write in `connection:` / `folder:`. Fallback rows are not included. */
     declared(): string[];
-    /** The full binding entry by `name` or `id` — for consumers that emit a binding
+    /** The full binding entry by `name` or `id` (fallback rows: `id` only) — for consumers that emit a binding
      * registry + `=bindings.<id>` refs (the Case caseplan) rather than inlining the
      * resourceKey (the Flow node). */
     entry(name?: string): Record<string, unknown> | undefined;

package/dist/core/bindings.js

@@ -5,21 +5,83 @@
 import { readFileSync, existsSync } from 'node:fs';
 export class Bindings {
     list = [];
+    /**
+     * Rows from {@link withFallback}: the root `bindings[]` of the plan being
+     * recompiled. Kept apart from `list` on purpose. They are not an author's
+     * bindings.json, so they never count as declared names and never feed the
+     * self-name / undeclared label rules. An offline plan's own rows are
+     * `{ id: 'slack', resourceKey: 'slack' }`; counted as declared they made the
+     * second offline compile refuse the connector's own label (BINDING_SELF_NAME).
+     */
+    fallback = [];
     constructor(file) {
         if (file && existsSync(file)) {
             this.list = normalizeBindings(JSON.parse(readFileSync(file, 'utf8')));
         }
     }
-    /** Resolve by binding `name` or `id`; returns its resourceKey (or default). */
+    /**
+     * Add the root bindings of another document (the plan being recompiled) as a
+     * fallback. A fallback row answers only a label that is exactly its `id`
+     * (what decompile emits), whose key is not that same id (a placeholder; see
+     * `fallbackRow`), and that the primary registry does not answer. It
+     * is never part of {@link declared}, and {@link fromFallback} lets the label
+     * rules skip it.
+     *
+     * @param file - A bindings.json, or any document with a root `bindings[]`
+     *   (a caseplan); a missing or unreadable file adds nothing.
+     * @param isPlaceholder - Recognises a row the document's own compiler minted
+     *   offline (a label with no real key behind it, under a minted id). Such a
+     *   row answers nothing, like a row whose key is its own id.
+     * @returns This registry, for chaining.
+     */
+    withFallback(file, isPlaceholder) {
+        if (!file || !existsSync(file))
+            return this;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            return this; // a fallback is optional; an unreadable one adds nothing
+        }
+        const ids = new Set(this.fallback.map((x) => x?.id));
+        for (const entry of normalizeBindings(parsed))
+            if (typeof entry?.id === 'string' && !ids.has(entry.id) && !isPlaceholder?.(entry))
+                this.fallback.push(entry);
+        return this;
+    }
+    primary(name) {
+        return this.list.find((x) => x.name === name || x.id === name);
+    }
+    /**
+     * The fallback row whose `id` is `name`. A row whose key is its own id
+     * (`{ id: 'drive', resourceKey: 'drive' }`, what an offline compile writes) is
+     * a placeholder, not an answer, so it is skipped: the label rules then judge
+     * `drive` against the author's bindings.json as they would without a fallback.
+     */
+    fallbackRow(name) {
+        return this.fallback.find((x) => x.id === name && (x.resourceKey ?? x.default) !== name);
+    }
+    /**
+     * True when only a fallback row answers `name`: the primary registry does not,
+     * and a fallback row's `id` is exactly `name`. The label rules
+     * (`bindingLabelRefusal`) accept such a label as is.
+     */
+    fromFallback(name) {
+        if (!name)
+            return false;
+        return this.primary(name) === undefined && this.fallbackRow(name) !== undefined;
+    }
+    /** Resolve by binding `name` or `id` (fallback rows: `id` only); returns its resourceKey (or default). */
     resolve(name) {
         if (!name)
             return undefined;
-        const b = this.list.find((x) => x.name === name || x.id === name);
+        const b = this.primary(name) ?? this.fallbackRow(name);
         if (!b)
             return undefined;
         return (b.resourceKey ?? b.default);
     }
-    /** Every symbolic name the file declares — what an author CAN write in `connection:` / `folder:`. */
+    /** Every symbolic name the bindings.json declares — what an author CAN write in `connection:` / `folder:`. Fallback rows are not included. */
     declared() {
         const names = [];
         for (const b of this.list) {
@@ -29,13 +91,13 @@ export class Bindings {
         }
         return names;
     }
-    /** The full binding entry by `name` or `id` — for consumers that emit a binding
+    /** The full binding entry by `name` or `id` (fallback rows: `id` only) — for consumers that emit a binding
      * registry + `=bindings.<id>` refs (the Case caseplan) rather than inlining the
      * resourceKey (the Flow node). */
     entry(name) {
         if (!name)
             return undefined;
-        return this.list.find((x) => x.name === name || x.id === name);
+        return (this.primary(name) ?? this.fallbackRow(name));
     }
 }
 /**

package/dist/core/connector-inputs.d.ts

@@ -46,6 +46,8 @@ export interface ConnectorInputOpts {
 }
 /** Flow's dialect, re-exported so `serialize.ts` need not reach past this module. */
 export { FLOW_EXPR_DIALECT } from './connector-checks.js';
+/** A required connector input left empty — the one draft code with no error class of its own. */
+export declare const CONNECTOR_INPUT_MISSING = "CONNECTOR_INPUT_MISSING";
 /**
  * What `compile` would refuse these connector inputs with, or `undefined` when it
  * would accept them — the SAME code path `buildConnectorInputs` runs at emit time,

package/dist/core/connector-inputs.js

@@ -30,6 +30,8 @@ export { FLOW_EXPR_DIALECT } from './connector-checks.js';
 import { FLOW_EXPR_DIALECT as FLOW_DIALECT } from './connector-checks.js';
 import { ownEntry } from './own-entry.js';
 import { isRecord } from './node-envelope.js';
+/** A required connector input left empty — the one draft code with no error class of its own. */
+export const CONNECTOR_INPUT_MISSING = 'CONNECTOR_INPUT_MISSING';
 /**
  * Validate a connector's activity inputs against its declared field list and
  * return them ROUTED to the wire slots the platform reads. Catches the three

package/dist/core/nodes/node-type.d.ts

@@ -106,6 +106,8 @@ export interface FactoryCall {
     readonly factory: string;
     readonly positional?: readonly string[];
     readonly options?: ReadonlyArray<readonly [name: string, source: string | undefined]>;
+    /** A note for the reader, written as a block comment after the call (the artifact escapes it). */
+    readonly comment?: string;
 }
 /** The contexts an artifact lends its node types, one per job. */
 export interface ArtifactContexts {
@@ -131,8 +133,11 @@ export interface NodeType<Spec, Serialized, Ctx extends ArtifactContexts> {
      * Whether the node has an error port. A `bundled` type must omit it — the answer
      * is the definition's, at this version. A `per-tenant` type must declare it,
      * because there is no definition to ask. The registry refuses either mistake.
+     * Serialize passes the definition the type supplied as `definition`, for a type
+     * whose definition comes from outside the SDK (a connector's, from its
+     * library); check, which has no definition, passes none.
      */
-    readonly errorPort?: boolean | ((spec: Spec) => boolean);
+    readonly errorPort?: boolean | ((spec: Spec, definition?: unknown) => boolean);
     /** Spec → the node's type-owned fields. The artifact still owns id, label, layout, edges and dedupe. */
     serialize(spec: Spec, ctx: Ctx['serialize']): Serialized;
     /** The lift: one serialized node → the spec it came from, or `undefined` when it is not this type's. */

package/dist/core/nodes/versioned.d.ts

@@ -33,6 +33,13 @@ Impl extends NodeType<Spec, Serialized, Ctx> = NodeType<Spec, Serialized, Ctx>>
      * exact name sit under the prefix as long as this rejects it.
      */
     typeNameMatches?(typeName: string): boolean;
+    /**
+     * One implementation answers for every version: the definition the type
+     * supplies names the node's version, as a connector operation's library entry
+     * does (1.0.0 for most, 4.0.0 for some). The registry then neither defaults nor
+     * refuses a `{ version }`; serialize holds the pin to that definition.
+     */
+    readonly versionedByDefinition?: boolean;
     readonly factory: string;
     /** The version used when the author names none. Changing it is a breaking change. */
     readonly defaultVersion: string;

package/dist/core/nodes/versioned.js

@@ -25,6 +25,11 @@ export function asVersioned(t) {
  * node type's bug, not the author's, and throws as an internal SDK error.
  */
 export function resolveVersion(t, spec, requested, where) {
+    if (t.versionedByDefinition) {
+        const only = ownEntry(t.versions, t.defaultVersion);
+        if (only)
+            return only;
+    }
     const selected = requested === undefined ? t.select?.(spec) : undefined;
     const version = requested ?? selected ?? t.defaultVersion;
     const impl = ownEntry(t.versions, version);
@@ -63,6 +68,12 @@ export function resolveVersion(t, spec, requested, where) {
  * implementation.
  */
 export function resolveVersionCarried(t, spec, requested, where, carried) {
+    // The definition names the version (see versionedByDefinition): a pin is the
+    // definition's to accept or refuse, not the registry's.
+    if (t.versionedByDefinition) {
+        const impl = resolveVersion(t, spec, undefined, where);
+        return { impl, version: requested ?? impl.version };
+    }
     if (requested !== undefined && !ownEntry(t.versions, requested)) {
         const def = carried?.(t.typeName, requested);
         if (def !== undefined) {