@uipath/maestro-builder-sdk 5.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UiPath, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# Maestro Builder SDK
+
+Build a UiPath Maestro Flow, Case Plan, or BPMN by writing a small, readable TypeScript program.
+You describe the orchestration's shape by calling methods (`.step`, `.branch`, `.loop`); the SDK compiles it to a valid `.flow`/`caseplan.json`/`.bpmn` that UiPath can run and open in the designer.
+
+This is a builder, not a program - nothing executes at author time except graph construction.
+Data flows through named variables and expressions — you never write native `if`/`for`.
+
+## Quick start
+
+Install the SDK:
+
+```bash
+npm install @uipath/maestro-builder-sdk
+```
+
+### Author
+
+A whole flow is one file. `HelloWorld.flow.ts`:
+
+```ts
+import { flow, script, out, types } from '@uipath/maestro-builder-sdk';
+
+export default flow('hello-world')
+  .name('HelloWorld')
+  .input({ name: types.string })
+  .output({ greeting: types.string })
+  .step('greet', script({
+    code: "return 'Hello, ' + $vars.start.output.name + '!';",
+  }))
+  .return({ greeting: out('greet') })
+  .build();
+```
+
+`.input` and `.output` are the flow's contract. `.step` adds a node — here a
+`script`, whose `code` runs on the platform, not at author time. Steps read each
+other through named variables: `$vars.start.output.name` inside the script,
+`out('greet')` in the builder. There is no `.trigger()` call, so the flow gets a
+manual trigger.
+
+### Check
+
+```bash
+uip maestro flow check HelloWorld.flow.ts --source
+```
+
+```
+✓ no issues
+```
+
+`check` reads the source without emitting anything. It is the fast pass: an
+undeclared variable, a step name that does not exist, an empty branch arm.
+
+### Compile
+
+```bash
+uip maestro flow compile HelloWorld
+```
+
+```
+compile: wrote HelloWorld.flow (3 nodes, 2 edges)
+```
+
+Three nodes: the trigger, the script, and the End that `.return()` created. That
+`.flow` is what UiPath runs and what the designer opens.
+
+For a flow that calls nothing outside itself, that is the whole loop —
+**author → check → compile**.
+
+### Prepare
+
+The moment a step calls a connector, a fourth verb appears. Add one:
+
+```ts
+import { flow, script, connector, lookup, out, types } from '@uipath/maestro-builder-sdk';
+
+const SLACK = { connection: 'slack', folder: 'shared' } as const;
+const SLACK_DM = ['uipath-salesforce-slack', 'send-message-to-user'] as const;
+
+export default flow('hello-world')
+  .name('HelloWorld')
+  .input({ name: types.string })
+  .output({ greeting: types.string })
+  .step('greet', script({
+    code: "return 'Hello, ' + $vars.start.output.name + '!';",
+  }))
+  .step('announce', connector(...SLACK_DM, {
+    channel: lookup(...SLACK_DM, 'channel').by('profile.email', 'ada@example.com'),
+    send_as: lookup(...SLACK_DM, 'send_as').by('name', 'bot'),
+    messageToSend: out('greet'),
+  }, SLACK))
+  .return({ greeting: out('greet') })
+  .build();
+```
+
+Two things there are deliberately *not* ids. `channel` and `send_as` are lookup
+fields: their real values are opaque ids belonging to one connection, so you
+write what you mean — an email address, the word `bot` — and `lookup()` records
+the question. Now `check` has something to say:
+
+```
+⚠ [LOOKUP_UNRESOLVED] Connector step "announce": input "channel" is an unresolved
+  lookup (profile.email="ada@example.com"). Compile does not make network calls, so
+  the value has to be resolved first:
+    npx flow-sdk registry prepare uipath-salesforce-slack send-message-to-user \
+      --resolve channel:profile.email=ada@example.com
+  Compile will fail until this is recorded.
+
+⚠ [LOOKUP_UNRESOLVED] … and the same for "send_as" (name="bot").
+```
+
+Warnings, not errors — the source pass still succeeds. It is `compile` that
+refuses, because resolving a lookup means asking the tenant and compile makes no
+network calls. That is what `prepare` is for: it is the one verb that does talk
+to the tenant. Run what `check` named, both fields at once:
+
+```bash
+npx flow-sdk registry pull    # once per machine: the connector library
+
+npx flow-sdk registry prepare uipath-salesforce-slack send-message-to-user \
+  --resolve channel:profile.email=ada@example.com \
+  --resolve send_as:name=bot
+```
+
+`registry pull` is the prerequisite, not part of the loop: `check` and `compile`
+read connector field schemas from that library, and without it a connector step
+reports its lookups as unresolved no matter how many times you prepare.
+
+It does three things, all of them on disk:
+
+- finds the connection and writes its ids into `bindings.json`, so the symbolic
+  `slack` and `shared` names in the code resolve;
+- records each answered lookup in `connectors-local/`, so compiling stays
+  offline and repeatable;
+- writes the connection-resolved field schema for that operation, which is how
+  a field the static library does not know about becomes compilable at all.
+
+Then the same two commands as before:
+
+```bash
+uip maestro flow check HelloWorld.flow.ts --source   # ✓ no issues
+uip maestro flow compile HelloWorld                  # wrote HelloWorld.flow (4 nodes, 3 edges)
+```
+
+**Author → check → prepare → check → compile.** `check` before `prepare` is the
+cheap order: one pass names every resolution the flow owes, so you make one trip
+to the tenant instead of one per field.
+
+### Case plans and BPMN
+
+The same builder core, the same four verbs. Import from
+`@uipath/maestro-builder-sdk/case` or `@uipath/maestro-builder-sdk/bpmn`, name the file
+`<Name>.case.ts` or `<Name>.bpmn.ts`, and swap the family in the command:
+`uip maestro case compile` / `uip maestro bpmn compile`. Their builder surfaces
+are `case-api.md` and `bpmn-api.md` in the authoring guides.
+
+## Commands
+
+The UiPath CLI is the authoring front door. Beyond the two verbs the quick start
+uses:
+
+```bash
+uip maestro flow check HelloWorld.flow --compiled   # deep validation of the ARTIFACT
+uip maestro flow validate HelloWorld.flow           # the product validator
+uip maestro flow debug HelloWorld.flow              # run it
+```
+
+`build()` itself runs a **first-level check** as it constructs the graph: an
+undeclared `$vars` reference — a mistyped variable or step name in a `` js`…` ``
+expression or script — throws a `FlowBuildError` right there, before anything is
+emitted. `uip maestro flow check --source` runs the authored-source checks without
+emitting. For a COMPILED `.flow`, `uip maestro flow validate` is the authoritative
+product validator, and `uip maestro flow debug` (or `flow-debug`) runs it. Case and BPMN use the same family-first shape:
+`uip maestro case compile|check|decompile` and
+`uip maestro bpmn compile|check|format`.
+
+These commands require a prerelease of `@uipath/cli` that exposes the preview
+authoring verbs.
+
+### UiPath CLI delegation contract
+
+The UiPath CLI resolves `@uipath/maestro-builder-sdk/package.json` from the caller's current
+directory, checks the installed version, and spawns
+`node <package>/dist/cli/index.js <family> <verb> …` with inherited cwd, environment,
+and stdio. It never imports or bundles the SDK. This preserves the runtime class
+identity shared by the authored TypeScript and serializer.
+
+The stable argv grammar is family first: `flow|case|bpmn`, then the SDK verb and
+its documented options. The process exit contract is `0` for success, `1` for
+diagnostics, and `2` for usage errors or a blocked mode. Changes to the spawn path,
+argv grammar, or exit meanings are semver-governed. The package also declares the
+`@uipath/maestro-builder-sdk/cli` export for tooling that needs to verify this surface; normal
+authors should invoke it through `uip maestro`.
+
+For `uip maestro flow check --compiled --uip`, the SDK's checker starts a nested
+`uip maestro flow registry get` process to resolve missing schemas. This is
+intentional and does not recurse into `check`. Set `UIP_BIN` to an alternate uip
+executable when the desired binary is not the one on `PATH`.
+
+## What you can express
+
+Every node type the platform runs has a builder form. Control flow and data:
+
+`core.trigger.manual` · `core.trigger.scheduled` · `core.logic.decision`
+(`.branch`) · `core.logic.switch` · `core.logic.merge` (`.parallel`) ·
+`core.logic.loop` · `core.logic.terminate` · `core.control.end` (`.return`) ·
+`core.subflow` · `core.logic.delay` · `core.logic.mock`
+
+Work:
+
+`core.action.script` · `core.action.transform` (+ `.map` / `.filter` /
+`.group-by`) · `core.action.http` and `core.action.http.v2` ·
+`core.action.queue.create` and `.create-and-wait` ·
+`uipath.connector.<key>.<action>` · `uipath.connector.trigger.<key>.<event>` and
+`uipath.connector.event.<key>.<event>` · `uipath.human-in-the-loop` (+
+`.quick-form`, `.coded-action-app`) · `uipath.core.rpa-workflow.<key>` ·
+`uipath.core.api-workflow.<key>` · `uipath.core.agentic-process.<key>` ·
+`uipath.core.agent.<key>` · `uipath.agent.autonomous` ·
+`uipath.pattern.deep-rag` (`summarize`) · `uipath.pattern.batch-transform` ·
+`uipath.ixp.*` (`ixpExtract`)
+
+An error port (`.onError`, whose handler can rejoin the success path with
+`h.rejoin('step')`), per-arm labels, and switch arms with their own terminal
+outputs are constructs rather than node types.
+
+Anything that names a tenant resource — a release key, a published extraction
+model, a queue consumer, a connector connection — needs that id or a `lookup()`
+resolved through `prepare`, as in the quick start. The authoring guides carry a
+worked example per node type.
+
+## The API in two parts
+
+- **Control flow & lifecycle** are *fluent methods* on the builder:
+  `.name` · `.version` · `.input` · `.output` · `.var` · `.trigger` · `.step` ·
+  `.branch` · `.switch` · `.parallel` · `.loop` · `.onError` (whose handler can
+  end by rejoining the success path — `h.rejoin('step')`) · `.terminate` ·
+  `.return` · `.build`. Inside a `.branch` / `.switch` arm, `.label('…')` names
+  that arm — the label round-trips to and from the `.flow`
+  (`trueLabel` / `falseLabel` on a decision, the case `label` on a switch).
+- **Actions** are *factory functions* passed to `.step(name, action)`:
+  `http` · `script` · `transform` · `hitl` · `delay` · `queueItem` · `connector` ·
+  `waitForEvent` · `rpaWorkflow` · `apiWorkflow` · `agenticProcess` · `agent` ·
+  `inlineAgent` · `subflow` · `summarize` · `batchTransform` · `ixpExtract` ·
+  `mock`.
+- **Expressions**: `lit` · `v` / `input` · `out` · `err` · `ran` · `` js`…` `` ·
+  `` tmpl`…` `` · `types.{string,number,boolean,object,array,file,any}`.
+
+Every node type, its builder API, ports, and a minimal example are in the Flow
+authoring guide, `SKILL.md` — its router table is the complete reference. See
+[The authoring guides](#the-authoring-guides).
+
+### Signature reference
+
+Exact signatures travel with the package, as TSDoc on the declarations in
+`dist/`: parameters, defaults, remarks and worked examples for every exported
+symbol, surfaced by an editor on hover. The authoring guides carry the same
+reference as Markdown.
+
+## Integration Service connectors
+
+A flow that calls a connector needs a `bindings.json` alongside it, mapping the
+symbolic `connection` / `folder` names in the code — `slack` and `shared` in the
+quick start — to real ids. `registry prepare` writes it; this is the shape, if
+you would rather fill it from
+`uip is connections list --all-folders --output json`:
+
+```json
+{
+  "schemaVersion": "1",
+  "bindings": [
+    { "id": "slack", "name": "slack", "resource": "Connection",
+      "resourceKey": "<connection-id>", "propertyAttribute": "ConnectionId" },
+    { "id": "shared", "name": "shared", "resource": "Connection",
+      "resourceKey": "<folder-key>", "propertyAttribute": "FolderKey" }
+  ]
+}
+```
+
+Keeping the names symbolic is what lets one flow move between connections: the
+code says `slack`, and only `bindings.json` knows which Slack.
+
+Discover ops and input shapes from the connector library that
+`npx flow-sdk registry pull` downloads and caches. A field the library does not
+carry is connection-specific — that is the `prepare` case from the quick start.
+
+The package also exposes the low-level materializer used by the UiPath CLI to
+derive the Markdown catalog and typed descriptors from canonical JSON:
+
+```bash
+flow-registry-materialize \
+  --library-json ./library-json \
+  --library-md ./library-md \
+  --connectors ./connectors
+```
+
+Most callers want `npx flow-sdk registry pull`, which downloads the published
+archive, verifies its checksum and then runs this transform. The low-level
+command is for SDK development, build pipelines, and troubleshooting: it only
+transforms local files that are already on disk.
+
+**Connector event triggers and waits** (`onEvent` / `waitForEvent`) additionally
+need a definition *pair* in the library. Curated pairs are published for
+**Outlook**, **HTTP Webhook**, and **OneDrive**; any other connector's pair is
+generated on demand from live registry evidence. The authoring guides'
+`references/event-trigger.md` has the commands and the evidence bar.
+
+## The authoring guides
+
+This package is the **API**: `dist/` and this README.
+
+The step-by-step authoring guides — `SKILL.md` for Flow, `SKILL-case.md`,
+`SKILL-bpmn.md`, and the per-node detail under `references/` — ship with the
+UiPath authoring skills catalog rather than here, so a coding agent and a human
+read the same copy. The worked examples named by those guides travel with them.
+
+The connector library is not bundled: `npx flow-sdk registry pull` downloads it
+and caches it per machine. The package does carry the curated overlay that pull
+applies on top — corrections and the definitions the raw registry dump omits.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/bindings-v2.d.ts

@@ -0,0 +1,37 @@
+/** One declared solution resource. */
+export interface BindingsV2Resource {
+    resource: string;
+    key: string;
+    id: string;
+    value: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** The `bindings_v2.json` document. */
+export interface BindingsV2Document {
+    version: string;
+    resources: BindingsV2Resource[];
+    [k: string]: unknown;
+}
+/**
+ * The `connection` resources a compiled flow declares — one per distinct
+ * connection, in node order, attributed to the FIRST node that uses it.
+ *
+ * Both halves of that are pack's behaviour, not a choice made here: a flow with
+ * two Outlook steps on one connection yields a single resource whose
+ * `ActivityName` is the earlier step's.
+ */
+export declare function connectionResources(flow: unknown): BindingsV2Resource[];
+/**
+ * Fold freshly derived connection rows into whatever the project already has.
+ *
+ * Connection rows are replaced wholesale — they are re-derived from the flow that
+ * was just compiled, so the compile is the newer truth. Every other row is
+ * carried through in its original order, because this module does not derive
+ * those kinds and dropping them would silently delete a `TimeTrigger` (or
+ * anything a future generator adds) that `node configure` or an earlier `pack`
+ * had put there.
+ */
+export declare function mergeBindingsV2(existing: unknown, connections: BindingsV2Resource[]): BindingsV2Document;
+/** Read a `bindings_v2.json`, or `undefined` when absent or unparseable. */
+export declare function readBindingsV2(path: string): BindingsV2Document | undefined;

package/dist/bindings-v2.js

@@ -0,0 +1,155 @@
+/**
+ * bindings-v2 — the project's solution-resource sidecar, `bindings_v2.json`.
+ *
+ * Two files with confusingly similar names, and both are wanted:
+ *
+ *   - `bindings.json` — the AUTHORED, symbolic mapping at the workspace root
+ *     (`slack`, `shared` → tenant keys). Input to compile; `uip maestro registry
+ *     prepare` writes it. Not this module.
+ *   - `bindings_v2.json` — the GENERATED resource declaration inside the Flow
+ *     project. `uip solution resources refresh` documents it as its own input:
+ *     "sync resource declarations from their `bindings_v2.json` files". This
+ *     module.
+ *
+ * Without the sidecar, `resources refresh` syncs nothing, so
+ * `resources/solution_folder/connection/<connector>/<name>.json` is never
+ * created and the canvas fails `solution-resource-validation` — every
+ * `ConnectionId` binding's `resourceKey` is compared against the solution's
+ * declared connection keys and reported as `Resource "…" is not found in the
+ * solution`. The UiPath VS Code extension surfaces that as an invalid
+ * connection. It is not cosmetic: the same declaration is what a solution deploy
+ * provisions the connection from (flow-builder-sdk#689).
+ *
+ * ## Why compile can write this without racing `pack`
+ *
+ * `uip maestro flow pack` REGENERATES `bindings_v2.json` from the flow and
+ * ignores whatever the project directory holds — verified by packing a project
+ * whose sidecar had been replaced with a sentinel, and getting the derived
+ * resources back. So the packaged artifact is authoritative and unaffected by
+ * this file; the project copy exists purely for `resources refresh` and the
+ * extension. A sidecar that lags pack's generator can therefore never ship
+ * inside a package.
+ *
+ * ## What this derives, and what it deliberately leaves alone
+ *
+ * Only `connection` resources, which is what refresh imports and what #689 is
+ * about. Pack derives more from the BPMN projection — a `core.trigger.scheduled`
+ * flow also yields a `TimeTrigger` resource whose `CronExpression` comes from
+ * translating the trigger's ISO-8601 `timerPreset`. Re-deriving those here would
+ * be a second implementation of someone else's generator, free to drift, for no
+ * gain in the package. So non-connection resources already in the file are
+ * PRESERVED untouched and never invented: {@link mergeBindingsV2} replaces only
+ * the connection rows.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+/** The document version pack emits. */
+const DOCUMENT_VERSION = '2.0';
+/** The per-resource metadata version pack stamps. */
+const BINDINGS_VERSION = '2.2';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** `resource` values are spelled lower-case in a `.flow` and capitalised in the BPMN projection. */
+function isConnection(resource) {
+    return typeof resource === 'string' && resource.toLowerCase() === 'connection';
+}
+/**
+ * The `connection` resources a compiled flow declares — one per distinct
+ * connection, in node order, attributed to the FIRST node that uses it.
+ *
+ * Both halves of that are pack's behaviour, not a choice made here: a flow with
+ * two Outlook steps on one connection yields a single resource whose
+ * `ActivityName` is the earlier step's.
+ */
+export function connectionResources(flow) {
+    if (!isRecord(flow))
+        return [];
+    const bindings = Array.isArray(flow.bindings) ? flow.bindings.filter(isRecord) : [];
+    // Only the ConnectionId binding describes the connection itself. A connector
+    // step also emits a sibling `FolderKey` binding against the same resourceKey,
+    // and pack does not carry it into the sidecar.
+    const byKey = new Map();
+    for (const binding of bindings) {
+        const key = str(binding.resourceKey);
+        if (!key || !isConnection(binding.resource))
+            continue;
+        if (str(binding.propertyAttribute)?.toLowerCase() !== 'connectionid')
+            continue;
+        if (!byKey.has(key))
+            byKey.set(key, binding);
+    }
+    if (byKey.size === 0)
+        return [];
+    const nodes = Array.isArray(flow.nodes) ? flow.nodes.filter(isRecord) : [];
+    const resources = [];
+    const seen = new Set();
+    for (const node of nodes) {
+        const detail = isRecord(node.inputs) && isRecord(node.inputs.detail) ? node.inputs.detail : undefined;
+        if (!detail)
+            continue;
+        const key = str(detail.connectionId) ?? str(detail.connectionResourceId);
+        if (!key || seen.has(key))
+            continue;
+        const binding = byKey.get(key);
+        if (!binding)
+            continue;
+        seen.add(key);
+        const displayLabel = str(binding.name) ?? key;
+        const label = isRecord(node.display) ? str(node.display.label) : undefined;
+        resources.push({
+            resource: 'connection',
+            key,
+            // Pack concatenates resource and key with no separator for a connection.
+            id: `connection${key}`,
+            value: {
+                ConnectionId: {
+                    defaultValue: str(binding.default) ?? key,
+                    isExpression: false,
+                    displayName: displayLabel,
+                },
+            },
+            metadata: {
+                ActivityName: label ?? str(node.id) ?? key,
+                BindingsVersion: BINDINGS_VERSION,
+                DisplayLabel: displayLabel,
+                UseConnectionService: 'true',
+                Connector: str(detail.connector) ?? '',
+            },
+        });
+    }
+    return resources;
+}
+/**
+ * Fold freshly derived connection rows into whatever the project already has.
+ *
+ * Connection rows are replaced wholesale — they are re-derived from the flow that
+ * was just compiled, so the compile is the newer truth. Every other row is
+ * carried through in its original order, because this module does not derive
+ * those kinds and dropping them would silently delete a `TimeTrigger` (or
+ * anything a future generator adds) that `node configure` or an earlier `pack`
+ * had put there.
+ */
+export function mergeBindingsV2(existing, connections) {
+    const previous = isRecord(existing) && Array.isArray(existing.resources)
+        ? existing.resources.filter(isRecord)
+        : [];
+    const preserved = previous.filter((r) => !isConnection(r.resource));
+    const version = (isRecord(existing) && str(existing.version)) || DOCUMENT_VERSION;
+    return { version, resources: [...connections, ...preserved] };
+}
+/** Read a `bindings_v2.json`, or `undefined` when absent or unparseable. */
+export function readBindingsV2(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        // A hand-broken sidecar should not fail the compile; it is regenerated below.
+        return undefined;
+    }
+}

package/dist/bindings.d.ts

@@ -0,0 +1,6 @@
+/**
+ * bindings — compatibility re-export. The symbolic binding resolver now lives
+ * in `core/` (shared across flow/case/bpmn); this shim preserves the historical
+ * `./bindings.js` import path.
+ */
+export * from './core/bindings.js';

package/dist/bindings.js

@@ -0,0 +1,6 @@
+/**
+ * bindings — compatibility re-export. The symbolic binding resolver now lives
+ * in `core/` (shared across flow/case/bpmn); this shim preserves the historical
+ * `./bindings.js` import path.
+ */
+export * from './core/bindings.js';

package/dist/bpmn/bpmn-expr-check.d.ts

@@ -0,0 +1,41 @@
+/**
+ * bpmn-expr-check — the BPMN adapter over the shared `core/expr-check`, run by
+ * `BpmnBuilder.build()` before it hands back the model to be serialized.
+ *
+ * A BPMN `=`-expression reads a declared variable as `=vars.<name>` (a gateway
+ * flow `condition`, a script `input`, a multi-instance `collection`/`completion`,
+ * a variable assignment). `vars.` is a CLOSED namespace, so a reference to a name
+ * nothing declares is a definite mistake — and this is the ONLY thing that
+ * catches it early: a `=vars.<typo>` reaches run time and reads `undefined`,
+ * silently taking the wrong path. So this flags every undeclared `vars.<root>`,
+ * exactly as the flow check flags `$vars`.
+ *
+ * "Declared" means what it means to the platform, which is wider than
+ * `.var()`/`.input()`/`.output()`: a node's output `var` is itself a declaration
+ * (the canvas model keys a variable off each output), so a connector's
+ * `<id>_response`, a script task's output and a variable task's assignment target
+ * are all readable downstream. `nodeDeclaredVars` supplies them; being stricter
+ * than the platform here would reject working processes.
+ *
+ * A loop's item binds `iterator.<itemVar>`, and a script output writes `=result.…`
+ * — different namespaces, left alone (only `vars.` is the author's to get wrong).
+ * Variables are SCOPED: a sub-process sees the enclosing variables plus its own.
+ */
+import { type ExprDiagnostic } from '../core/expr-check.js';
+import { type BuiltBpmn } from './bpmn-sdk.js';
+/** A diagnostic plus the element it was found in. */
+export interface BpmnLocatedDiagnostic extends ExprDiagnostic {
+    where: string;
+}
+/** Every first-level expression problem in a built BPMN process, stamped with its location. */
+export declare function checkBpmnExpressions(built: BuiltBpmn): BpmnLocatedDiagnostic[];
+/**
+ * Thrown by `BpmnBuilder.build()` when the first-level expression check finds an
+ * undeclared `vars.<name>` reference. Same shape/rationale as the flow's
+ * `FlowBuildError`: `message` lists every problem; `diagnostics` carries them
+ * structured.
+ */
+export declare class BpmnBuildError extends Error {
+    readonly diagnostics: BpmnLocatedDiagnostic[];
+    constructor(built: BuiltBpmn, diagnostics: BpmnLocatedDiagnostic[]);
+}