@uipath/maestro-builder-sdk 6.14.5 → 6.15.0

package/dist/core/event-checks.js

@@ -0,0 +1,321 @@
+/**
+ * core/event-checks — the connector-EVENT rules, shared by every family that can
+ * subscribe to one.
+ *
+ * The activity twin is `core/connector-checks.ts`. These were Flow's, and like
+ * those they were never flow-shaped: both functions take the subscription as
+ * `unknown` and duck-type `{ connector, event, where, object, filters, version,
+ * connection }`, because that is all they need. BPMN's `.eventTrigger()` /
+ * `.waitForEvent()` node carries the same facts under its own names, and
+ * `bpmn/check.ts` adapts one to the other.
+ *
+ * What BPMN does NOT carry is `filters` — payload filtering is a Flow surface —
+ * so the `EVENT_FILTER_*` family simply does not fire there. The rules that do
+ * are the ones about the SUBSCRIPTION: whether it resolves at all, whether a
+ * generic event named its object, and whether its scope names parameters the
+ * operation actually declares. `skill-bpmn-outlook-waitfor-email` in
+ * `flow-v2-run-8` failed on exactly that last question.
+ */
+import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './lookups.js';
+import { prepareCommand } from './cli-spelling.js';
+import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
+import { EVENT_BYOA_UNVERIFIED, byoaUnverified } from './byoa.js';
+/**
+ * Ask the library what event parameters a subscription's operation declares.
+ * Returns `undefined` when the subscription is too broken to look up (its own
+ * diagnostics say so) or when no resolver was supplied — both mean "unknown", and
+ * unknown fails open.
+ */
+export function eventParamsFor(subscription, opts) {
+    if (!opts.eventParams)
+        return undefined;
+    const sub = subscription;
+    if (typeof sub?.connector !== 'string' || typeof sub?.event !== 'string')
+        return undefined;
+    if (sub.connector === '' || sub.event === '')
+        return undefined;
+    // A GENERIC event's schema is per OBJECT once the library carries baked
+    // per-object variants, so the object is part of the subscription's identity
+    // here. Without it the lookup asks for a node type that resolves to no
+    // single variant and answers "unknown", which reads as EVENT_UNPREPARED on
+    // an event the library actually knows.
+    const object = typeof sub.object === 'string' && sub.object !== ''
+        ? sub.object : undefined;
+    return opts.eventParams(sub.connector, sub.event, object);
+}
+/**
+ * The event-side resolution rules — the trigger twin of `checkConnectorLookups`,
+ * plus three rules with no activity counterpart:
+ *
+ * - `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_BYOA_UNVERIFIED` — an ERROR: the event only fires on a BYOA
+ *   (bring-your-own-app) connection, and the bound connection id has no record
+ *   of `prepare` having checked it (`core/byoa.ts` has the rule and when it
+ *   stays silent). A standard connection deploys and the trigger never fires;
+ *   the usual way in is binding the connection by preparing one of the
+ *   connector's ACTIONS, which checks nothing about BYOA. `compile` throws the
+ *   same text.
+ * - `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
+ *   trigger then fires on events the filter should exclude, silently. Matching
+ *   is case-sensitive, so the near-miss hint checks case first. When the
+ *   vocabulary is unknown or known-empty this stays quiet — fail open.
+ *
+ * Unresolved `where` lookups follow the activity rule exactly: a WARNING here
+ * (compile repeats it as the hard failure), with the recorded answer looked up
+ * under the event-form node type — the form `prepare` stores.
+ */
+export 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 === '')
+        return;
+    // Captured because the guard above narrows `sub.connector` / `sub.event` only
+    // in THIS scope: a property narrowing does not survive into the `filters`
+    // callback below, where they are `unknown` again. The old messages hid that
+    // 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;
+    const byoa = opts.eventFacts && byoaUnverified(where, { connector: connectorKey, event: eventName, ...(object ? { object } : {}), connection: sub.connection }, opts.eventFacts(connectorKey, eventName, object), opts.byoa, opts.bindings);
+    if (byoa)
+        error(EVENT_BYOA_UNVERIFIED, byoa);
+    if (eventParams?.objectUnprepared && object) {
+        // The generic template answers for every object, so resolution SUCCEEDS
+        // and nothing downstream notices that the object named here has no
+        // schema: no unprepared warning, and a filter vocabulary that fails open.
+        // That is the silent case this whole surface exists to remove, one level
+        // up from the activity it was first found on.
+        warn('OBJECT_UNPREPARED', `${where}: object \`${object}\` has no prepared schema for `
+            + `\`${sub.connector}\` \`${sub.event}\`, and this connector's objects come from `
+            + `the connection, so the library cannot carry one. Materialize it:\n`
+            + `  ${prepareCommand(connectorKey, eventName)} --object ${object}\n`
+            + `Until then its event parameters and filterable fields are unknown and `
+            + `nothing here can check them.`);
+    }
+    if (opts.eventParams && eventParams === undefined) {
+        warn('EVENT_UNPREPARED', `${where}: the library knows nothing about connector event \`${sub.connector}\` \`${sub.event}\` — `
+            + `its parameters and filterable fields cannot be verified offline. Prepare it against a live connection:\n`
+            + `  ${prepareCommand(connectorKey, eventName)}\n`
+            + `and re-run check: the prepared overlay makes this event checkable.`);
+    }
+    const resolutions = opts.resolutions ?? {};
+    const scope = sub.where && typeof sub.where === 'object'
+        ? Object.entries(sub.where) : [];
+    for (const [key, value] of scope) {
+        if (!isLookupToken(value))
+            continue;
+        if (resolvedValue(value, resolutions) !== undefined)
+            continue;
+        warn('LOOKUP_UNRESOLVED', `${where}: \`where.${key}\` ` + unresolvedLookupMessage(value)
+            + `\nCompile will fail until this is recorded.`);
+    }
+    const names = opts.eventFilterFields?.(sub.connector, sub.event, object);
+    if (names && names.length > 0 && Array.isArray(sub.filters)) {
+        const known = new Set(names);
+        sub.filters.forEach((leaf, i) => {
+            const { read } = readEventFilter(leaf);
+            if (!read || known.has(read.field))
+                return;
+            const caseSlip = names.find((n) => n.toLowerCase() === read.field.toLowerCase());
+            // A case slip is a mistake whatever the vocabulary's completeness — the
+            // platform matches case-sensitively, so `Subject` is dropped even where
+            // `subject` exists. An unrecognized name is only certainly wrong when
+            // the vocabulary is COMPLETE; where required selectors decide the field
+            // set and nothing can supply them, refusing a legal field would be the
+            // worse error, so it warns.
+            const selectors = eventParams?.selectors ?? [];
+            // A hybrid connector's custom filter fields are left for `prepare` BY
+            // DESIGN, so the baked list is a strict subset of the tenant's and a
+            // name outside it may be perfectly real. Erroring there tells the author
+            // the platform will drop a field it will actually honour, and the only
+            // way out is deleting a correct filter — "not in my snapshot" mistaken
+            // for "wrong", which is the trap CUSTOM_FIELDS_UNPREPARED was narrowed
+            // around for activities. Same shape here, and the same remedy: name the
+            // prepare that closes the gap.
+            if (eventParams?.customFieldsUnprepared && !caseSlip) {
+                warn('CUSTOM_FIELDS_UNPREPARED', `${where}: filters[${i}] names \`${read.field}\`, which is not in the `
+                    + `tenant-agnostic vocabulary for \`${sub.connector}\` \`${sub.event}\`. This `
+                    + `connector discovers CUSTOM FIELDS per connection, so the baked list is a `
+                    + `subset by design and this name may be a real field of yours. Prepare the `
+                    + `event against your connection to check it for real:\n`
+                    + `  ${prepareCommand(connectorKey, eventName)}`
+                    + `${object ? ` --object ${object}` : ''}\n`
+                    + `Baked fields: ${names.slice(0, 12).join(', ')}${names.length > 12 ? ', …' : ''}.`);
+                return;
+            }
+            // Same shape as the branch above, for the gap preparing cannot close.
+            // `customFieldsUnprepared` says "run prepare and this resolves";
+            // `filtersPartial` says "no call reaches these fields at all", so the
+            // remedy is the designer, not another command.
+            //
+            // Yields to the selector branch below, which reaches the same WARNING by
+            // a more specific route: where `project` / `issuetype` select the schema
+            // it can name them, and "these two values decide the field set" is more
+            // use to an author than "this connector reads its schema from the
+            // connection". Both are true of Jira; the named one is the better message.
+            if (eventParams?.filtersPartial && !caseSlip && selectors.length === 0) {
+                warn('EVENT_FILTER_UNKNOWN_FIELD', `${where}: filters[${i}] names \`${read.field}\`, which is not in the known `
+                    + `filter vocabulary for \`${sub.connector}\` \`${sub.event}\`. This connector `
+                    + `discovers custom fields per connection, and the trigger metadata call takes no `
+                    + `parent values (\`uip is triggers describe\` has no \`-f\`), so the list below is a `
+                    + `subset NO prepare can complete — this name may be a real field of yours. `
+                    + `Verify it against the trigger in the designer before deploying.\n`
+                    + `Known fields: ${names.slice(0, 12).join(', ')}${names.length > 12 ? ', …' : ''}.`);
+                return;
+            }
+            const baseline = selectors.length > 0 && !caseSlip;
+            (baseline ? warn : error)('EVENT_FILTER_UNKNOWN_FIELD', `${where}: filters[${i}] names \`${read.field}\`, which is not a filterable field of `
+                + `\`${sub.connector}\` \`${sub.event}\`. The platform DROPS an unmatched leaf and the deployed `
+                + `trigger fires on events this filter should exclude. `
+                + (caseSlip
+                    ? `Did you mean \`${caseSlip}\`? Matching is case-sensitive.`
+                    : `Filterable fields: ${names.slice(0, 12).join(', ')}${names.length > 12 ? ', …' : ''}.`)
+                + (baseline
+                    ? ` This is a WARNING rather than an error because \`${selectors.join('`, `')}\` `
+                        + `select this event's schema and no discovery call accepts their values, so the `
+                        + `list above is a baseline the real vocabulary extends. Verify the name against `
+                        + `the trigger in the designer before deploying.`
+                    : ''));
+        });
+    }
+}
+export function checkEventSubscription(subscription, where, at, warn, eventParams) {
+    const sub = subscription;
+    if (!sub || typeof sub !== 'object') {
+        at('EVENT_NO_SUBSCRIPTION', `${where} has no event subscription. Pass one: `
+            + `{ connector: 'uipath-microsoft-outlook365', event: 'email-received', where: { parentFolderId: '<id>' } }.`);
+        return;
+    }
+    if (typeof sub.connector !== 'string' || sub.connector === '') {
+        at('EVENT_NO_CONNECTOR', `${where} has no \`connector\` key (e.g. 'uipath-microsoft-outlook365').`);
+    }
+    if (typeof sub.event !== 'string' || sub.event === '') {
+        at('EVENT_NO_EVENT', `${where} has no \`event\` name (e.g. 'email-received').`);
+    }
+    const scope = sub.where;
+    const scopeEntries = scope && typeof scope === 'object'
+        ? Object.entries(scope)
+            .filter(([, v]) => v !== undefined && v !== null && String(v) !== '')
+        : [];
+    const scopeKeys = scopeEntries.map(([k]) => k);
+    // The object an author put in `where` by mistake — `objectName` is what the
+    // platform's own `node configure --detail` calls it, so it is the natural slip.
+    const scopeObject = scopeEntries.find(([k]) => /^(objectName|entityName|object)$/i.test(k))?.[1];
+    const object = typeof sub.object === 'string' && sub.object !== '' ? sub.object : undefined;
+    const say = warn ?? at;
+    // The OBJECT half of the contract. A GENERIC event (`record-created` on Data
+    // Fabric, Salesforce, ServiceNow, Jira, …) fires for ONE object of the connection
+    // and its library entry names none — so `object` is REQUIRED, and its absence is
+    // an error: the node would carry `objectName: ""`, validate, and be refused by
+    // the platform's dispatcher (or watch nothing). A CURATED event has its object
+    // built in, so an `object` there names a choice that does not exist.
+    if (eventParams?.generic) {
+        if (object === undefined) {
+            at('EVENT_GENERIC_NO_OBJECT', `${where} subscribes to a GENERIC event: \`${String(sub.connector)}\` \`${String(sub.event)}\` fires for ONE `
+                + `object of the connection (an entity, a table, a custom object) and the library carries no default. `
+                + `Name it with \`object\`.`
+                + (scopeObject !== undefined
+                    ? ` \`where: { ${scopeKeys.join(', ')} }\` is not it — \`where\` holds event PARAMETERS, and this `
+                        + `operation takes none; the value you put there is the object.`
+                    : ` \`uip is triggers objects ${String(sub.connector)} <EVENT> --connection-id <id>\` lists the objects `
+                        + `the bound connection exposes.`), `object: '${scopeObject !== undefined ? String(scopeObject) : '<Object>'}'`);
+        }
+    }
+    else if (object !== undefined && eventParams?.known) {
+        at('EVENT_OBJECT_NOT_GENERIC', `${where} passes \`object: '${object}'\`, but \`${String(sub.connector)}\` \`${String(sub.event)}\` is a `
+            + `CURATED event whose object is built in`
+            + (eventParams.object ? ` (\`${eventParams.object}\`)` : '')
+            + `. \`object\` names the object of a GENERIC event only (\`record-created\` and its kin); drop it here.`, undefined);
+    }
+    // The operation declares no event parameters: an empty `where` is the ONLY
+    // correct authoring, and a non-empty one names fields the operation has not got.
+    if (eventParams?.known && eventParams.names.length === 0) {
+        if (scopeKeys.length > 0) {
+            say('EVENT_SCOPE_NOT_TAKEN', `${where} passes \`where: { ${scopeKeys.join(', ')} }\`, but this connector operation takes NO event `
+                + `parameters — its library entry declares \`inputSchema.fields: []\`, and \`uip is triggers describe\` `
+                + `reports \`EventParameters: []\`. The subscription is scoped by the CONNECTION alone, so these keys `
+                + `are carried into \`detail.eventParameters\` and matched against nothing. `
+                + (eventParams.generic && scopeObject !== undefined
+                    ? `The object this GENERIC event watches goes in \`object\`, not \`where\`.`
+                    : `Filter on the PAYLOAD instead if you meant to narrow it.`), eventParams.generic && scopeObject !== undefined
+                ? `object: '${String(scopeObject)}'`
+                : `where: {}`);
+        }
+    }
+    else if (scopeKeys.length === 0 && !eventParams?.generic) {
+        // Whether omitting the scope is a mistake is not knowable here — the platform
+        // accepts an unscoped subscription (it listens to everything the connection can
+        // see) and 12 deployed Outlook flows that do exactly that scored 1.0. Name the
+        // fields the operation actually has and let the author decide.
+        const fields = eventParams?.known && eventParams.names.length > 0
+            ? `Its event parameters are: ${eventParams.names.map((n) => `\`${n}\``).join(', ')}`
+            : "\`where\` carries the connector's event parameters — for Outlook email-received that is the mail folder";
+        say('EVENT_NO_SCOPE', `${where} has no \`where\`, so its subscription is UNSCOPED: it listens to everything the bound `
+            + `connection can see, not the one thing you named. That deploys and runs — it is broader than you `
+            + `probably meant, which is why this is a warning and not an error. ${fields}. `
+            + `The names and their ids come from the bound connection: `
+            + `\`uip is triggers describe <connector> <EVENT> <object> --connection-id <id>\` lists them, and `
+            + `\`uip is resources run list <connector> MailFolder --connection-id <id>\` resolves a folder id. `
+            + `If the operation takes no event parameters at all — HTTP Webhook is one — an empty \`where\` `
+            + `is correct, and with a library on hand this warning does not fire.`, eventParams?.known && eventParams.names.length > 0
+            ? `where: { ${eventParams.names[0]}: '<id>' }`
+            : `where: { parentFolderId: '<mail folder id>' }`);
+    }
+    const filters = sub.filters;
+    if (filters !== undefined) {
+        if (!Array.isArray(filters)) {
+            at('EVENT_FILTERS_NOT_ARRAY', `${where}'s \`filters\` must be an ARRAY of { field, <operator>: value } — filters are positional and `
+                + `carry author-supplied field names, so an object map cannot express them.`, `filters: [{ field: 'subject', contains: 'Report' }]`);
+        }
+        else {
+            const operators = Object.keys(EVENT_FILTER_OPERATORS).join(', ');
+            filters.forEach((f, i) => {
+                const leaf = f;
+                if (!leaf || typeof leaf.field !== 'string' || leaf.field === '') {
+                    at('EVENT_FILTER_NO_FIELD', `${where}'s filters[${i}] has no \`field\` — name a field on the event payload, e.g. 'subject'.`);
+                }
+                const { keys, read } = readEventFilter(leaf);
+                if (keys.length === 0) {
+                    at('EVENT_FILTER_NO_VALUE', `${where}'s filters[${i}] has no operator. Write exactly one of ${operators} with its value — `
+                        + `\`contains\` is a case-sensitive substring test, the same one Integration Service applies `
+                        + `server-side; \`lessThan\`/\`greaterThan\` order a number or an ISO date.`, `{ field: '${typeof leaf?.field === 'string' ? leaf.field : 'subject'}', contains: '<text>' }`);
+                }
+                else if (keys.length > 1) {
+                    at('EVENT_FILTER_MANY_OPERATORS', `${where}'s filters[${i}] carries ${keys.length} operators (${keys.join(', ')}); a condition has exactly `
+                        + `one. Write two conditions instead — they are ANDed.`);
+                }
+                else if (!read) {
+                    at('EVENT_FILTER_NO_VALUE', `${where}'s filters[${i}] gives \`${keys[0]}\` a value that is not a string, number or boolean.`);
+                }
+                else {
+                    const problem = eventFilterProblem(read);
+                    if (problem)
+                        at('EVENT_FILTER_BAD_VALUE', `${where}'s filters[${i}] on \`${read.field}\`: ${problem}`);
+                }
+            });
+        }
+    }
+}

