@uipath/maestro-builder-sdk 6.11.4 → 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

@@ -8,6 +8,7 @@
 import { Expr, SCHEDULE_PRESETS, DELAY_PRESETS, VARIANT_OPERATION, parseIxpProjectType, flatNameOf, flatNameSegmentsOf, FLAT_SEP } from './flow-sdk.js';
 import { FlowNode } from './core/node-classes.js';
 import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './core/lookups.js';
+import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
 import { extractRefs } from './core/expr-check.js';
 import { bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
@@ -17,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);
 }
@@ -145,20 +147,12 @@ function checkFlow(built, ancestors, opts = {}) {
     // form's ANSWER fields (plus `Action`), so a read of it is checked against the
     // form the author wrote rather than waved through (see HITL_READ_* below).
     const hitlForms = new Map();
-    const apiWorkflows = new Map();
-    const publishedFunctions = new Map();
-    // Agentic-process step name → its call. Same reason as api-workflow's map: the
-    // step publishes the job's output arguments and the only offline statement of
-    // what those are is the step's own `returns`.
+    // Agentic-process step name → its call, for the form-field rules below. Its
+    // output READS go through OUTPUT_READ_RULES like every `returns` family.
     const agenticProcesses = new Map();
-    // Published-agent step name → its call. Same reason again: the step publishes the
-    // agent job's output arguments, and the only offline statement of what those are
-    // is the step's own `returns`.
-    const agents = new Map();
-    // Inline-agent step name → its call. NOT the same reason: an inline agent's
-    // contract is AUTHORED rather than looked up on a tenant, so a read outside the
-    // declared `returns` is a mistake the compiler can be certain about.
-    const inlineAgents = new Map();
+    // Step name → the read rule for its output, bound to its inputs. Filled from
+    // OUTPUT_READ_RULES for every kind whose inputs take a `returns`.
+    const outputReaders = new Map();
     const connectorSteps = new Map();
     // Subflow step name → the child flow it runs. A subflow's output is the
     // OBJECT of the child's declared outputs, so a read of it is checked against
@@ -434,11 +428,9 @@ function checkFlow(built, ancestors, opts = {}) {
                     checkRpaWorkflow(s.name, s.spec.inputs, diags);
                 if (s.spec.kind === 'apiWorkflow') {
                     checkApiWorkflow(s.name, s.spec.inputs, diags);
-                    apiWorkflows.set(s.name, s.spec.inputs);
                 }
                 if (s.spec.kind === 'publishedFunction') {
                     checkPublishedFunction(s.name, s.spec.inputs, diags);
-                    publishedFunctions.set(s.name, s.spec.inputs);
                 }
                 if (s.spec.kind === 'sendMessage' || s.spec.kind === 'waitForMessage'
                     || s.spec.kind === 'conversationContext') {
@@ -456,14 +448,20 @@ function checkFlow(built, ancestors, opts = {}) {
                 }
                 if (s.spec.kind === 'agent') {
                     checkAgent(s.name, s.spec.inputs, diags);
-                    agents.set(s.name, s.spec.inputs);
                 }
                 if (s.spec.kind === 'inlineAgent') {
                     checkInlineAgent(s.name, s.spec.inputs, diags);
-                    inlineAgents.set(s.name, s.spec.inputs);
                 }
                 if (s.spec.kind === 'queueItem')
                     checkQueueItem(s.name, s.spec.inputs, diags);
+                {
+                    const rule = OUTPUT_READ_RULES[s.spec.kind];
+                    if (typeof rule === 'function') {
+                        const stepName = s.name;
+                        const inputs = s.spec.inputs;
+                        outputReaders.set(stepName, (field, rest, at, d) => rule(stepName, field, rest, inputs, at, d));
+                    }
+                }
                 if (s.spec.kind === 'documentClassify' || s.spec.kind === 'dynamicExtract') {
                     const fr = s.spec.inputs.fileRef;
                     const empty = fr === undefined || fr === null || (typeof fr === 'string' && fr.trim() === '');
@@ -1168,49 +1166,13 @@ function checkFlow(built, ancestors, opts = {}) {
                 checkHitlRead(name, field, rest, form, step, diags);
                 continue;
             }
-            // An API workflow publishes the job's output arguments, and the only offline
-            // statement of what those are is the step's own `returns`. A read of anything
-            // else is `undefined` on every rung and on the platform — and with no
-            // `returns` at all the node declares no output schema, so nothing downstream
-            // can tell a real field from a typo.
-            const apiwf = apiWorkflows.get(name);
-            if (apiwf) {
-                checkApiWorkflowRead(name, field, rest, apiwf, step, diags);
-                continue;
-            }
-            // A published function publishes its result the same way, and the same
-            // three read mistakes are decidable from the same place — so the reader is
-            // shared, with the family named in the codes.
-            const fn = publishedFunctions.get(name);
-            if (fn) {
-                checkPublishedFunctionRead(name, field, rest, fn, step, diags);
-                continue;
-            }
-            // An agentic process publishes its job's output arguments the same way, so
-            // the same three read mistakes are decidable from the same place.
-            const agentic = agenticProcesses.get(name);
-            if (agentic) {
-                checkAgenticProcessRead(name, field, rest, agentic, step, diags);
-                continue;
-            }
-            // A published agent publishes its job's output arguments the same way its
-            // three siblings do, so the same three read mistakes are decidable — with one
-            // extra that only this family has: a read whose CASE differs from the declared
-            // field. That used to be a live-only defect (the poll verb PascalCased the
-            // answer, flow-builder-sdk #122), so the wrong case was right live and wrong
-            // offline for a while. Now it is simply wrong, and worth naming as itself
-            // rather than as an unknown field.
-            const published = agents.get(name);
-            if (published) {
-                checkAgentRead(name, field, rest, published, step, diags);
-                continue;
-            }
-            // An inline agent's readable fields are exactly its declared `returns` — the
-            // node's `agentOutputVariables`, which is also what the engine's live path
-            // coerces the model's completion to. Nothing on a tenant to consult.
-            const inline = inlineAgents.get(name);
-            if (inline) {
-                checkInlineAgentRead(name, field, rest, inline, step, diags);
+            // Every family that declares its output's fields — the author's `returns`, or
+            // a shape the SDK fixes — has its read rule in OUTPUT_READ_RULES, keyed by
+            // kind. A read outside the declared set is undefined on every rung and on
+            // the platform, so it is refused here rather than at `flow debug`.
+            const readOutput = outputReaders.get(name);
+            if (readOutput) {
+                readOutput(field, rest, step, diags);
                 continue;
             }
             // A loop step exposes a fixed set of fields, and only those resolve at run
@@ -1992,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
@@ -2027,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
@@ -2815,6 +2787,175 @@ function checkPublishedFunctionRead(name, field, rest, spec, step, diags) {
         suggestion: `returns: { ${wanted}: 'string' }`,
     });
 }
+/**
+ * The fields every HTTP response carries at the top of `output`, whatever the
+ * API answered. `core.action.http`'s definition declares all three; the author's
+ * `returns` describes what is INSIDE `body`, never beside it.
+ */
+const HTTP_ENVELOPE_FIELDS = ['body', 'statusCode', 'headers'];
+/**
+ * A read of an `http()` step's result.
+ *
+ * The response is an envelope — `{ body, statusCode, headers }` — and `returns`
+ * declares the parsed JSON body's top-level fields, so a declared field is read
+ * at `output.body.<field>` (`out('<step>', 'body.<field>')`). That nesting is the
+ * one thing this family does not share with the process families, and it is
+ * exactly where flow-builder-sdk#850's run went wrong: a branch kept reading
+ * `output.currentDayForecast…` (the Azure Maps connector's path) after the step
+ * became an Open-Meteo `http()`, passed `check` and `validate`, and faulted at
+ * `flow debug` as `[400302]`.
+ */
+function checkHttpRead(name, field, rest, spec, step, diags) {
+    if (field === undefined)
+        return; // `out('fetch')` — the whole response.
+    if (field === 'error')
+        return; // the failure envelope (managed http's error port).
+    if (field !== 'output') {
+        diags.push({
+            level: 'error', code: 'HTTP_READ_NOT_OUTPUT', step,
+            message: `HTTP step "${name}" publishes its response under "output", but "$vars.${name}.${field}" `
+                + `(read in "${step}") asks for "${field}", which is undefined at run time.`,
+            suggestion: `out('${name}', 'body.<field>')`,
+        });
+        return;
+    }
+    const [top, inner] = (rest ?? '').replace(/^\./, '').split('.');
+    if (!top)
+        return; // `$vars.<name>.output` — the whole envelope.
+    const declared = Object.keys(spec?.returns ?? {});
+    if (!HTTP_ENVELOPE_FIELDS.includes(top)) {
+        // The commonest form: a declared body field read one level too high.
+        const hoisted = declared.includes(top) ? top : undefined;
+        const nearest = hoisted ?? nearestName(top, declared);
+        diags.push({
+            level: 'error', code: 'HTTP_READ_UNKNOWN_FIELD', step,
+            message: `"$vars.${name}.output.${top}" (read in "${step}") is not a field of HTTP step "${name}"'s `
+                + `response. An HTTP response publishes ${HTTP_ENVELOPE_FIELDS.map((f) => `"${f}"`).join(', ')}; `
+                + `the fields \`returns\` declares live under "body"`
+                + (hoisted ? `, so "${top}" is read as "$vars.${name}.output.body.${top}".` : '.')
+                + ` A read outside that shape resolves to undefined and faults a gateway at run time.`,
+            ...(nearest !== undefined ? { suggestion: `out('${name}', 'body.${nearest}')` } : {}),
+        });
+        return;
+    }
+    if (top !== 'body' || !inner)
+        return; // `statusCode`, `headers`, or the whole body.
+    if (declared.length === 0) {
+        diags.push({
+            level: 'error', code: 'HTTP_READ_WITHOUT_RETURNS', step,
+            message: `"$vars.${name}.output.body.${inner}" (read in "${step}") reads a field of HTTP step "${name}"'s `
+                + `response body, but the step declares no \`returns\` — so the node carries no body schema and nothing `
+                + `can tell a real field from a typo. Only the API being called knows its body; declare the fields you read.`,
+            suggestion: `returns: { ${inner}: 'string' }`,
+        });
+        return;
+    }
+    if (declared.includes(inner))
+        return;
+    const nearest = nearestName(inner, declared);
+    diags.push({
+        level: 'error', code: 'HTTP_READ_UNKNOWN_FIELD', step,
+        message: `HTTP step "${name}" declares no body field "${inner}" (read as "$vars.${name}.output.body.${inner}" `
+            + `in "${step}"). Its \`returns\` names: ${declared.join(', ')}. A read outside that set resolves to undefined.`,
+        ...(nearest !== undefined ? { suggestion: `out('${name}', 'body.${nearest}')` } : {}),
+    });
+}
+/**
+ * The read rule the process-shaped families share: the result is published
+ * under `output`, keyed by a known field list — the author's `returns`, or a
+ * shape the SDK itself fixes. `declared: undefined` means "the author declared
+ * nothing", which is its own mistake (`<PREFIX>_READ_WITHOUT_RETURNS`).
+ */
+function checkDeclaredOutputRead(o) {
+    const { prefix, what, name, field, rest, step, diags } = o;
+    if (field === undefined || field === 'error')
+        return;
+    if (field !== 'output') {
+        diags.push({
+            level: 'error', code: `${prefix}_READ_NOT_OUTPUT`, step,
+            message: `${what} "${name}" publishes its result under "output", but "$vars.${name}.${field}" `
+                + `(read in "${step}") asks for "${field}", which is undefined at run time.`,
+            suggestion: `out('${name}', '<field>')`,
+        });
+        return;
+    }
+    const wanted = (rest ?? '').replace(/^\./, '').split('.')[0];
+    if (!wanted)
+        return;
+    if (o.declared === undefined) {
+        diags.push({
+            level: 'error', code: `${prefix}_READ_WITHOUT_RETURNS`, step,
+            message: `"$vars.${name}.output.${wanted}" (read in "${step}") reads a field of ${what} "${name}"'s result, `
+                + `but the step declares no \`returns\` — so the node carries no output schema and nothing can tell a `
+                + `real field from a typo. ${o.withoutReturns}`,
+            suggestion: `returns: { ${wanted}: 'string' }`,
+        });
+        return;
+    }
+    if (o.declared.includes(wanted))
+        return;
+    const nearest = nearestName(wanted, o.declared);
+    diags.push({
+        level: 'error', code: `${prefix}_READ_UNKNOWN_FIELD`, step,
+        message: `${what} "${name}" declares no output "${wanted}" (read as "$vars.${name}.output.${wanted}" in `
+            + `"${step}"). It publishes: ${o.declared.join(', ')}. A read outside that set resolves to undefined.`,
+        ...(nearest !== undefined ? { suggestion: `out('${name}', '${nearest}')` } : {}),
+    });
+}
+function checkRpaWorkflowRead(name, field, rest, spec, step, diags) {
+    const declared = Object.keys(spec?.returns ?? {});
+    checkDeclaredOutputRead({
+        prefix: 'RPA', what: 'RPA process', name, field, rest, step, diags,
+        declared: declared.length ? declared : undefined,
+        withoutReturns: `The process's output arguments live on the tenant; declare the ones you read. `
+            + `\`uip maestro flow registry get uipath.core.rpa-workflow.${spec?.key}\` shows what the platform `
+            + `synthesizes for it.`,
+    });
+}
+/**
+ * A queue step publishes one of two shapes: a plain enqueue publishes the queue
+ * ITEM's Orchestrator record (fixed, declared by the serializer from
+ * `QUEUE_ITEM_RECORD_SCHEMA`), a `wait: true` publishes the processed result,
+ * whose fields only the author's `returns` states.
+ */
+function checkQueueItemRead(name, field, rest, spec, step, diags) {
+    const waitReturns = Object.keys(spec?.returns ?? {});
+    checkDeclaredOutputRead({
+        prefix: 'QUEUE', what: spec?.wait ? 'Queue wait' : 'Queue item', name, field, rest, step, diags,
+        declared: !spec?.wait
+            ? Object.keys(QUEUE_ITEM_RECORD_SCHEMA.properties)
+            : waitReturns.length ? waitReturns : undefined,
+        withoutReturns: `What the consumer writes into the processed item's result is that automation's business; `
+            + `declare the fields you read.`,
+    });
+}
+/**
+ * THE GATE (flow-builder-sdk#850). Each `returns`-bearing kind maps to the rule
+ * that checks a read of its output, or to a stated reason it has none.
+ *
+ * Before this table each family's rule was wired by hand — a map filled in the
+ * walk plus a branch in the `$vars` dispatch — and nothing tied "this family
+ * takes `returns`" to "this family has a read rule". `http`, `rpaWorkflow` and
+ * `queueItem` shipped without one, so a read of an undeclared field passed
+ * `check` and `validate` and only faulted live. The type below is exhaustive
+ * over the derived kinds: give a new family a `returns` and `tsc` refuses to
+ * build until it lands here.
+ */
+const OUTPUT_READ_RULES = {
+    http: checkHttpRead,
+    rpaWorkflow: checkRpaWorkflowRead,
+    apiWorkflow: checkApiWorkflowRead,
+    publishedFunction: checkPublishedFunctionRead,
+    agenticProcess: checkAgenticProcessRead,
+    agent: checkAgentRead,
+    inlineAgent: checkInlineAgentRead,
+    queueItem: checkQueueItemRead,
+    script: {
+        exempt: 'Not yet: only the field-map form of a script\'s `returns` gives a list to check against (the '
+            + 'type form and the inferred form do not), and script is the most-used step, so its rule lands with '
+            + 'its own false-positive sweep — flow-builder-sdk#855.',
+    },
+};
 function checkApiWorkflowRead(name, field, rest, spec, step, diags) {
     if (field === undefined)
         return; // `out('call')` — the whole output object.

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/actions.d.ts

@@ -82,6 +82,16 @@ interface HttpInputsBase {
      * fields, and nothing downstream can tell a real field from a typo. Same rule,
      * and the same word, as
      * `rpaWorkflow`'s `returns`.
+     *
+     * **Where a declared field is read:** under `body`, never beside it. The
+     * response is an envelope — `{ body, statusCode, headers }` — and these are the
+     * body's fields, so `returns: { items: 'array' }` is read as
+     * `out('fetch', 'body.items')`, which is `$vars.fetch.output.body.items`.
+     * `$vars.fetch.output.items` is undefined at run time.
+     *
+     * @enforcedBy HTTP_READ_UNKNOWN_FIELD A read must be `output.body.<declared field>`,
+     * `output.statusCode` or `output.headers`.
+     * @enforcedBy HTTP_READ_WITHOUT_RETURNS Reading a body field requires declaring it here.
      */
     returns?: Record<string, ReturnFieldType>;
     /**
@@ -991,6 +1001,9 @@ export interface RpaWorkflowInputs {
      * the fields here is the same thing the platform's own definition does when it
      * can reach the process, and it is what lets a misspelled read be caught at
      * `uip maestro flow check` instead of at run time.
+     *
+     * @enforcedBy RPA_READ_UNKNOWN_FIELD A read of the output must name a field declared here.
+     * @enforcedBy RPA_READ_WITHOUT_RETURNS Reading a field off the result requires declaring it here.
      */
     returns?: Record<string, ReturnFieldType>;
 }
@@ -2035,6 +2048,11 @@ export interface QueueItemInputs {
      * `wait: false` needs none: what it publishes is the queue ITEM's own
      * Orchestrator record (`Key`, `Status`, `Reference`, `SpecificContent`, …),
      * which is the same for every queue, so the serializer declares it for you.
+     *
+     * @enforcedBy QUEUE_READ_UNKNOWN_FIELD A read must name a field of the record
+     * (`wait: false`) or of this `returns` (`wait: true`).
+     * @enforcedBy QUEUE_READ_WITHOUT_RETURNS Reading a field off a `wait: true` result
+     * requires declaring it here.
      */
     returns?: Record<string, ReturnFieldType>;
 }

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;