@uipath/maestro-builder-sdk 6.8.4 → 6.8.6

package/dist/api-index.md

@@ -201,7 +201,7 @@ could hand you spans for a version you do not have.
 | `QueueItemInputs` | interface | `dist/core/actions.d.ts:1950-2018` | Option shapes | 10 field(s) |
 | `QueuePriority` | type | `dist/core/actions.d.ts:1948-1949` | Supporting types | The three priorities an Orchestrator queue item can carry. |
 | `ran` | function | `dist/core/expr.d.ts:90-136` | Expressions and types | Did this step run? |
-| `rawNode` | function | `dist/core/node-classes.d.ts:180-234` | Supporting types | Place a node this SDK has no factory for, carrying its definition verbatim (`uipath.exotic.thing@2.1` and the manifest… |
+| `rawNode` | function | `dist/core/node-classes.d.ts:180-242` | Supporting types | Place a node this SDK has no factory for, carrying its definition verbatim (`uipath.exotic.thing@2.1` and the manifest… |
 | `RawReference` | type | `dist/core/lookups.d.ts:190-198` | Supporting types |  |
 | `refuseLookupToken` | function | `dist/core/lookups.d.ts:207-226` | Generated descriptors | Refuse a lookup token where the family cannot resolve one. |
 | `RemoteA2aToolRef` | interface | `dist/core/actions.d.ts:1649-1669` | Supporting types | A remote A2A (agent-to-agent) endpoint the agent may delegate to. |

package/dist/check-cli.js

@@ -6,15 +6,15 @@
  * Prints diagnostics; exits non-zero if any errors.
  */
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { check } from './check.js';
-import { Library } from './library.js';
+import { eventResolveErrorFor, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { connectorInputErrors } from './serialize.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
-import { resolveLibraryDir } from './registry/cache.js';
+/** Flags that take a value, so the value is never read as the source argument. */
+const VALUE_FLAGS = new Set(['--library', '--bindings', '--connectors-local']);
 /**
  * Library lookups for the checks whose facts live in the connector corpus:
  * event parameters and measured list envelopes.
@@ -23,33 +23,30 @@ import { resolveLibraryDir } from './registry/cache.js';
  * function of the built flow — with no library it simply cannot know whether an
  * empty `where` is correct, so it fails open (a warning, not an error). Given a
  * library, `compile` and `check` make the same call with the facts in hand.
- * `--library` mirrors compile-cli's flag and default.
+ * `--library` and `--connectors-local` mirror compile-cli's flags and defaults,
+ * through the same `openCliLibrary`.
  */
 function checkOpts(argv) {
-    const flag = argv.indexOf('--library');
-    const libDir = resolveLibraryDir(flag >= 0 ? argv[flag + 1] : undefined);
     // bindings.json beside the source, exactly as compile-cli finds it — so the
     // own-name refusal compile would raise is reported here first.
     const bindFlag = argv.indexOf('--bindings');
     const bindFile = bindFlag >= 0 ? argv[bindFlag + 1] : (existsSync('bindings.json') ? 'bindings.json' : undefined);
     const bindings = bindFile ? new Bindings(bindFile) : undefined;
-    if (!libDir || !existsSync(join(libDir, 'index.json')))
-        return bindings ? { bindings } : {};
     // The overlay matters here as much as it does for compile: `resolutions.json`
     // lives in it, and without it every already-resolved lookup would be reported
     // as still owed — telling the author to re-run a `prepare` they already ran.
-    const overlayDir = existsSync(join('connectors-local', 'index.json'))
-        ? 'connectors-local'
-        : undefined;
-    const library = new Library(libDir, { overlayDir });
+    const library = openCliLibrary(argv);
+    if (!library)
+        return bindings ? { bindings } : {};
     return {
+        eventResolveError: eventResolveErrorFor(library),
         eventParams: (connector, event, object) => {
             try {
                 return library.eventParameterFields(connector, event, object);
             }
             catch {
-                // An unresolvable operation is EVENT_UNKNOWN's business (compile reports
-                // it against the real library); here it just means "unknown".
+                // An unresolvable operation is EVENT_UNKNOWN's business, reported from
+                // `eventResolveError` above; here it just means "unknown".
                 return undefined;
             }
         },
@@ -96,9 +93,9 @@ function checkOpts(argv) {
     };
 }
 export async function run(argv) {
-    const arg = argv.find((a) => !a.startsWith('--')) ?? argv[0];
+    const arg = argv.find((a, i) => !a.startsWith('--') && !VALUE_FLAGS.has(argv[i - 1])) ?? argv[0];
     if (!arg || arg === '-h' || arg === '--help') {
-        console.error('usage: check [--library <dir>] [--bindings <file>] <flow.ts | BaseName>');
+        console.error('usage: check [--library <dir>] [--connectors-local <dir>] [--bindings <file>] <flow.ts | BaseName>');
         return 2;
     }
     const file = resolveFlowFile(arg);

package/dist/check.d.ts

@@ -75,6 +75,26 @@ export interface CheckOpts {
      * and cannot be slowed down by one.
      */
     eventParams?: (connector: string, event: string, object?: string) => EventParamFields | undefined;
+    /**
+     * What `compile` would refuse a connector event subscription with, or
+     * `undefined` when the library resolves it. `kind` is the node form compile
+     * asks for: `trigger` for `onEvent` (the flow's trigger and every entry point),
+     * `event` for `waitForEvent`. Supplied by the CLIs from the same
+     * `library.resolveEvent(kind, connector, event, version, object)` call
+     * `serialize` makes (`eventResolveErrorFor` in `cli-library.ts`), so the two
+     * cannot disagree; omitted (no library) → not checked.
+     *
+     * Before this hook `check` could only warn EVENT_UNPREPARED here, because
+     * `eventParams` answers `undefined` for "cannot resolve" and for "no facts"
+     * alike: it printed `0 error(s)` on a source `compile` then refused
+     * (2026-09-23, `skill-flow-datafabric-trigger-lifecycle`, v2 commands 31 and 46).
+     */
+    eventResolveError?: (kind: 'trigger' | 'event', subscription: {
+        connector: string;
+        event: string;
+        version?: string;
+        object?: string;
+    }) => string | undefined;
     /**
      * Resolve a connector event's FILTERABLE field names — the vocabulary a
      * `filters` leaf may name — sourced the same way as `eventParams`. A GENERIC

package/dist/check.js

@@ -15,7 +15,7 @@ import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from '
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
-import { prepareCommand } from './core/cli-spelling.js';
+import { prepareCommand, resolveFlagArg } from './core/cli-spelling.js';
 export function check(built, opts = {}) {
     return checkFlow(built, [], opts);
 }
@@ -529,7 +529,7 @@ function checkFlow(built, ancestors, opts = {}) {
                         ...(suggestion ? { suggestion } : {}),
                     });
                     checkEventSubscription(s.spec.subscription, `waitForEvent "${stepName}"`, push('error'), push('warning'), eventParamsFor(s.spec.subscription, opts));
-                    checkEventResolution(s.spec.subscription, `waitForEvent "${stepName}"`, opts, push('error'), push('warning'), eventParamsFor(s.spec.subscription, opts));
+                    checkEventResolution(s.spec.subscription, `waitForEvent "${stepName}"`, 'event', opts, push('error'), push('warning'), eventParamsFor(s.spec.subscription, opts));
                 }
                 if (s.spec.kind === 'subflow') {
                     // Only a real child goes in the map: a missing one is reported by
@@ -1264,6 +1264,9 @@ function checkFlow(built, ancestors, opts = {}) {
 function checkConnectorLookups(step, spec, opts, diags) {
     const specs = opts.lookups?.(spec.key, spec.action, spec.version, spec.object);
     const resolutions = opts.resolutions ?? {};
+    // One LOOKUP_LITERAL_ID per field: a multiselect of three pasted ids is one
+    // mistake with one remedy, not three.
+    const literalWarned = new Set();
     const visit = (value, path) => {
         if (isLookupToken(value)) {
             // A match key the field does not declare is certainly wrong, and the
@@ -1304,7 +1307,17 @@ function checkConnectorLookups(step, spec, opts, diags) {
             return;
         }
         if (Array.isArray(value)) {
-            value.forEach((v, i) => visit(v, [...path, String(i)]));
+            // An element is named by the WIRE name the lookup table is keyed on —
+            // `users[*]`, `contacts[*].id` — not by its index. `users.0` matched no
+            // spec, so a pasted id, a token with a bad match key, or a runtime value
+            // inside a multiselect passed every rule below unseen. A name that already
+            // is the array's (a flat `'users[*]'` key, or a field typed as an array)
+            // stays as it is.
+            const last = path[path.length - 1] ?? '';
+            const element = last.endsWith('[*]') || specs?.[path.join('.')]
+                ? path
+                : [...path.slice(0, -1), `${last}[*]`];
+            value.forEach((v) => visit(v, element));
             return;
         }
         if (value && typeof value === 'object' && !(value instanceof Expr)) {
@@ -1329,6 +1342,9 @@ function checkConnectorLookups(step, spec, opts, diags) {
         const literal = value instanceof Expr ? value.value : value;
         if (typeof literal !== 'string')
             return;
+        if (literalWarned.has(field))
+            return;
+        literalWarned.add(field);
         const { target, call } = lookupPhrases(field, lookup, spec);
         diags.push({
             level: 'warning',
@@ -1340,7 +1356,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
                 + `compile nor deploy can tell. Write what you mean and resolve it late:\n`
                 + `  ${call}\n`
                 + `then record the value once with \`${prepareCommand(spec.key)} `
-                + `${spec.action} --resolve ${field}:${lookup.by[0] ?? 'id'}=<value>\`.`,
+                + `${spec.action} --resolve ${resolveFlagArg(field, lookup.by[0] ?? 'id', '<value>')}\`.`,
             step,
         });
     };
@@ -1557,7 +1573,7 @@ function runtimeLookupDiagnostic(step, spec, field, lookup, value) {
         + `neither compile nor validate can tell. Resolve the value you know instead:\n`
         + `  ${call}\n`
         + `then record it once with \`${prepareCommand(spec.key, spec.action)} `
-        + `--resolve ${field}:${lookup.by[0] ?? 'id'}=<value>\`; or read the id from a step whose `
+        + `--resolve ${resolveFlagArg(field, lookup.by[0] ?? 'id', '<value>')}\`; or read the id from a step whose `
         + `output returned one (\`${lookup.value}\`).`
         + (isEmail
             ? `\n\`${single.raw}\` reads \`${leaf}\`, an e-mail address, not a \`${target}\`.`
@@ -1939,12 +1955,18 @@ function eventParamsFor(subscription, opts) {
 }
 /**
  * The event-side resolution rules — the trigger twin of `checkConnectorLookups`,
- * plus two rules with no activity counterpart:
+ * plus three rules with no activity counterpart:
  *
- * - `EVENT_UNPREPARED` — a library resolver is present and knows NOTHING about
- *   this event, not even identity: the fallback case for a connector the
- *   shipped library was not generated against. Prints the one command that
- *   makes the event checkable.
+ * - `EVENT_UNKNOWN` — an ERROR: a library is loaded and it cannot resolve the
+ *   subscription, so `compile` will refuse it. The message is the resolver's
+ *   own (`eventResolveError`), the same text compile throws. Checked first; when
+ *   it fires, EVENT_UNPREPARED and the filter rules below are skipped for this
+ *   subscription, since there is no entry for them to read.
+ * - `EVENT_UNPREPARED` — the event RESOLVES but the library knows nothing
+ *   about its parameters (or no `eventResolveError` resolver was supplied):
+ *   the fallback case for a connector the shipped library was not generated
+ *   against. A warning, because compile still succeeds. Prints the one
+ *   command that makes the event checkable.
  * - `EVENT_FILTER_UNKNOWN_FIELD` — a filter leaf naming a field outside the
  *   prepared vocabulary is an ERROR, not a warning, because the platform's own
  *   configure DROPS an unmatched leaf and reports Success: the deployed
@@ -1956,7 +1978,7 @@ function eventParamsFor(subscription, opts) {
  * (compile repeats it as the hard failure), with the recorded answer looked up
  * under the event-form node type — the form `prepare` stores.
  */
-function checkEventResolution(subscription, where, opts, error, warn, eventParams) {
+function checkEventResolution(subscription, where, kind, opts, error, warn, eventParams) {
     const sub = subscription;
     if (!sub || typeof sub.connector !== 'string' || typeof sub.event !== 'string'
         || sub.connector === '' || sub.event === '')
@@ -1967,6 +1989,18 @@ function checkEventResolution(subscription, where, opts, error, warn, eventParam
     // by interpolating them into template literals, which accept anything.
     const connectorKey = sub.connector;
     const eventName = sub.event;
+    // Exactly what `serialize` passes to `resolveEvent` — `sub.version` and
+    // `sub.object` as the author wrote them — so the verdict is compile's.
+    const unresolved = opts.eventResolveError?.(kind, {
+        connector: connectorKey,
+        event: eventName,
+        ...(typeof sub.version === 'string' ? { version: sub.version } : {}),
+        ...(typeof sub.object === 'string' ? { object: sub.object } : {}),
+    });
+    if (unresolved !== undefined) {
+        error('EVENT_UNKNOWN', `${where}: ${unresolved}`);
+        return;
+    }
     const object = typeof sub.object === 'string' && sub.object !== '' ? sub.object : undefined;
     if (eventParams?.objectUnprepared && object) {
         // The generic template answers for every object, so resolution SUCCEEDS
@@ -2243,7 +2277,7 @@ function checkTrigger(spec, diags, opts = {}) {
     if (spec?.kind === 'event') {
         const sub = spec.subscription;
         checkEventSubscription(sub, 'trigger', at, push('warning'), eventParamsFor(sub, opts));
-        checkEventResolution(sub, 'trigger', opts, at, push('warning'), eventParamsFor(sub, opts));
+        checkEventResolution(sub, 'trigger', 'trigger', opts, at, push('warning'), eventParamsFor(sub, opts));
         return;
     }
     // manual() is the explicit spelling of the default — nothing to validate.

package/dist/cli/commands/flow.js

@@ -25,6 +25,7 @@ export function registerFlowCommands(program) {
         .option('--source', 'check authored TypeScript')
         .option('--compiled', 'check the emitted artifact')
         .option('--library <dir>', 'connector library directory')
+        .option('--connectors-local <dir>', 'connection-resolved connector overlay')
         .option('--json', 'print compiled-check diagnostics as JSON')
         .option('--uip', 'resolve missing schemas with the UiPath CLI')
         .option('--max-errors <count>', 'stop after this many compiled-check errors')
@@ -50,6 +51,7 @@ export function registerFlowCommands(program) {
         if (mode === 'source') {
             const argv = [input];
             addValue(argv, '--library', options.library);
+            addValue(argv, '--connectors-local', options.connectorsLocal);
             await invoke('flow check', () => loadTool(import.meta.url, '../../check-cli.js'), argv);
             return;
         }

package/dist/cli-library.d.ts

@@ -0,0 +1,21 @@
+import type { CheckOpts } from './check.js';
+import { Library } from './library.js';
+/**
+ * The library for this invocation, or `undefined` when there is none.
+ *
+ * `--library <dir>`, else `$FLOW_SDK_LIBRARY_JSON`, else the cache `registry
+ * pull` filled (`resolveLibraryDir`). The overlay is `--connectors-local <dir>`,
+ * else `./connectors-local` when it has an `index.json` — the directory
+ * `registry prepare` writes by default.
+ */
+export declare function openCliLibrary(argv: readonly string[]): Library | undefined;
+/**
+ * `check`'s EVENT_UNKNOWN verdict: the message `library.resolveEvent` throws
+ * for a subscription, or `undefined` when it resolves.
+ *
+ * This is the call `serialize` makes for `onEvent` (kind `trigger`, for the
+ * flow's trigger and each entry point) and for `waitForEvent` (kind `event`),
+ * with the subscription's own `version` and `object`, so check reports an error
+ * exactly when compile would throw, with the same text.
+ */
+export declare function eventResolveErrorFor(library: Library): NonNullable<CheckOpts['eventResolveError']>;

package/dist/cli-library.js

@@ -0,0 +1,56 @@
+/**
+ * cli-library — the connector library a flow CLI opens, and the event verdict
+ * `check` shares with `compile`.
+ *
+ * `check-cli` and `compile-cli` used to open the library each in their own way:
+ * compile honoured `--connectors-local <dir>`, check ignored the flag and only
+ * auto-detected `./connectors-local`. As long as check only WARNED from the
+ * library that was harmless. Now check reports EVENT_UNKNOWN as an ERROR when
+ * the library cannot resolve an event, so a different library would make check
+ * refuse a source compile accepts. Both CLIs open it here instead.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { Library } from './library.js';
+import { resolveLibraryDir } from './registry/cache.js';
+/** The value after `name` in `argv`, or `undefined`. */
+function flagValue(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+/**
+ * The library for this invocation, or `undefined` when there is none.
+ *
+ * `--library <dir>`, else `$FLOW_SDK_LIBRARY_JSON`, else the cache `registry
+ * pull` filled (`resolveLibraryDir`). The overlay is `--connectors-local <dir>`,
+ * else `./connectors-local` when it has an `index.json` — the directory
+ * `registry prepare` writes by default.
+ */
+export function openCliLibrary(argv) {
+    const libDir = resolveLibraryDir(flagValue(argv, '--library'));
+    if (!libDir || !existsSync(join(libDir, 'index.json')))
+        return undefined;
+    const overlayDir = flagValue(argv, '--connectors-local')
+        ?? (existsSync(join('connectors-local', 'index.json')) ? 'connectors-local' : undefined);
+    return new Library(libDir, { overlayDir });
+}
+/**
+ * `check`'s EVENT_UNKNOWN verdict: the message `library.resolveEvent` throws
+ * for a subscription, or `undefined` when it resolves.
+ *
+ * This is the call `serialize` makes for `onEvent` (kind `trigger`, for the
+ * flow's trigger and each entry point) and for `waitForEvent` (kind `event`),
+ * with the subscription's own `version` and `object`, so check reports an error
+ * exactly when compile would throw, with the same text.
+ */
+export function eventResolveErrorFor(library) {
+    return (kind, sub) => {
+        try {
+            library.resolveEvent(kind, sub.connector, sub.event, sub.version, sub.object);
+            return undefined;
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+    };
+}

package/dist/compile-cli.js

@@ -22,8 +22,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars, connectorInputErrors } from './serialize.js';
 import { check } from './check.js';
-import { Library } from './library.js';
-import { resolveLibraryDir } from './registry/cache.js';
+import { eventResolveErrorFor, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
 import { connectionResources, mergeBindingsV2, readBindingsV2 } from './bindings-v2.js';
@@ -50,14 +49,11 @@ export async function run(argv) {
     // --library, else $FLOW_SDK_LIBRARY_JSON, else the shared cache `registry pull`
     // filled. Resolving through one helper is what stops `pull` and `compile`
     // disagreeing about where the library is — they did, and a pulled library was
-    // invisible to this command.
-    const libDir = resolveLibraryDir(opt(argv, '--library'));
-    const bindFile = opt(argv, '--bindings') ?? (existsSync('bindings.json') ? 'bindings.json' : undefined);
-    // A `prepare-connector`/`prepare-trigger` overlay: auto-detected next to the
-    // flow (like bindings.json), it shadows the baked library with full,
-    // connection-resolved field schemas. See core/library.ts (LibraryOpts.overlayDir).
-    const overlayDir = opt(argv, '--connectors-local')
-        ?? (existsSync(join('connectors-local', 'index.json')) ? 'connectors-local' : undefined);
+    // invisible to this command. The `prepare-connector`/`prepare-trigger` overlay
+    // is `--connectors-local`, else `./connectors-local` (like bindings.json); it
+    // shadows the baked library with full, connection-resolved field schemas. See
+    // core/library.ts (LibraryOpts.overlayDir). `check-cli` opens it the same way.
+    //
     // Only load the library when it's actually present; flows without connectors
     // (e.g. HTTP-only) then compile fine even if the connector cache isn't built.
     // A connector action with no library resolves to a clear error in serialize().
@@ -66,11 +62,16 @@ export async function run(argv) {
     // event operation declares any event parameters) can only be answered from the
     // library, and answering it from an assumption instead is what made
     // EVENT_NO_SCOPE an error for HTTP Webhook, whose only correct `where` is empty.
-    const library = libDir && existsSync(join(libDir, 'index.json')) ? new Library(libDir, { overlayDir }) : undefined;
+    const library = openCliLibrary(argv);
+    const bindFile = opt(argv, '--bindings') ?? (existsSync('bindings.json') ? 'bindings.json' : undefined);
     const bindings = new Bindings(bindFile);
     if (!noCheck) {
         const diags = check(built, library
             ? {
+                // The refusal serialize() would throw for an event it cannot resolve,
+                // printed as `✗ [EVENT_UNKNOWN]` before stopping instead of hiding
+                // behind "1 error(s); not emitting".
+                eventResolveError: eventResolveErrorFor(library),
                 eventParams: (connector, event) => {
                     try {
                         return library.eventParameterFields(connector, event);

package/dist/core/cli-spelling.d.ts

@@ -37,3 +37,13 @@ export declare function cliSpelling(env?: CliSpellingEnv): string;
  * ```
  */
 export declare function prepareCommand(...args: string[]): string;
+/**
+ * The argument of one `--resolve <field>:<by>=<value>`, single-quoted when the
+ * shell would otherwise mangle it.
+ *
+ * @param field - The lookup field's wire name, e.g. `channel` or `users[*]`.
+ * @param by - The match key, e.g. `profile.email`.
+ * @param value - The value to match, or the `<value>` placeholder.
+ * @returns `channel:profile.email=d@x.com` as is; `'users[*]:profile.real_name=Coder Evals'` quoted.
+ */
+export declare function resolveFlagArg(field: string, by: string, value: string): string;

package/dist/core/cli-spelling.js

@@ -60,3 +60,27 @@ export function cliSpelling(env = ambientEnv()) {
 export function prepareCommand(...args) {
     return [cliSpelling(), 'registry', 'prepare', ...args.filter(Boolean)].join(' ');
 }
+/**
+ * Characters that make a `--resolve` argument unsafe to paste unquoted. `[*]`
+ * is a shell glob (every multiselect wire name, `users[*]`), whitespace splits
+ * a real name (`Coder Evals`) into two arguments, and quotes, `$`, backslash
+ * and the control operators change what the shell hands over. The `<value>`
+ * placeholder a template prints is stripped before the test, so a template
+ * with nothing else unsafe keeps its bytes.
+ */
+const SHELL_UNSAFE = /[\s'"`$\\[\]*?;&|(){}!#~<>]/;
+/**
+ * The argument of one `--resolve <field>:<by>=<value>`, single-quoted when the
+ * shell would otherwise mangle it.
+ *
+ * @param field - The lookup field's wire name, e.g. `channel` or `users[*]`.
+ * @param by - The match key, e.g. `profile.email`.
+ * @param value - The value to match, or the `<value>` placeholder.
+ * @returns `channel:profile.email=d@x.com` as is; `'users[*]:profile.real_name=Coder Evals'` quoted.
+ */
+export function resolveFlagArg(field, by, value) {
+    const arg = `${field}:${by}=${value}`;
+    if (!SHELL_UNSAFE.test(arg.replaceAll('<value>', '')))
+        return arg;
+    return `'${arg.replaceAll("'", `'\\''`)}'`;
+}

package/dist/core/library.d.ts

@@ -402,6 +402,26 @@ export declare class Library {
      * that. It resorted to grepping the library's JSON out of `node_modules`.
      */
     private describeMiss;
+    /** Every direct operation id under `prefix` (no further dot), across layers, sorted and de-duplicated. */
+    private opsUnder;
+    /** Whether any layer indexes `nodeType` (at `version`, when one is asked for). */
+    private carries;
+    /** The connector key is in no entry at all. */
+    private noConnector;
+    /**
+     * The event half of {@link describeMiss}: which of the connector's EVENTS the
+     * library carries, read from BOTH namespaces.
+     *
+     * Both, because the library stores almost every event in one form only: the
+     * baseline snapshot of 2026-09-23 (`2a4405dd…`) has 994 `.event.` entries and 4
+     * `.trigger.` ones, and a start trigger resolves from its `.event.` sibling
+     * ({@link resolveEvent}). Reading the asked namespace alone answered `No
+     * connector "uipath-uipath-dataservice"` for a typo'd `onEvent` event on a
+     * connector whose events were all right there, and the same words for a
+     * connector present with eight actions and no events at all (2026-09-23 eval,
+     * `skill-flow-datafabric-trigger-lifecycle`, v2 commands 45/46).
+     */
+    private describeEventMiss;
     /**
      * Resolve the op WITHIN one layer, selecting the entry by `objectName` for a
      * GENERIC operation. Returns undefined when the layer does not carry the op;

package/dist/core/library.js

@@ -8,6 +8,7 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { prepareCommand } from './cli-spelling.js';
 import { loadListEnvelopes, lookupListEnvelope } from './list-envelope.js';
 import { lookupSpecOf } from './lookups.js';
 import { loadInvariantCollections, loadLookupResolutions } from './lookup-store.js';
@@ -245,11 +246,18 @@ export class Library {
             // own `registry get` answers for both forms (see `deriveTriggerForm`).
             if (kind !== 'trigger')
                 throw error;
+            const siblingType = `uipath.connector.event.${key}.${event}`;
             let sibling;
             try {
-                sibling = this.resolveType(`uipath.connector.event.${key}.${event}`, version, objectName);
+                sibling = this.resolveType(siblingType, version, objectName);
             }
-            catch {
+            catch (siblingError) {
+                // The wait form IS in the library and refused the request itself — a
+                // GENERIC event with no `object`, or a disagreeing one. That refusal is
+                // the true answer; replacing it with the start form's "not in library"
+                // told the author the connector was missing.
+                if (this.carries(siblingType, version))
+                    throw siblingError;
                 throw error;
             }
             rc = deriveTriggerForm(sibling, nodeType);
@@ -528,7 +536,7 @@ export class Library {
                 + `\`…connector.trigger.…\` starts a flow, \`…connector.event.…\` waits mid-flow.`
             : '';
         throw new Error(`connector not in library: ${nodeType}${version ? '@' + version : ''}.${hint}`
-            + this.describeMiss(nodeType));
+            + this.describeMiss(nodeType, version, objectName));
     }
     /**
      * Turn a lookup miss into something actionable: which operations this connector
@@ -541,7 +549,7 @@ export class Library {
      * `connector not in library: …send-mail-v2.` said nothing that would reveal
      * that. It resorted to grepping the library's JSON out of `node_modules`.
      */
-    describeMiss(nodeType) {
+    describeMiss(nodeType, version, objectName) {
         // `uipath.connector.<key>.<op>`, or `uipath.connector.(trigger|event).<key>.<ev>`
         // for the two event namespaces. No connector key contains a dot.
         const parts = nodeType.split('.');
@@ -550,23 +558,12 @@ export class Library {
         const asked = (eventNs ? parts.slice(4) : parts.slice(3)).join('.');
         if (!key)
             return '';
-        const prefix = eventNs ? `uipath.connector.${parts[2]}.${key}.` : `uipath.connector.${key}.`;
-        const ops = [...new Set(this.layers.flatMap((l) => l.entries
-                .map((e) => String(e.nodeType ?? ''))
-                .filter((t) => t.startsWith(prefix))
-                .map((t) => t.slice(prefix.length))))].sort();
         const where = ` Searched: ${this.layers.map((l) => l.dir).join(', ')}.`;
-        if (!ops.length) {
-            const keys = [...new Set(this.layers.flatMap((l) => l.entries.map((e) => {
-                    const p = String(e.nodeType ?? '').split('.');
-                    return (p[2] === 'trigger' || p[2] === 'event' ? p[3] : p[2]) ?? '';
-                })))].filter(Boolean).sort();
-            const near = nearest(key, keys);
-            return ` No connector "${key}" in the library (${keys.length} indexed).`
-                + (near && near !== key ? ` Closest: ${near}.` : '')
-                + where
-                + ' If the connector is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
-        }
+        if (eventNs)
+            return this.describeEventMiss(parts[2], key, asked, where, version, objectName);
+        const ops = this.opsUnder(`uipath.connector.${key}.`);
+        if (!ops.length)
+            return this.noConnector(key, where);
         const near = asked ? nearest(asked, ops) : undefined;
         const listed = ops.length <= 12
             ? `Operations: ${ops.join(', ')}.`
@@ -580,6 +577,86 @@ export class Library {
             + ' — `uip maestro case spec` reports the latter, and the two can differ.'
             + ' If the operation is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
     }
+    /** Every direct operation id under `prefix` (no further dot), across layers, sorted and de-duplicated. */
+    opsUnder(prefix) {
+        return [...new Set(this.layers.flatMap((l) => l.entries
+                .map((e) => String(e.nodeType ?? ''))
+                .filter((t) => t.startsWith(prefix))
+                .map((t) => t.slice(prefix.length))
+                .filter((op) => op !== '' && !op.includes('.'))))].sort();
+    }
+    /** Whether any layer indexes `nodeType` (at `version`, when one is asked for). */
+    carries(nodeType, version) {
+        return this.layers.some((l) => l.entries.some((e) => e.nodeType === nodeType && (!version || e.version === version)));
+    }
+    /** The connector key is in no entry at all. */
+    noConnector(key, where) {
+        const keys = [...new Set(this.layers.flatMap((l) => l.entries.map((e) => {
+                const p = String(e.nodeType ?? '').split('.');
+                return (p[2] === 'trigger' || p[2] === 'event' ? p[3] : p[2]) ?? '';
+            })))].filter(Boolean).sort();
+        const near = nearest(key, keys);
+        return ` No connector "${key}" in the library (${keys.length} indexed).`
+            + (near && near !== key ? ` Closest: ${near}.` : '')
+            + where
+            + ' If the connector is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
+    }
+    /**
+     * The event half of {@link describeMiss}: which of the connector's EVENTS the
+     * library carries, read from BOTH namespaces.
+     *
+     * Both, because the library stores almost every event in one form only: the
+     * baseline snapshot of 2026-09-23 (`2a4405dd…`) has 994 `.event.` entries and 4
+     * `.trigger.` ones, and a start trigger resolves from its `.event.` sibling
+     * ({@link resolveEvent}). Reading the asked namespace alone answered `No
+     * connector "uipath-uipath-dataservice"` for a typo'd `onEvent` event on a
+     * connector whose events were all right there, and the same words for a
+     * connector present with eight actions and no events at all (2026-09-23 eval,
+     * `skill-flow-datafabric-trigger-lifecycle`, v2 commands 45/46).
+     */
+    describeEventMiss(kind, key, asked, where, version, objectName) {
+        const starts = this.opsUnder(`uipath.connector.trigger.${key}.`);
+        const waits = this.opsUnder(`uipath.connector.event.${key}.`);
+        // A start trigger resolves from either form; a mid-flow wait needs the `.event.` form itself.
+        const usable = kind === 'trigger' ? [...new Set([...starts, ...waits])].sort() : waits;
+        const refresh = ' If the event is newer than the library, refresh it with `uip maestro flow registry pull --force`.';
+        if (usable.length) {
+            if (usable.includes(asked)) {
+                // Only a version can make a carried event miss here: every other refusal
+                // of a carried entry is thrown by the entry itself.
+                return ` Connector "${key}" carries event "${asked}", but not at version ${version ?? '(any)'}.`
+                    + ` Drop the version, or use one the library's index.json lists for it.` + where;
+            }
+            const onlyStart = kind === 'event' && starts.includes(asked);
+            const near = onlyStart ? undefined : nearest(asked, usable);
+            const listed = usable.length <= 12
+                ? `Events: ${usable.join(', ')}.`
+                : `Events (${usable.length}, first 12): ${usable.slice(0, 12).join(', ')}, … — `
+                    + `the full list is every \`nodeType\` under "${key}" in the library's index.json.`;
+            return ` Connector "${key}" is present but carries no event "${asked}"`
+                + (onlyStart
+                    ? ` that can be waited on: it is here only as a start trigger (\`uipath.connector.trigger.${key}.${asked}\`), `
+                        + `and \`waitForEvent\` needs its \`uipath.connector.event.\` form.`
+                    : '.')
+                + (near ? ` Closest: ${near}.` : '')
+                + ` ${listed}`
+                + where
+                + refresh;
+        }
+        if (starts.length) {
+            return ` Connector "${key}" carries only start triggers in this library (${starts.join(', ')}), `
+                + `and \`waitForEvent\` needs the \`uipath.connector.event.\` form.` + where + refresh;
+        }
+        const actions = this.opsUnder(`uipath.connector.${key}.`).length;
+        if (!actions)
+            return this.noConnector(key, where);
+        const prepare = prepareCommand(key, asked, ...(objectName ? ['--object', objectName] : []));
+        return ` Connector "${key}" is present (${actions} action${actions === 1 ? '' : 's'}) but this library carries `
+            + `no events for it.` + where
+            + ` Prepare the event against a live connection: ${prepare}. If prepare reports that the registry serves `
+            + `no event for "${key}" either (after \`uip maestro flow registry pull --force\`, if its catalog looks stale), `
+            + `refreshing the library will not add one: it is built from the same catalog.`;
+    }
     /**
      * Resolve the op WITHIN one layer, selecting the entry by `objectName` for a
      * GENERIC operation. Returns undefined when the layer does not carry the op;