@uipath/maestro-builder-sdk 6.11.5 → 6.11.6

package/dist/check-cli.js

@@ -9,7 +9,7 @@ import { reportDiagnostics } from './cli-result.js';
 import { existsSync } from 'node:fs';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { check } from './check.js';
-import { eventResolveErrorFor, openCliLibrary } from './cli-library.js';
+import { byoaCheckOpts, eventResolveErrorFor, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { connectorInputErrors } from './serialize.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
@@ -41,6 +41,7 @@ function checkOpts(argv) {
         return bindings ? { bindings } : {};
     return {
         eventResolveError: eventResolveErrorFor(library),
+        ...byoaCheckOpts(library),
         eventParams: (connector, event, object) => {
             try {
                 return library.eventParameterFields(connector, event, object);

package/dist/check.d.ts

@@ -2,6 +2,7 @@ import { type LookupResolutions, type LookupSpec } from './core/lookups.js';
 import type { SchemaReadiness } from './core/library.js';
 import type { BuiltFlow } from './flow-sdk.js';
 import { type BindingsView } from './core/binding-messages.js';
+import { type ByoaEventFacts, type ByoaLedger } from './core/byoa.js';
 export interface Diagnostic {
     level: 'error' | 'warning';
     code: string;
@@ -116,6 +117,18 @@ export interface CheckOpts {
     lookups?: (connector: string, action: string, version?: string, object?: string) => Readonly<Record<string, LookupSpec>> | undefined;
     /** Everything `registry prepare --resolve` has recorded in the local overlay. */
     resolutions?: LookupResolutions;
+    /**
+     * A connector event's BYOA and webhook-URL facts, or `undefined` when unknown.
+     * Supplied by the CLIs from `library.eventFacts` — the call `serialize` makes
+     * for the same refusal — so check and compile cannot disagree; omitted (no
+     * library) → EVENT_BYOA_UNVERIFIED is not checked.
+     */
+    eventFacts?: (connector: string, event: string, object?: string) => ByoaEventFacts | undefined;
+    /**
+     * The BYOA checks `registry prepare` recorded — the `byoa` section of the
+     * overlay's `resolutions.json`, as `library.byoaVerifications` loads it.
+     */
+    byoa?: ByoaLedger;
     /**
      * Whether a connector step's schema is materialized locally — the fact behind
      * the OBJECT_UNPREPARED and CUSTOM_FIELDS_UNPREPARED warnings. Supplied by the

package/dist/check.js

@@ -18,6 +18,7 @@ import { childStepLists, declaredExits, hasExits, stopsAtEnd } from './core/step
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
 import { prepareCommand, resolveFlagArg } from './core/cli-spelling.js';
+import { EVENT_BYOA_UNVERIFIED, byoaUnverified } from './core/byoa.js';
 export function check(built, opts = {}) {
     return checkFlow(built, [], opts);
 }
@@ -1953,6 +1954,13 @@ function eventParamsFor(subscription, opts) {
  *   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
@@ -1988,6 +1996,9 @@ function checkEventResolution(subscription, where, kind, opts, error, warn, even
         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

package/dist/cli-library.d.ts

@@ -19,3 +19,10 @@ export declare function openCliLibrary(argv: readonly string[]): Library | undef
  * exactly when compile would throw, with the same text.
  */
 export declare function eventResolveErrorFor(library: Library): NonNullable<CheckOpts['eventResolveError']>;
+/**
+ * `check`'s EVENT_BYOA_UNVERIFIED inputs: the event facts and the recorded BYOA
+ * checks, from the same `library.eventFacts` / `library.byoaVerifications` that
+ * `serialize` reads for the same refusal. Both CLIs spread this into their
+ * check options, so the inner loop and the emit rung refuse the same flows.
+ */
+export declare function byoaCheckOpts(library: Library): Pick<CheckOpts, 'eventFacts' | 'byoa'>;

package/dist/cli-library.js

@@ -54,3 +54,22 @@ export function eventResolveErrorFor(library) {
         }
     };
 }
+/**
+ * `check`'s EVENT_BYOA_UNVERIFIED inputs: the event facts and the recorded BYOA
+ * checks, from the same `library.eventFacts` / `library.byoaVerifications` that
+ * `serialize` reads for the same refusal. Both CLIs spread this into their
+ * check options, so the inner loop and the emit rung refuse the same flows.
+ */
+export function byoaCheckOpts(library) {
+    return {
+        eventFacts: (connector, event, object) => {
+            try {
+                return library.eventFacts(connector, event, object);
+            }
+            catch {
+                return undefined; // unknown fails open, same as every library callback
+            }
+        },
+        byoa: library.byoaVerifications,
+    };
+}

package/dist/compile-cli.js

@@ -23,12 +23,13 @@ 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 { eventResolveErrorFor, openCliLibrary } from './cli-library.js';
+import { byoaCheckOpts, 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';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
 import { BindingRefusal } from './core/binding-messages.js';
+import { ByoaRefusal } from './core/byoa.js';
 function opt(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 ? argv[i + 1] : undefined;
@@ -96,6 +97,7 @@ export async function run(argv) {
                 // printed as `✗ [EVENT_UNKNOWN]` before stopping instead of hiding
                 // behind "1 error(s); not emitting".
                 eventResolveError: eventResolveErrorFor(library),
+                ...byoaCheckOpts(library),
                 eventParams: (connector, event) => {
                     try {
                         return library.eventParameterFields(connector, event);
@@ -134,16 +136,17 @@ export async function run(argv) {
     // check()'s. Warnings are never fatal: the .flow is still written, exit stays 0.
     // A binding LABEL the serializer refuses (its own name as the resourceKey, or a
     // label a populated bindings.json does not declare) is an error, not a
-    // warning: the check pass above reports it first, and this is the same refusal
-    // in the same `✗ [CODE]` shape when that pass was skipped (`--no-check`, or an
-    // emit-only project). Nothing is written.
+    // warning, and so is a BYOA-only event on a connection `prepare` never checked
+    // (EVENT_BYOA_UNVERIFIED): the check pass above reports each first, and this is
+    // the same refusal in the same `✗ [CODE]` shape when that pass was skipped
+    // (`--no-check`, or an emit-only project). Nothing is written.
     const warnings = [];
     let emitted;
     try {
         emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w) });
     }
     catch (error) {
-        if (!(error instanceof BindingRefusal))
+        if (!(error instanceof BindingRefusal || error instanceof ByoaRefusal))
             throw error;
         for (const w of warnings)
             console.error(`  ⚠ [${w.code}] ${w.message}`);

package/dist/core/byoa.d.ts

@@ -0,0 +1,69 @@
+/** The diagnostic code, in `check` and on the error `serialize` throws. */
+export declare const EVENT_BYOA_UNVERIFIED = "EVENT_BYOA_UNVERIFIED";
+/** One verification `prepare` recorded. Only a PASSING check is ever written. */
+export interface ByoaRecord {
+    byoa: true;
+    /** The connection's `Name`, so a person reading the file can tell which one it is. */
+    connectionName?: string;
+    /** `YYYY-MM-DD`: a resolved answer is a snapshot, like every other ledger row. */
+    verifiedAt?: string;
+}
+/**
+ * The ledger's `byoa` section: `byoa[<event node type>][<connection id>]`.
+ *
+ * Keyed per EVENT, not per connector — Slack `send-reply` needs no BYOA, the
+ * message trigger does — and per CONNECTION, so swapping the connection in
+ * bindings.json un-verifies the event until it is prepared again.
+ */
+export type ByoaLedger = Record<string, Record<string, ByoaRecord>>;
+/** The event facts the rule reads, as `Library.eventFacts` answers them. */
+export interface ByoaEventFacts {
+    byoaConnection: boolean;
+    isWebhookUrlVisible: boolean;
+}
+/**
+ * The key an event's record is stored under: the WAIT form of the node type,
+ * the form `prepare` stores an event's overlay and lookup rows under, whichever
+ * role (`onEvent` or `waitForEvent`) the flow uses it in.
+ */
+export declare function byoaLedgerKey(connectorKey: string, event: string): string;
+/** The record for `connectionId` under `nodeType`, matching the id case-insensitively. */
+export declare function byoaRecordFor(ledger: ByoaLedger | undefined, nodeType: string, connectionId: string): ByoaRecord | undefined;
+/** What `compile` throws for the refusal; `code` lets the CLI print it as `✗ [CODE]`. */
+export declare class ByoaRefusal extends Error {
+    readonly code = "EVENT_BYOA_UNVERIFIED";
+    constructor(message: string);
+}
+/** One subscription, as the rule needs it. */
+export interface ByoaSubscription {
+    connector: string;
+    event: string;
+    object?: string;
+    /** The `connection:` label as authored — a bindings.json name, or a connection id. */
+    connection?: unknown;
+}
+/**
+ * Why a BYOA-only event cannot be trusted to fire on its bound connection, or
+ * `undefined` when there is nothing to refuse. The ONE condition behind
+ * `check`'s EVENT_BYOA_UNVERIFIED error and `compile`'s refusal, so the two
+ * cannot disagree.
+ *
+ * Refuses when the event's facts say BYOA and the connection resolves to a real
+ * connection id with no `byoa` record for this event. Silent when:
+ *
+ * - the facts are unknown or say no BYOA;
+ * - the connection does not resolve to a real id — no bindings.json, a label it
+ *   does not declare, or a placeholder (`0000…`, `<…>`, the label itself). There
+ *   is no id to look a record up by, and nothing is lost: such a flow cannot
+ *   run its trigger on any connection, and BINDING_SELF_NAME /
+ *   BINDING_UNDECLARED / CONNECTION_STUB already say so.
+ *
+ * @param where - The call site, as the other event diagnostics name it (`trigger`, `waitForEvent "x"`).
+ * @param sub - The subscription.
+ * @param facts - The event's facts from the library, or `undefined` when unknown.
+ * @param ledger - The overlay ledger's `byoa` section.
+ * @param bindings - Resolves the `connection:` label to an id.
+ */
+export declare function byoaUnverified(where: string, sub: ByoaSubscription, facts: ByoaEventFacts | undefined, ledger: ByoaLedger | undefined, bindings: {
+    resolve(name?: string): string | undefined;
+} | undefined): string | undefined;

package/dist/core/byoa.js

@@ -0,0 +1,98 @@
+/**
+ * core/byoa — connector events that only fire on a BYOA connection (#848).
+ *
+ * BYOA is "bring your own app": an Integration Service connection created with
+ * the customer's own OAuth app. Some event objects need one — Slack
+ * `message-received-in-slack` is a webhook the customer's Slack app delivers,
+ * so on a standard connection the trigger deploys, validates, and never fires.
+ *
+ * Only a live call can tell a BYOA connection from a standard one, and `registry
+ * prepare` makes it: on an event whose facts say BYOA it lists the tenant's BYOA
+ * connections, refuses a connection that is not among them, and records one
+ * that is under `byoa[<event node type>][<connection id>]` in
+ * `connectors-local/resolutions.json`. This module is the offline half: the
+ * record's shape, and the one condition `check` reports and `compile` throws
+ * when a BYOA event's bound connection carries no record — typically because
+ * the connection was bound by preparing an ACTION of the same connector, which
+ * checks nothing about BYOA. `check` stays offline: it checks that the live
+ * check happened, never the tenant.
+ *
+ * No `node:fs` here — `check` and `serialize` import this module, and the file
+ * read lives in `lookup-store.ts` beside the ledger's other reader.
+ */
+import { GUID_RE } from './binding-messages.js';
+import { prepareCommand } from './cli-spelling.js';
+/** The diagnostic code, in `check` and on the error `serialize` throws. */
+export const EVENT_BYOA_UNVERIFIED = 'EVENT_BYOA_UNVERIFIED';
+/**
+ * The key an event's record is stored under: the WAIT form of the node type,
+ * the form `prepare` stores an event's overlay and lookup rows under, whichever
+ * role (`onEvent` or `waitForEvent`) the flow uses it in.
+ */
+export function byoaLedgerKey(connectorKey, event) {
+    return `uipath.connector.event.${connectorKey}.${event}`;
+}
+/** The record for `connectionId` under `nodeType`, matching the id case-insensitively. */
+export function byoaRecordFor(ledger, nodeType, connectionId) {
+    const perEvent = ledger?.[nodeType];
+    if (!perEvent || typeof perEvent !== 'object')
+        return undefined;
+    const wanted = connectionId.toLowerCase();
+    for (const [id, record] of Object.entries(perEvent)) {
+        if (id.toLowerCase() === wanted && record && typeof record === 'object' && record.byoa === true)
+            return record;
+    }
+    return undefined;
+}
+/** What `compile` throws for the refusal; `code` lets the CLI print it as `✗ [CODE]`. */
+export class ByoaRefusal extends Error {
+    code = EVENT_BYOA_UNVERIFIED;
+    constructor(message) {
+        super(message);
+        this.name = 'ByoaRefusal';
+    }
+}
+/** An all-zero GUID: a placeholder no tenant issues (compile's CONNECTION_STUB). */
+const STUB_GUID_RE = /^0{8}-0{4}-0{4}-0{4}-/;
+/**
+ * Why a BYOA-only event cannot be trusted to fire on its bound connection, or
+ * `undefined` when there is nothing to refuse. The ONE condition behind
+ * `check`'s EVENT_BYOA_UNVERIFIED error and `compile`'s refusal, so the two
+ * cannot disagree.
+ *
+ * Refuses when the event's facts say BYOA and the connection resolves to a real
+ * connection id with no `byoa` record for this event. Silent when:
+ *
+ * - the facts are unknown or say no BYOA;
+ * - the connection does not resolve to a real id — no bindings.json, a label it
+ *   does not declare, or a placeholder (`0000…`, `<…>`, the label itself). There
+ *   is no id to look a record up by, and nothing is lost: such a flow cannot
+ *   run its trigger on any connection, and BINDING_SELF_NAME /
+ *   BINDING_UNDECLARED / CONNECTION_STUB already say so.
+ *
+ * @param where - The call site, as the other event diagnostics name it (`trigger`, `waitForEvent "x"`).
+ * @param sub - The subscription.
+ * @param facts - The event's facts from the library, or `undefined` when unknown.
+ * @param ledger - The overlay ledger's `byoa` section.
+ * @param bindings - Resolves the `connection:` label to an id.
+ */
+export function byoaUnverified(where, sub, facts, ledger, bindings) {
+    if (!facts?.byoaConnection)
+        return undefined;
+    if (typeof sub.connection !== 'string' || sub.connection === '')
+        return undefined;
+    const label = sub.connection;
+    const id = bindings?.resolve(label) ?? label;
+    if (!GUID_RE.test(id) || STUB_GUID_RE.test(id))
+        return undefined;
+    if (byoaRecordFor(ledger, byoaLedgerKey(sub.connector, sub.event), id))
+        return undefined;
+    const named = label === id ? `connection ${id}` : `connection \`${label}\` (${id})`;
+    const object = sub.object ? ` --object ${sub.object}` : '';
+    return `${where}: \`${sub.connector}\` \`${sub.event}\` requires a BYOA (bring-your-own-app) connection — `
+        + `one created with your own OAuth app — and ${named} was never checked against that requirement. `
+        + `A standard connection deploys and the trigger never fires. Prepare the event on this connection, `
+        + `which refuses a standard connection and records a BYOA one:\n`
+        + `  ${prepareCommand(sub.connector, sub.event)}${object} --connection-id ${id}\n`
+        + `BYOA connections (rows for \`${sub.connector}\`): uip is connections list --byoa --all-folders`;
+}

package/dist/core/library.d.ts

@@ -1,4 +1,5 @@
 import { type LookupResolutions, type LookupSpec } from './lookups.js';
+import type { ByoaEventFacts, ByoaLedger } from './byoa.js';
 export interface ResolvedConnector {
     nodeType: string;
     version: string;
@@ -229,6 +230,12 @@ export declare class Library {
      * id from someone else's connection.
      */
     readonly lookupResolutions: LookupResolutions;
+    /**
+     * The BYOA checks `prepare` recorded (`resolutions.json` → `byoa`), from the
+     * overlay only, for the same reason as {@link lookupResolutions}: whether a
+     * connection is BYOA is a fact about one tenant.
+     */
+    readonly byoaVerifications: ByoaLedger;
     /** Collections the ledger declares connector-invariant; overlay unions over baked. */
     private readonly invariantCollections;
     constructor(dir: string, opts?: LibraryOpts);
@@ -348,6 +355,22 @@ export declare class Library {
      * raw library snapshot carries ZERO trigger/event entries).
      */
     eventParameterFields(key: string, event: string, objectName?: string): EventParameterFields | undefined;
+    /**
+     * Whether a connector event needs a BYOA (bring-your-own-app) connection, and
+     * whether its webhook URL must be registered by hand — or `undefined` when no
+     * layer carries the event in either form.
+     *
+     * Read from the `.v1def.json` sidecar, where the library build stamps the
+     * facts from the event's `triggers objects` row and `prepare` stores them on
+     * the overlay. A fact is TRUE when ANY layer, in either form (`.event.` or
+     * `.trigger.`), says so: the requirement belongs to the event object, not to
+     * a tenant, and an overlay written by an older `prepare` — which stored the
+     * `describe` answer, `false` for Slack `message-received-in-slack` — must not
+     * hide the true fact a newer baked library carries.
+     *
+     * `check` and `compile` read this through the one rule in `core/byoa.ts`.
+     */
+    eventFacts(key: string, event: string, objectName?: string): ByoaEventFacts | undefined;
     /**
      * The filterable-field names a connector event declares — the vocabulary a
      * `filters` leaf may name.

package/dist/core/library.js

@@ -11,7 +11,7 @@ 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';
+import { loadByoaLedger, loadInvariantCollections, loadLookupResolutions } from './lookup-store.js';
 export class Library {
     layers = [];
     /** The LIST-ENVELOPE LEDGER, overlay first so a prepared entry can add a row. */
@@ -24,10 +24,17 @@ export class Library {
      * id from someone else's connection.
      */
     lookupResolutions;
+    /**
+     * The BYOA checks `prepare` recorded (`resolutions.json` → `byoa`), from the
+     * overlay only, for the same reason as {@link lookupResolutions}: whether a
+     * connection is BYOA is a fact about one tenant.
+     */
+    byoaVerifications;
     /** Collections the ledger declares connector-invariant; overlay unions over baked. */
     invariantCollections;
     constructor(dir, opts = {}) {
         this.lookupResolutions = loadLookupResolutions(opts.overlayDir);
+        this.byoaVerifications = loadByoaLedger(opts.overlayDir);
         this.invariantCollections = new Set([
             ...loadInvariantCollections(dir),
             ...loadInvariantCollections(opts.overlayDir),
@@ -434,6 +441,45 @@ export class Library {
                 .some(([name, value]) => name !== 'type' && Boolean(value)),
         };
     }
+    /**
+     * Whether a connector event needs a BYOA (bring-your-own-app) connection, and
+     * whether its webhook URL must be registered by hand — or `undefined` when no
+     * layer carries the event in either form.
+     *
+     * Read from the `.v1def.json` sidecar, where the library build stamps the
+     * facts from the event's `triggers objects` row and `prepare` stores them on
+     * the overlay. A fact is TRUE when ANY layer, in either form (`.event.` or
+     * `.trigger.`), says so: the requirement belongs to the event object, not to
+     * a tenant, and an overlay written by an older `prepare` — which stored the
+     * `describe` answer, `false` for Slack `message-received-in-slack` — must not
+     * hide the true fact a newer baked library carries.
+     *
+     * `check` and `compile` read this through the one rule in `core/byoa.ts`.
+     */
+    eventFacts(key, event, objectName) {
+        let found = false;
+        const facts = { byoaConnection: false, isWebhookUrlVisible: false };
+        for (const layer of this.layers) {
+            for (const kind of ['event', 'trigger']) {
+                let rc;
+                try {
+                    rc = this.resolveInLayer(layer, `uipath.connector.${kind}.${key}.${event}`, undefined, objectName);
+                }
+                catch {
+                    continue; // an ambiguous object is resolveEvent's refusal to report
+                }
+                if (!rc)
+                    continue;
+                found = true;
+                const v1def = (rc.v1def ?? {});
+                if (v1def.byoaConnection === true)
+                    facts.byoaConnection = true;
+                if (v1def.isWebhookUrlVisible === true)
+                    facts.isWebhookUrlVisible = true;
+            }
+        }
+        return found ? facts : undefined;
+    }
     /**
      * The filterable-field names a connector event declares — the vocabulary a
      * `filters` leaf may name.

package/dist/core/lookup-store.d.ts

@@ -1,3 +1,4 @@
+import type { ByoaLedger } from './byoa.js';
 import type { LookupResolutions } from './lookups.js';
 /**
  * Load `<overlayDir>/resolutions.json`, or an empty map.
@@ -8,6 +9,17 @@ import type { LookupResolutions } from './lookups.js';
  * behaviour an author wants from a missing resolution anyway.
  */
 export declare function loadLookupResolutions(overlayDir: string | undefined): LookupResolutions;
+/**
+ * Load the `byoa` section of `<overlayDir>/resolutions.json` — the BYOA checks
+ * `registry prepare` recorded (see `core/byoa.ts`) — or an empty map.
+ *
+ * Lenient like {@link loadLookupResolutions}: an absent or malformed file reads
+ * as EMPTY, and the consequence of empty is the EVENT_BYOA_UNVERIFIED error
+ * naming the `prepare` command that records the check. Read fresh on every
+ * call rather than cached: `prepare` rewrites this file, and a stale "never
+ * checked" answer would refuse a flow that was just verified.
+ */
+export declare function loadByoaLedger(overlayDir: string | undefined): ByoaLedger;
 /**
  * The invariant-collection ledger's `objectName` set, from a library dir.
  *

package/dist/core/lookup-store.js

@@ -45,6 +45,31 @@ export function loadLookupResolutions(overlayDir) {
     RESOLUTION_CACHE.set(overlayDir, rows);
     return rows;
 }
+/**
+ * Load the `byoa` section of `<overlayDir>/resolutions.json` — the BYOA checks
+ * `registry prepare` recorded (see `core/byoa.ts`) — or an empty map.
+ *
+ * Lenient like {@link loadLookupResolutions}: an absent or malformed file reads
+ * as EMPTY, and the consequence of empty is the EVENT_BYOA_UNVERIFIED error
+ * naming the `prepare` command that records the check. Read fresh on every
+ * call rather than cached: `prepare` rewrites this file, and a stale "never
+ * checked" answer would refuse a flow that was just verified.
+ */
+export function loadByoaLedger(overlayDir) {
+    if (!overlayDir)
+        return {};
+    const file = join(overlayDir, 'resolutions.json');
+    if (!existsSync(file))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        const byoa = parsed?.byoa;
+        return byoa && typeof byoa === 'object' && !Array.isArray(byoa) ? byoa : {};
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * The invariant-collection ledger's `objectName` set, from a library dir.
  *

package/dist/registry/generators/descriptors.d.ts

@@ -40,7 +40,7 @@ export declare function emitLookupsBlock(specs: ReadonlyMap<string, LookupSpecDa
  * parameters (HTTP Webhook) or one nothing has described yet, and an empty
  * interface would refuse every key in both cases.
  */
-export declare function emitEvent(entry: LibraryEntry, inFields: readonly LibraryField[], inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>): string[];
+export declare function emitEvent(entry: LibraryEntry, inFields: readonly LibraryField[], inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>, v1def?: V1Definition): string[];
 /** One operation: its `Inputs`/`Outputs` interfaces, doc comment and `descriptor()` const. */
 export declare function emitOp(entry: LibraryEntry, v1def: V1Definition, inputTree: TypeTree, outputTree: TypeTree, name: string, inputTypes: NamedTypeRegistry, outputTypes: NamedTypeRegistry, invariant?: ReadonlySet<string>): string[];
 /**

package/dist/registry/generators/descriptors.js

@@ -18,6 +18,7 @@
  * event's per-object variants are skipped because they share their template's
  * node type and so would emit the same const twice.
  */
+import { prepareCommand } from "../../core/cli-spelling.js";
 import { PACKAGE_NAME } from "../../package-name.js";
 import { pyJsonString, pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedByCodePoint, sortedStrings } from "../compat/compare.js";
@@ -165,7 +166,7 @@ function versionOf(entry) {
  * parameters (HTTP Webhook) or one nothing has described yet, and an empty
  * interface would refuse every key in both cases.
  */
-export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant = new Set()) {
+export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant = new Set(), v1def = {}) {
     const nodeType = entry.nodeType;
     const eventId = afterLast(nodeType, ".");
     const connectorKey = pyTruthy(entry.connector?.key) ? entry.connector.key : "";
@@ -196,6 +197,23 @@ export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTyp
         lines.push(` * Start a flow on it with \`onEvent(${name}, { where: { … } })\`, or pause for it`);
         lines.push(` * with \`waitForEvent(${name}, { … })\`; \`where\` carries its event parameters.`);
     }
+    // The facts the library build stamped from the event's `triggers objects`
+    // row. An author holding only the descriptor must learn the requirement here:
+    // on a standard connection the trigger deploys and never fires.
+    if (v1def.byoaConnection === true) {
+        lines.push(" *");
+        lines.push(" * Requires a BYOA (bring-your-own-app) connection — on a standard one the");
+        lines.push(" * trigger deploys and never fires. Bind it with");
+        // Spelled for whoever ran the generator, like every `check` remedy.
+        lines.push(` * \`${prepareCommand(pyStr(connectorKey), eventId, "--connection-id", "<id>")}\`,`);
+        lines.push(" * which refuses a standard connection and records the check `compile` requires;");
+        lines.push(" * `uip is connections list --byoa --all-folders` lists the BYOA connections.");
+    }
+    if (v1def.isWebhookUrlVisible === true) {
+        lines.push(" *");
+        lines.push(" * After deploying, register the trigger's webhook URL in the connector app's");
+        lines.push(" * event-subscription settings; `registry prepare` prints the instructions.");
+    }
     // INSIDE the block: `emitLookupComment` returns bare ` * ` body lines.
     if (specs.size > 0) {
         lines.push(" *");
@@ -222,7 +240,7 @@ export function emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, ou
     const runtime = entry.runtime ?? {};
     const inFields = descriptorInputFields(entry, v1def);
     if (isEventNodeType(nodeType)) {
-        return emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant);
+        return emitEvent(entry, inFields, inputTree, outputTree, name, inputTypes, outputTypes, invariant, v1def);
     }
     const lines = [];
     lines.push(...emitInterface(`${name}Inputs`, false, inputTypes, inputTree, true));

package/dist/registry/generators/markdown/page.js

@@ -1,12 +1,13 @@
 /**
  * One library entry rendered to Markdown: header → schema-dynamic notice →
- * choosing the object → resolving the field set → required inputs → optional
+ * connection requirements (events) → choosing the object → resolving the field set → required inputs → optional
  * inputs → resolving lookups → example → filtering → outputs. Ported from
  * `render_op`; the page is `"\n".join(lines)` with no trailing newline.
  */
 import { afterLast, pyStr } from "../../compat/pystr.js";
 import { dictOf, getStr, pyOr, pyTruthy } from "./pyvalue.js";
 import { choosingObjectLines } from "./sections/choosing-object.js";
+import { eventFactsLines } from "./sections/event-facts.js";
 import { exampleLines } from "./sections/example.js";
 import { eventFilterLines } from "./sections/filtering.js";
 import { headerLines } from "./sections/header.js";
@@ -28,6 +29,7 @@ export function renderOp(j, v1def, symbol, invariant) {
     const out = [];
     out.push(...headerLines(j, nodeType));
     out.push(...schemaDynamicLines(j, nodeType));
+    out.push(...eventFactsLines(j, v1def));
     const fields = assembleFields(j, v1def);
     const required = fields.filter((f) => pyTruthy(f.required));
     const optional = fields.filter((f) => !pyTruthy(f.required));

package/dist/registry/generators/markdown/sections/event-facts.d.ts

@@ -0,0 +1,2 @@
+import { type Dict } from "../pyvalue.js";
+export declare function eventFactsLines(j: Dict, v1def: Dict | undefined): string[];

package/dist/registry/generators/markdown/sections/event-facts.js

@@ -0,0 +1,45 @@
+/**
+ * `## Connection requirements`: the event facts an author has to act on before
+ * the trigger can fire — a BYOA (bring-your-own-app) connection, and a webhook
+ * URL registered by hand. Emitted only when a fact is TRUE, so every other
+ * event page is unchanged. The facts are the sidecar's, which the library build
+ * stamps from the event's `triggers objects` row (#848).
+ */
+import { prepareCommand } from "../../../../core/cli-spelling.js";
+import { isEventNodeType } from "../../../model/library.js";
+import { dictOf, getStr } from "../pyvalue.js";
+export function eventFactsLines(j, v1def) {
+    const nodeType = getStr(j, "nodeType", "");
+    if (!isEventNodeType(nodeType))
+        return [];
+    const facts = dictOf(v1def);
+    const byoa = facts.byoaConnection === true;
+    const webhook = facts.isWebhookUrlVisible === true;
+    if (!byoa && !webhook)
+        return [];
+    const key = getStr(dictOf(j.connector), "key", "<connector>");
+    const event = nodeType.slice(nodeType.lastIndexOf(".") + 1);
+    const out = ["## Connection requirements", ""];
+    if (byoa) {
+        out.push("**Requires a BYOA connection.** This event fires only on a BYOA " +
+            "(bring-your-own-app) connection — one created with your own OAuth app. " +
+            "On a standard connection the trigger deploys and never fires. Prepare " +
+            "the event on the connection you bind: it refuses a standard connection " +
+            "and records a BYOA one, and `check` and `compile` refuse this event on a " +
+            "connection that was never checked (`EVENT_BYOA_UNVERIFIED`).");
+        out.push("");
+        out.push("```bash");
+        out.push(prepareCommand(key, event, "--connection-id", "<id>"));
+        out.push("uip is connections list --byoa --all-folders   # the BYOA connections");
+        out.push("```");
+        out.push("");
+    }
+    if (webhook) {
+        out.push("**Register the webhook URL.** The connector's app delivers these events " +
+            "to a URL Integration Service issues. After deploying, copy the trigger's " +
+            "webhook URL into the app's event-subscription settings; `registry prepare` " +
+            "prints the connector's own instructions.");
+        out.push("");
+    }
+    return out;
+}

package/dist/registry/library-build/events.d.ts

@@ -48,15 +48,43 @@ export declare function normalizeBucketFields(parameters: unknown): Dict[];
  * survives the merge.
  */
 export declare function unionEventParameters(declared: unknown, objectParameters: unknown): Dict[];
-/** `merge_describe_into_node`: fold a `triggers describe` answer into a registry trigger definition (a copy). */
-export declare function mergeDescribeIntoNode(node: Dict, describe: Dict, objectParameters?: unknown): Dict;
+/** The three event facts: the API's (PascalCase) spelling and the stored (camelCase) one. */
+declare const EVENT_FACTS: ReadonlyArray<readonly [string, "eventMode" | "byoaConnection" | "isWebhookUrlVisible"]>;
+/** The facts one source states, under their stored names; a fact the source does not state is absent. */
+export type StatedEventFacts = Partial<Record<(typeof EVENT_FACTS)[number][1], unknown>>;
+/**
+ * THE precedence rule for the three event facts, used by every place that
+ * decides one: the `triggers objects` ROW wins, then `fallback`, and a fact
+ * neither states stays absent.
+ *
+ * `fallback` is whichever definition the caller holds — a `triggers describe`
+ * answer (PascalCase, generate time) or a registry node (camelCase, prepare
+ * time); both spellings are read. The row is the only one of the three sources
+ * that tells the truth about BYOA: Slack `message-received-in-slack` answers
+ * `ByoaConnection: true` in its objects row and `false` in both `describe` and
+ * the registry node. Generate time used to read `describe` alone while
+ * `prepare` read the row, so the library baked `false` for a BYOA-only event
+ * and nothing downstream could refuse a standard connection on it (#848).
+ * One function, so the two sides cannot drift again.
+ */
+export declare function resolveEventFacts(objectRow: unknown, fallback: unknown): StatedEventFacts;
+/**
+ * `merge_describe_into_node`: fold a `triggers describe` answer into a registry
+ * trigger definition (a copy). The facts follow {@link resolveEventFacts}, so
+ * pass the event's `triggers objects` row when there is one: `prepare` stores
+ * this definition as the overlay, and `check` reads BYOA off the overlay.
+ */
+export declare function mergeDescribeIntoNode(node: Dict, describe: Dict, objectParameters?: unknown, objectRow?: unknown): Dict;
 export interface EventFacts {
     eventMode: string;
     byoaConnection: boolean;
     isWebhookUrlVisible: boolean;
     textBlocks: string[];
 }
-/** `event_facts`: the three facts that change how a subscription is prepared or tested; the object row wins. */
+/**
+ * `event_facts`: the three facts that change how a subscription is prepared or
+ * tested, by {@link resolveEventFacts} (the object row wins), with defaults.
+ */
 export declare function eventFacts(node: Dict, objectRow: unknown): EventFacts;
 /**
  * `triggers_objects_cached`: cached `uip is triggers objects <key> <OPERATION>`,
@@ -106,3 +134,4 @@ export declare function expandGenericEvents(ctx: BuildContext, templates: Librar
  * input with curated events described in place.
  */
 export declare function resolveConnectorEvents(ctx: BuildContext, entries: LibraryEntry[]): Promise<[LibraryEntry[], LibraryEntry[]]>;
+export {};

package/dist/registry/library-build/events.js

@@ -261,39 +261,69 @@ export function unionEventParameters(declared, objectParameters) {
     }
     return withCascade([...merged.values()]);
 }
+/** The three event facts: the API's (PascalCase) spelling and the stored (camelCase) one. */
 const EVENT_FACTS = [
     ["EventMode", "eventMode"],
     ["ByoaConnection", "byoaConnection"],
     ["IsWebhookUrlVisible", "isWebhookUrlVisible"],
 ];
-/** `merge_describe_into_node`: fold a `triggers describe` answer into a registry trigger definition (a copy). */
-export function mergeDescribeIntoNode(node, describe, objectParameters = null) {
+/**
+ * THE precedence rule for the three event facts, used by every place that
+ * decides one: the `triggers objects` ROW wins, then `fallback`, and a fact
+ * neither states stays absent.
+ *
+ * `fallback` is whichever definition the caller holds — a `triggers describe`
+ * answer (PascalCase, generate time) or a registry node (camelCase, prepare
+ * time); both spellings are read. The row is the only one of the three sources
+ * that tells the truth about BYOA: Slack `message-received-in-slack` answers
+ * `ByoaConnection: true` in its objects row and `false` in both `describe` and
+ * the registry node. Generate time used to read `describe` alone while
+ * `prepare` read the row, so the library baked `false` for a BYOA-only event
+ * and nothing downstream could refuse a standard connection on it (#848).
+ * One function, so the two sides cannot drift again.
+ */
+export function resolveEventFacts(objectRow, fallback) {
+    const row = pyOr(objectRow, {});
+    const other = pyOr(fallback, {});
+    const out = {};
+    for (const [api, stored] of EVENT_FACTS) {
+        for (const [source, key] of [[row, api], [other, api], [other, stored]]) {
+            if (get(source, key) !== null) {
+                out[stored] = source[key];
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * `merge_describe_into_node`: fold a `triggers describe` answer into a registry
+ * trigger definition (a copy). The facts follow {@link resolveEventFacts}, so
+ * pass the event's `triggers objects` row when there is one: `prepare` stores
+ * this definition as the overlay, and `check` reads BYOA off the overlay.
+ */
+export function mergeDescribeIntoNode(node, describe, objectParameters = null, objectRow = null) {
     const out = { ...node };
     out.eventParameters = { fields: unionEventParameters(get(describe, "EventParameters"), objectParameters) };
     out.filterFields = { fields: camelFields(get(describe, "FilterFields")) };
     if (truthy(get(describe, "OutputFields"))) {
         out.outputResponseDefinition = { fields: camelFields(get(describe, "OutputFields")) };
     }
-    for (const [src, dst] of EVENT_FACTS)
-        if (get(describe, src) !== null)
-            out[dst] = describe[src];
+    Object.assign(out, resolveEventFacts(objectRow, describe));
     return out;
 }
-/** `event_facts`: the three facts that change how a subscription is prepared or tested; the object row wins. */
+/**
+ * `event_facts`: the three facts that change how a subscription is prepared or
+ * tested, by {@link resolveEventFacts} (the object row wins), with defaults.
+ */
 export function eventFacts(node, objectRow) {
     const row = pyOr(objectRow, {});
-    const fact = (rowKey, nodeKey, dflt) => {
-        if (get(row, rowKey) !== null)
-            return row[rowKey];
-        if (get(node, nodeKey) !== null)
-            return node[nodeKey];
-        return dflt;
-    };
+    const stated = resolveEventFacts(row, node);
     const textBlocks = pyOr(get(pyOr(get(row, "Design"), {}), "TextBlocks"), get(pyOr(get(row, "design"), {}), "textBlocks"), []);
     return {
-        eventMode: pyStr(pyOr(get(node, "eventMode"), "polling")),
-        byoaConnection: truthy(fact("ByoaConnection", "byoaConnection", false)),
-        isWebhookUrlVisible: truthy(fact("IsWebhookUrlVisible", "isWebhookUrlVisible", false)),
+        eventMode: pyStr(pyOr(stated.eventMode ?? null, "polling")),
+        byoaConnection: truthy(stated.byoaConnection ?? false),
+        isWebhookUrlVisible: truthy(stated.isWebhookUrlVisible ?? false),
         textBlocks: pyIter(textBlocks).map(textBlockText),
     };
 }
@@ -388,9 +418,8 @@ export function applyEventSchema(entry, describe, obj) {
     if (outputFields.length > 0)
         e.outputSchema = { fields: outputFields };
     const eventSchema = { eventParameters: fields, filterFields: camelFields(get(d, "FilterFields")) };
-    for (const [src, dst] of EVENT_FACTS)
-        if (get(d, src) !== null)
-            eventSchema[dst] = d[src];
+    // The objects row is the per-object fact sheet; describe is the fallback.
+    Object.assign(eventSchema, resolveEventFacts(o, d));
     e.eventSchema = eventSchema;
     return entry;
 }

package/dist/registry/prepare/byoa-ledger.d.ts

@@ -0,0 +1,12 @@
+import type { ConnectionRow } from "./connections.js";
+/**
+ * The ledger with `byoa[nodeType][connectionId]` set to a passing check. Pure:
+ * returns a new ledger. A re-run on the same connection rewrites the entry,
+ * `verifiedAt` included — the check was made again, so the snapshot is newer.
+ */
+export declare function recordByoa(ledger: Record<string, unknown>, nodeType: string, connectionId: string, row: ConnectionRow | undefined, verifiedAt: string): Record<string, unknown>;
+/**
+ * Record a passing BYOA check in `<outDir>/resolutions.json` and return that
+ * path: read (refusing a corrupt file before anything is written), record, write.
+ */
+export declare function recordByoaVerification(outDir: string, nodeType: string, connectionId: string, row: ConnectionRow | undefined, verifiedAt?: string): string;

package/dist/registry/prepare/byoa-ledger.js

@@ -0,0 +1,26 @@
+import { ledgerPath, readLedger, writeLedger } from "./objects.js";
+import { isPlainObject, pyGet, pyStrAny } from "./support.js";
+/**
+ * The ledger with `byoa[nodeType][connectionId]` set to a passing check. Pure:
+ * returns a new ledger. A re-run on the same connection rewrites the entry,
+ * `verifiedAt` included — the check was made again, so the snapshot is newer.
+ */
+export function recordByoa(ledger, nodeType, connectionId, row, verifiedAt) {
+    const sectionIn = ledger.byoa;
+    const section = isPlainObject(sectionIn) ? { ...sectionIn } : {};
+    const perEventIn = section[nodeType];
+    const perEvent = isPlainObject(perEventIn) ? { ...perEventIn } : {};
+    const name = pyStrAny(pyGet(row ?? {}, "Name", "") ?? "");
+    perEvent[connectionId] = { byoa: true, ...(name ? { connectionName: name } : {}), verifiedAt };
+    section[nodeType] = perEvent;
+    return { ...ledger, schemaVersion: "1", byoa: section };
+}
+/**
+ * Record a passing BYOA check in `<outDir>/resolutions.json` and return that
+ * path: read (refusing a corrupt file before anything is written), record, write.
+ */
+export function recordByoaVerification(outDir, nodeType, connectionId, row, verifiedAt = new Date().toISOString().slice(0, 10)) {
+    const path = ledgerPath(outDir);
+    writeLedger(path, recordByoa(readLedger(path), nodeType, connectionId, row, verifiedAt));
+    return path;
+}

package/dist/registry/prepare/event.d.ts

@@ -3,6 +3,7 @@ import { type EventFacts } from "../library-build/events.js";
 import { type Dict } from "../library-build/py.js";
 import type { LibraryEntry } from "../model/library.js";
 import type { UipClient } from "../uip/client.js";
+import { type ConnectionRow } from "./connections.js";
 /**
  * `_event_operation`: the operation key every trigger API takes.
  *
@@ -50,8 +51,11 @@ export interface BindingsRollback {
  * connection into `bindings.json` by the time the event's own metadata says it
  * is the wrong KIND, so the file is restored first. A listing that FAILED is
  * not a tenant with no BYOA connections; the remedies are opposite.
+ *
+ * Returns the connection's BYOA listing row when it passes, for the record
+ * `prepare` then writes (see `byoa-ledger.ts`).
  */
-export declare function refuseUnlessByoaConnection(client: UipClient, connectorKey: string, connectionId: string, rollback: BindingsRollback | undefined, warn: (line: string) => void): Promise<void>;
+export declare function refuseUnlessByoaConnection(client: UipClient, connectorKey: string, connectionId: string, rollback: BindingsRollback | undefined, warn: (line: string) => void): Promise<ConnectionRow>;
 export interface EventPrepareOptions {
     connectorKey: string;
     action: string;

package/dist/registry/prepare/event.js

@@ -21,12 +21,13 @@
  */
 import { extractCanonical, nodeOf } from "../library-build/canonical.js";
 import { registryProbe } from "../library-build/context.js";
-import { EventDiscoveryError, eventFacts, mergeDescribeIntoNode, triggersDescribe, triggersObjects, unionEventParameters, } from "../library-build/events.js";
+import { EventDiscoveryError, eventFacts, mergeDescribeIntoNode, resolveEventFacts, triggersDescribe, triggersObjects, unionEventParameters, } from "../library-build/events.js";
 import { get, isRecord } from "../library-build/py.js";
 import { planLibrary } from "../library-build/plan.js";
+import { recordByoaVerification } from "./byoa-ledger.js";
 import { ConnectionRefusal, byoaConnections, byoaListing, restoreBindings } from "./connections.js";
 import { writeResolutions } from "./ledger.js";
-import { PREPARE_COMMAND, PrepareRefusal, byoaListingFailedMessage, byoaRequiredMessage, describeFallbackWarning, generatedModulesLine, eventAllObjectsMessage, eventNextLine, eventParentFieldsMessage, eventSubscription, eventSummaryLine, filterableFieldsLine, genericEventNeedsObjectMessage, lookupVocabularyLines, objectNoteLine, objectOnCuratedEventMessage, objectRecordedLine, warnLine, webhookNoteLines, } from "./messages.js";
+import { PREPARE_COMMAND, PrepareRefusal, byoaListingFailedMessage, byoaRecordedLine, byoaRequiredMessage, describeFallbackWarning, generatedModulesLine, eventAllObjectsMessage, eventNextLine, eventParentFieldsMessage, eventSubscription, eventSummaryLine, filterableFieldsLine, genericEventNeedsObjectMessage, lookupVocabularyLines, objectNoteLine, objectOnCuratedEventMessage, objectRecordedLine, warnLine, webhookNoteLines, } from "./messages.js";
 import { RESOLUTIONS_FILENAME, matchObject, recordObjectResolution } from "./objects.js";
 import { lookupSpecsFromOverlay, mergeFilesInto } from "./overlay.js";
 import { regenerateDescriptors } from "./regenerate.js";
@@ -62,12 +63,15 @@ export function assembleEventDefinition(node, entry, describe, objectRow, eventN
     const objectParameters = objectRow === undefined ? null : pyGet(objectRow, "Parameters", null);
     let stored;
     if (describe !== undefined) {
-        stored = mergeDescribeIntoNode(node, describe, objectParameters);
+        stored = mergeDescribeIntoNode(node, describe, objectParameters, objectRow ?? null);
     }
     else {
         stored = { ...node };
         const declared = pyOr(get(stored, "eventParameters"), {});
         stored.eventParameters = { fields: unionEventParameters(get(declared, "fields"), objectParameters) };
+        // The row's facts win here too: this definition IS the overlay, and a
+        // describe outage on a BYOA event must not store the registry's `false`.
+        Object.assign(stored, resolveEventFacts(objectRow ?? null, stored));
     }
     const out = { ...entry };
     const outputDefinition = pyOr(get(stored, "outputResponseDefinition"), {});
@@ -88,6 +92,9 @@ export function assembleEventDefinition(node, entry, describe, objectRow, eventN
  * connection into `bindings.json` by the time the event's own metadata says it
  * is the wrong KIND, so the file is restored first. A listing that FAILED is
  * not a tenant with no BYOA connections; the remedies are opposite.
+ *
+ * Returns the connection's BYOA listing row when it passes, for the record
+ * `prepare` then writes (see `byoa-ledger.ts`).
  */
 export async function refuseUnlessByoaConnection(client, connectorKey, connectionId, rollback, warn) {
     const restore = () => {
@@ -104,8 +111,9 @@ export async function refuseUnlessByoaConnection(client, connectorKey, connectio
         restore();
         throw new PrepareRefusal(byoaListingFailedMessage(connectionId, error), "BYOA_LISTING_FAILED");
     }
-    if (rows.some((row) => pyStrAny(pyGet(row, "Id", null)) === connectionId))
-        return;
+    const match = rows.find((row) => pyStrAny(pyGet(row, "Id", null)) === connectionId);
+    if (match)
+        return match;
     restore();
     throw new PrepareRefusal(byoaRequiredMessage(connectionId, connectorKey, byoaListing(rows, connectorKey)), "BYOA_REQUIRED");
 }
@@ -212,14 +220,20 @@ export async function prepareEvent(ctx, options) {
         }
     }
     const facts = eventFacts(node, objectRow ?? null);
-    if (facts.byoaConnection) {
-        await refuseUnlessByoaConnection(ctx.client, connectorKey, connectionId, options.bindings, warn);
-    }
+    const byoaRow = facts.byoaConnection
+        ? await refuseUnlessByoaConnection(ctx.client, connectorKey, connectionId, options.bindings, warn)
+        : undefined;
     const definition = assembleEventDefinition(node, entry, describe, objectRow, eventNodeType);
     const plan = planLibrary([definition.entry], () => definition.node);
     for (const line of plan.warnings)
         warn(line);
     mergeFilesInto(plan.files, out);
+    if (byoaRow !== undefined) {
+        // What `check` and `compile` look for before they accept this event on this
+        // connection: the proof that the live check above ran and passed.
+        recordByoaVerification(out, eventNodeType, connectionId, byoaRow);
+        info(byoaRecordedLine(connectionId, pyPathJoin(outShown, RESOLUTIONS_FILENAME)));
+    }
     if (generic) {
         recordObjectResolution(out, eventNodeType, requestedObject, objectRow, operation);
         // Named as the author spelled `--out`, not as the file was resolved.

package/dist/registry/prepare/messages.d.ts

@@ -237,6 +237,8 @@ export declare function warnLine(error: unknown): string;
 /** The describe could not answer for a curated event; the definition's own sections stand in. */
 export declare function describeFallbackWarning(error: unknown, bakedObject: string): string;
 export declare function byoaListingFailedMessage(connectionId: string, error: unknown): string;
+/** The passing BYOA check, and where it was recorded for `check` / `compile`. */
+export declare function byoaRecordedLine(connectionId: string, ledgerPath: string): string;
 export declare function byoaRequiredMessage(connectionId: string, connectorKey: string, listing: string): string;
 export declare function eventSummaryLine(eventNodeType: string, out: string, operation: string, mode: string, whereParameters: number, filterFields: number): string;
 /** The first eight filterable field names, or nothing when the event has none. */

package/dist/registry/prepare/messages.js

@@ -548,6 +548,10 @@ export function byoaListingFailedMessage(connectionId, error) {
         "(bring-your-own-app) connection, and the BYOA listing needed to " +
         `check ${connectionId} against it failed: ${messageOf(error)}`);
 }
+/** The passing BYOA check, and where it was recorded for `check` / `compile`. */
+export function byoaRecordedLine(connectionId, ledgerPath) {
+    return `  byoa: ${connectionId} is a BYOA connection — recorded in ${ledgerPath}`;
+}
 export function byoaRequiredMessage(connectionId, connectorKey, listing) {
     return (`${PREFIX}this event object requires a BYOA ` +
         `(bring-your-own-app) connection, and ${connectionId} is not ` +

package/dist/serialize.js

@@ -16,6 +16,7 @@ import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { dataFabricUnknownInputs } from './core/typed-raw-node.js';
 import { isAnswerField } from './core/hitl-answers.js';
 import { BindingRefusal, GUID_RE, bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
+import { ByoaRefusal, byoaUnverified } from './core/byoa.js';
 import { OUTCOME_HANDLE_NODE_TYPES, assertHitlExitInvariant, hitlExitModel, hitlExitViolation, outcomeSlug } from './core/hitl-routing.js';
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { buildConfiguration, transportHttpMethod } from './config.js';
@@ -3212,6 +3213,24 @@ function eventTarget(sub) {
         ? { key: sub.connector, ...(typeof sub.event === 'string' && sub.event !== '' ? { action: sub.event } : {}) }
         : undefined;
 }
+/**
+ * Throw `check`'s EVENT_BYOA_UNVERIFIED for a subscription whose event only
+ * fires on a BYOA connection and whose bound connection `prepare` never checked
+ * — the one condition in `core/byoa.ts`, fed from the same library and
+ * bindings, so a flow check refuses never compiles.
+ *
+ * `where` is check's spelling of the site (`trigger` for `onEvent`, entry points
+ * included; `waitForEvent "<step>"`), so the two print the same sentence.
+ */
+function refuseUnverifiedByoa(opts, where, sub) {
+    const library = opts.library;
+    if (!library || typeof library.eventFacts !== 'function')
+        return;
+    const object = typeof sub.object === 'string' && sub.object !== '' ? sub.object : undefined;
+    const message = byoaUnverified(where, { connector: sub.connector, event: sub.event, ...(object ? { object } : {}), connection: sub.connection }, library.eventFacts(sub.connector, sub.event, object), library.byoaVerifications, opts.bindings);
+    if (message)
+        throw new ByoaRefusal(message);
+}
 /**
  * Resolve a symbolic connection/folder name to the resource key that is inlined
  * as `connectionId` / `connectionFolderKey`.
@@ -4184,7 +4203,9 @@ export function serialize(built, opts = {}) {
             if (!opts.library)
                 throw new Error(`onEvent() needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
             const sub = built.trigger.subscription;
-            return opts.library.resolveEvent('trigger', sub.connector, sub.event, sub.version, sub.object);
+            const rc = opts.library.resolveEvent('trigger', sub.connector, sub.event, sub.version, sub.object);
+            refuseUnverifiedByoa(opts, 'trigger', sub);
+            return rc;
         })()
         : undefined;
     // The trigger node's id is `start` unless the flow renamed it. `input('x')`
@@ -5306,6 +5327,7 @@ export function serialize(built, opts = {}) {
                 throw new Error(`waitForEvent "${step.name}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
             const sub = spec.subscription;
             const rc = opts.library.resolveEvent('event', sub.connector, sub.event, sub.version, sub.object);
+            refuseUnverifiedByoa(opts, `waitForEvent "${step.name}"`, sub);
             const id = stepUid(scope, step.name);
             const node = makeNode(rc.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def: rc.v1def });
             node.inputs = { detail: eventDetail(rc, sub, id, opts) };
@@ -6160,6 +6182,7 @@ export function serialize(built, opts = {}) {
                     throw new Error(`onEvent() needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
                 const sub = epSpec.subscription;
                 const rc = opts.library.resolveEvent('trigger', sub.connector, sub.event, sub.version, sub.object);
+                refuseUnverifiedByoa(opts, 'trigger', sub);
                 node = makeNode(rc.nodeType, ep.id, 'Event trigger', { def: rc.v1def, requestedVersion });
                 node.inputs = {
                     entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.11.5",
+  "version": "6.11.6",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "db9c4cfda2ffb8c391dc11eb75786eda3c08edcb"
+  "gitref": "db117054e312c3c2aa7b7b208d3a92fc68de7fb9"
 }