package/dist/decompile.js

@@ -38,7 +38,7 @@ import { DEFAULT_TRIGGER_ID } from './core/expr.js';
 import { parseIxpProjectType } from './core/actions.js';
 import { readFlowGlobals } from './flow-variables.js';
 import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
-import { eventFilterFromTreeLeaf } from './event-filters.js';
+import { eventFilterFromTreeLeaf } from './core/event-filters.js';
 /**
  * The trigger id of the flow currently being decompiled, so a reference through a
  * RENAMED trigger is still recognized as `input('x')` rather than falling back to

package/dist/registry/generators/markdown/sections/example.d.ts

@@ -10,7 +10,13 @@ export declare function nestInputs(pairs: ReadonlyArray<readonly [unknown, strin
  * helper; an enum shows its FIRST DECLARED CHOICE, typed to the declaration
  * where it can be; anything else shows `input('<name>')`.
  */
-export declare function exampleValue(f: Dict, symbol: string | undefined, invariant: ReadonlySet<string>, connectorKey?: string, action?: string): string;
+export declare function exampleValue(f: Dict, symbol: string | undefined, invariant: ReadonlySet<string>, connectorKey?: string, action?: string, 
+/**
+ * BPMN spelling: `.connector()` there takes the key and action as STRINGS —
+ * there is no generated descriptor to import — and a process reads a variable
+ * as the `=`-expression `=vars.<name>` rather than through `input()`.
+ */
+bpmnForm?: boolean): string;
 /** A compilable `connector(...)` call for this operation; events go to {@link eventExampleLines}. */
 export declare function exampleLines(j: Dict, fields: readonly Dict[], symbol: string | undefined, invariant: ReadonlySet<string>, v1def: Dict | undefined): string[];
 /**

package/dist/registry/generators/markdown/sections/example.js

@@ -93,7 +93,13 @@ export function nestInputs(pairs) {
  * helper; an enum shows its FIRST DECLARED CHOICE, typed to the declaration
  * where it can be; anything else shows `input('<name>')`.
  */
-export function exampleValue(f, symbol, invariant, connectorKey = "", action = "") {
+export function exampleValue(f, symbol, invariant, connectorKey = "", action = "", 
+/**
+ * BPMN spelling: `.connector()` there takes the key and action as STRINGS —
+ * there is no generated descriptor to import — and a process reads a variable
+ * as the `=`-expression `=vars.<name>` rather than through `input()`.
+ */
+bpmnForm = false) {
     const [name] = authoringField(f);
     // The lookup table is keyed by the WIRE name (`addLabelIds[*]`), which is
     // what `--resolve` and `buildConnectorInputs` both match on.
@@ -104,7 +110,7 @@ export function exampleValue(f, symbol, invariant, connectorKey = "", action = "
         const names = strList(reference.lookupNames);
         const aliases = byAliases(names);
         const first = names.length ? names[0] : "id";
-        if (symbol) {
+        if (symbol && !bpmnForm) {
             if (aliases.size)
                 return `lookup(${symbol}, '${wire}').${firstValue(aliases)}('…')`;
             return `lookup(${symbol}, '${wire}').by('${first}', '…')`;
@@ -131,7 +137,64 @@ export function exampleValue(f, symbol, invariant, connectorKey = "", action = "
             return pyJsonString(choice);
         }
     }
-    return `input('${leafName(name)}')`;
+    return bpmnForm ? `'=vars.${leafName(name)}'` : `input('${leafName(name)}')`;
+}
+/**
+ * `### BPMN` — the same operation as a `.connector()` call on the BPMN builder.
+ *
+ * The Flow block above cannot be pasted into a `.bpmn.ts`: BPMN leads with the
+ * ELEMENT ID, never takes a generated descriptor (so `lookup()` is always the
+ * string form), and reads a variable as `=vars.x`. An agent handed this page by
+ * `registry search --limit 5` and told to author BPMN was being handed Flow.
+ */
+function bpmnExampleLines(required, invariant, connectorKey, action, step, runtime, operation) {
+    const pairs = required.map((f) => {
+        const [name, , wireName] = authoringField(f);
+        return [wireName ? f.name : name, exampleValue(f, undefined, invariant, connectorKey, action, true)];
+    });
+    const out = ["### BPMN", "", "```ts"];
+    out.push(`import { bpmn } from '${PACKAGE_NAME}/bpmn';`);
+    if (pairs.some(([, v]) => v.includes("lookup(")))
+        out.push(`import { lookup } from '${PACKAGE_NAME}';`);
+    out.push("");
+    out.push(`.connector('${step}', '${connectorKey}', '${action}', {`);
+    if (pairs.length)
+        out.push(...nestInputs(pairs));
+    const opts = [];
+    if (pyTruthy(runtime.requiresConnection))
+        opts.push(`connection: '${afterLast(connectorKey, "-")}'`);
+    if (pyTruthy(runtime.requiresFolderKey))
+        opts.push("folder: 'shared'");
+    if (operation.activityType === "Generic" || operation.activityType === "GenericExpanded") {
+        opts.push(`object: '${pyStr(pyOr(operation.objectName, "<object>"))}'`);
+    }
+    out.push("}" + (opts.length ? `, { ${opts.join(", ")} }` : "") + ")");
+    out.push("```");
+    out.push("");
+    return out;
+}
+/**
+ * `### BPMN` for a connector EVENT: `.eventTrigger()` starts a process,
+ * `.waitForEvent()` pauses one. The subscription scope is `filter` and its
+ * parameters are FLAT there, where Flow's `where` nests them.
+ */
+function bpmnEventExampleLines(params, generic, start, connectorKey, action, step) {
+    const method = start ? "eventTrigger" : "waitForEvent";
+    const opts = [`connection: '${afterLast(connectorKey, "-")}'`, "folder: 'shared'"];
+    if (generic)
+        opts.push("object: '<Object>'");
+    if (params.length)
+        opts.push(`filter: { ${params.map((p) => `${IDENT.test(p) ? p : pyJsonString(p)}: '<${p}>'`).join(", ")} }`);
+    return [
+        "### BPMN",
+        "",
+        "```ts",
+        `import { bpmn } from '${PACKAGE_NAME}/bpmn';`,
+        "",
+        `.${method}('${step}', '${connectorKey}', '${action}', { ${opts.join(", ")} })`,
+        "```",
+        "",
+    ];
 }
 /** A compilable `connector(...)` call for this operation; events go to {@link eventExampleLines}. */
 export function exampleLines(j, fields, symbol, invariant, v1def) {
@@ -162,7 +225,7 @@ export function exampleLines(j, fields, symbol, invariant, v1def) {
     const schemaDynamic = pyTruthy(operation.objectFromDiscovery) ||
         pyTruthy(dictOf(operation.schemaAction).parents) ||
         pyTruthy(runtime.requiresConnectionForSchema);
-    const out = ["## Example", ""];
+    const out = ["## Example", "", "### Flow", ""];
     const pairs = required.map((f) => {
         const [name, , wireName] = authoringField(f);
         return [wireName ? f.name : name, exampleValue(f, symbol, invariant, connectorKey, action)];
@@ -224,6 +287,7 @@ export function exampleLines(j, fields, symbol, invariant, v1def) {
         }
         out.push("");
     }
+    out.push(...bpmnExampleLines(required, invariant, connectorKey, action, step, runtime, operation));
     return out;
 }
 /**
@@ -243,7 +307,7 @@ export function eventExampleLines(j, symbol, connectorKey, action, step, v1def)
         .filter((f) => typeof f.name === "string" && !pyTruthy(f.hidden))
         .map((f) => f.name);
     const factory = start ? "onEvent" : "waitForEvent";
-    const out = ["## Example", "", "```ts"];
+    const out = ["## Example", "", "### Flow", "", "```ts"];
     out.push(`import { ${factory} } from '${PACKAGE_NAME}';`);
     if (symbol)
         out.push(`import { ${symbol} } from './connectors/${connectorKey}.ts';`);
@@ -291,5 +355,6 @@ export function eventExampleLines(j, symbol, connectorKey, action, step, v1def)
             "--connection-id <id>` lists the objects the bound connection exposes.");
         out.push("");
     }
+    out.push(...bpmnEventExampleLines(params, generic, start, connectorKey, action, step));
     return out;
 }

package/dist/registry/generators/markdown/sections/lookups.js

@@ -11,7 +11,7 @@ import { sortedStrings } from "../../../compat/compare.js";
 import { pyStr, splitOnce } from "../../../compat/pystr.js";
 import { classify, referenceOf } from "../../../lookup-specs.js";
 import { byAliases } from "../../../naming.js";
-import { resolveFlagArg } from "../../../../core/cli-spelling.js";
+import { prepareCommand, resolveFlagArg } from "../../../../core/cli-spelling.js";
 import { authoringField, referenceCollection, referenceQuery } from "../common.js";
 import { firstValue, IDENT, pyOr, pyTruthy, strList } from "../pyvalue.js";
 /** The `resources run list` call that shows what an identity-lookup field accepts. */
@@ -94,15 +94,36 @@ export function lookupLines(connectorKey, action, fields, symbol, invariant) {
         // array too: the flat key compiles to the same list the nested
         // `recipients: { listIds: [...] }` of `## Example` does.
         const [authoringName, , multiselectWire] = authoringField(firstField);
-        if (multiselectWire) {
-            out.push(`${authoringName}: [${call}${sample}]`);
-        }
-        else {
+        const line = (c, sa) => {
+            if (multiselectWire)
+                return `${authoringName}: [${c}${sa}]`;
             const key = IDENT.test(firstName) ? firstName : pyJsonString(firstName);
-            out.push(firstName.endsWith("[*]") ? `${key}: [${call}${sample}]` : `${key}: ${call}${sample}`);
-        }
+            return firstName.endsWith("[*]") ? `${key}: [${c}${sa}]` : `${key}: ${c}${sa}`;
+        };
+        out.push(line(call, sample));
         out.push("```");
         out.push("");
+        // A SECOND fence, not a second line in the first: that one is an object
+        // literal and `## Example`'s gate compiles it, so two keys there is a
+        // syntax error before it is anything else.
+        //
+        // The descriptor form above is Flow's — `lookup(Descriptor, …)` needs a
+        // generated `connectors/<key>.ts` module, and the aliases (`.byName`) exist
+        // only on it. BPMN's `.connector()` takes the key and action as strings and
+        // imports no descriptor, so a page that printed only the descriptor form
+        // handed a BPMN author a call that does not resolve, with the generic
+        // `.by()` it needs mentioned two paragraphs further down, after the table.
+        if (symbol) {
+            const stringCall = `lookup('${connectorKey}', '${action}', '${firstName}')`;
+            const generic = firstNames.length ? `.by('${firstNames[0]}', '…')` : ".by('id', '…')";
+            out.push("In BPMN there is no descriptor to import, so the key and the action " +
+                "are strings and only the generic `.by()` exists:");
+            out.push("");
+            out.push("```ts");
+            out.push(line(stringCall, generic));
+            out.push("```");
+            out.push("");
+        }
         out.push("| field | helpers | matches on | sends |");
         out.push("| --- | --- | --- | --- |");
         for (const [f, reference] of resolvable) {
@@ -128,7 +149,7 @@ export function lookupLines(connectorKey, action, fields, symbol, invariant) {
         out.push("");
         // ONE command carrying every --resolve, and no `--connection-id`.
         out.push("```bash");
-        out.push(`npx flow-sdk registry prepare ${connectorKey} --action ${action} \\`);
+        out.push(`${prepareCommand(connectorKey, action)} \\`);
         // The WIRE name (`users[*]`), which is what prepare's lookup table is keyed
         // on — the authoring name (`users`) is refused as RESOLVE_UNKNOWN_FIELD.
         const resolves = resolvable.map(([f, reference]) => {

package/dist/registry/prepare/messages.js

@@ -220,7 +220,12 @@ export function unresolvedOperationMessage(input) {
     else {
         lines.push("", `\`registry search ${key}\` lists no action for ${key} either.`);
     }
-    lines.push("", "`registry get` and `registry search` answer from the CLI's local copy of the catalog.", "If it looks stale, refresh it first: `uip maestro flow registry pull --force`.");
+    lines.push("", "`registry get` and `registry search` answer from the CLI's local copy of the catalog.", "If it looks stale, refresh it first: `uip maestro flow registry pull --force`.", 
+    // Named `flow` on purpose, whatever family you are authoring: this is the
+    // catalog `prepare` itself reads, and `uip maestro bpmn registry pull` fills
+    // a DIFFERENT one (the BPMN extension types). A BPMN author who "corrects"
+    // the command here refreshes the wrong cache and sees no change.
+    "That is the catalog this command reads, in every family — `uip maestro bpmn registry`", "is the BPMN extension-type catalog, a different cache, and pulling it changes nothing here.");
     return lines.join("\n");
 }
 /**

package/dist/registry/prepare/source-import.d.ts

@@ -4,7 +4,7 @@
  */
 export declare const IMPORT_PATTERN: RegExp;
 /**
- * Where a `.flow.ts` will not be: generated output and installed packages.
+ * Where an authored source will not be: generated output and installed packages.
  * Matched by name at any depth, so `.flow-sdk/connectors/` is skipped too while
  * a source kept in `.flow-sdk/` itself is found.
  */
@@ -22,10 +22,10 @@ export declare function isRelativeSpecifier(specifier: string): boolean;
  * A bare package specifier never does — it is not our overlay.
  */
 export declare function resolvesTo(specifier: string, source: string, target: string): boolean;
-/** Every `*.flow.ts` file under `root`, sorted, skipping the directories a source is never in. */
+/** Every authored source file under `root`, sorted, skipping the directories a source is never in. */
 export declare function flowSources(root: string): string[];
 /**
- * `_sources_importing`: every `*.flow.ts` under `root` whose import resolves
+ * `_sources_importing`: every authored source under `root` whose import resolves
  * to `baked`. Selection is by CONTENT rather than "the single flow in this
  * directory": a workspace with three flows, one of which uses this connector,
  * has one correct answer and this finds it.

package/dist/registry/prepare/source-import.js

@@ -31,7 +31,7 @@ import { repointedLine, severalSourcesLine, sourceNotAFileLine } from "./message
  */
 export const IMPORT_PATTERN = /(^\s*import\s[^;'"]*?\sfrom\s*)(['"])([^'"]+)(\2)/gm;
 /**
- * Where a `.flow.ts` will not be: generated output and installed packages.
+ * Where an authored source will not be: generated output and installed packages.
  * Matched by name at any depth, so `.flow-sdk/connectors/` is skipped too while
  * a source kept in `.flow-sdk/` itself is found.
  */
@@ -75,7 +75,18 @@ function comparePaths(a, b) {
     }
     return a.length - b.length;
 }
-/** Every `*.flow.ts` file under `root`, sorted, skipping the directories a source is never in. */
+/**
+ * The authored-source suffixes `prepare` reads.
+ *
+ * `.bpmn.ts` is here because a BPMN `.connector()` binds a connection and a
+ * folder exactly as a Flow step does, and `prepare` reuses the author's existing
+ * label names rather than inventing new ones (`source-labels.ts`). It will never
+ * match in `sourcesImporting` — BPMN takes its connector as strings and imports
+ * no descriptor — which costs one `readFileSync` per BPMN source and keeps the
+ * two callers on one walk.
+ */
+const SOURCE_SUFFIXES = ['.flow.ts', '.bpmn.ts'];
+/** Every authored source file under `root`, sorted, skipping the directories a source is never in. */
 export function flowSources(root) {
     const found = [];
     const walk = (dir, parts) => {
@@ -91,7 +102,7 @@ export function flowSources(root) {
                 if (!SOURCE_SKIP_DIRS.has(child.name))
                     walk(join(dir, child.name), [...parts, child.name]);
             }
-            else if (child.isFile() && child.name.endsWith(".flow.ts")) {
+            else if (child.isFile() && SOURCE_SUFFIXES.some((suffix) => child.name.endsWith(suffix))) {
                 found.push([...parts, child.name]);
             }
         }
@@ -101,7 +112,7 @@ export function flowSources(root) {
     return found.map((parts) => join(root, ...parts));
 }
 /**
- * `_sources_importing`: every `*.flow.ts` under `root` whose import resolves
+ * `_sources_importing`: every authored source under `root` whose import resolves
  * to `baked`. Selection is by CONTENT rather than "the single flow in this
  * directory": a workspace with three flows, one of which uses this connector,
  * has one correct answer and this finds it.