@uipath/maestro-builder-sdk 6.37.0 → 6.38.0

package/dist/bpmn/bpmn-sdk.d.ts

@@ -163,6 +163,10 @@ export type BpmnNode = {
     inputs: Record<string, unknown>;
     /** Variable the response lands in; defaults to `<id>_response`. */
     outputVar?: string;
+    /** Variable the error payload lands in; defaults to `<id>_Error`. */
+    errorVar?: string;
+    /** Extra mapped output rows, by the variable each writes — see `BpmnConnectorOpts.outputs`. */
+    outputs?: Record<string, string | ConnectorOutputRow>;
     /** `=`-expression that, when true, skips this activity (`uipath:activity/@skipCondition`). */
     skipCondition?: string;
 }) | (ActivityNodeFields & {
@@ -3140,6 +3144,20 @@ declare abstract class ScopeBuilder {
     vars(entries: VarEntry[]): this;
     private declareVar;
 }
+/**
+ * One extra output row on a connector task, spelled out — the object form of an entry in
+ * {@link BpmnConnectorOpts}' `outputs`.
+ */
+export interface ConnectorOutputRow {
+    /** The `=`-expression against the result, e.g. `'=response.Id'`. */
+    source: string;
+    /** The row's `name`; defaults to the variable. The designer names a row after the field it reads. */
+    name?: string;
+    /** The row's `type`; defaults to the variable's declared type, else `string`. */
+    type?: string;
+    /** The designer's `custom="true"` mark on a row the author added in the variables panel. */
+    custom?: boolean;
+}
 /**
  * `.connector()` options: the shared connector options, plus the BPMN-only
  * display `name` and output-variable override.
@@ -3164,6 +3182,21 @@ export type BpmnConnectorOpts = ConnectorOpts & ActivityOpts & {
      * always lands in `<id>_Error`.
      */
     outputVar?: string;
+    /**
+     * Variable the error payload lands in. Defaults to `<id>_Error`, the name every
+     * `.connector()` has always written; an import names whatever the file bound
+     * (`error12`), so decompile can lift a connector task without renaming its variable.
+     */
+    errorVar?: string;
+    /**
+     * Extra output rows beside the response and the Error, by the variable each
+     * writes: `{ invoiceId: '=response.Id' }` writes `<uipath:output name="invoiceId"
+     * source="=response.Id" var="invoiceId"/>`; the object form names and types the row
+     * (`{ id5: { source: '=response.Id', name: 'Id', type: 'string' } }`), which is how a
+     * designer-added row reads back from an import. Each variable is declared for you
+     * unless you declared it.
+     */
+    outputs?: Record<string, string | ConnectorOutputRow>;
 };
 /** A sub-process body: the same graph methods, plus an internal node builder. */
 export declare class SubProcessBuilder extends ScopeBuilder {

package/dist/bpmn/bpmn-sdk.js

@@ -943,9 +943,13 @@ class ScopeBuilder {
             object: spec.object,
             inputs: spec.inputs,
             outputVar: bpmnOpts.outputVar,
+            errorVar: bpmnOpts.errorVar,
+            outputs: bpmnOpts.outputs,
             skipCondition: bpmnOpts.skipCondition,
+            tags: bpmnOpts.tags,
             retry: bpmnOpts.retry,
             loop: bpmnOpts.loop,
+            errorMapping: bpmnOpts.errorMapping,
         }, body);
     }
     /**

package/dist/bpmn/check.js

@@ -99,6 +99,21 @@ function checkConnectors(built, opts, diags) {
         checkConnectorLookups(where, n, opts, EQUALS_EXPR_DIALECT, report);
         checkConnectorSchema(where, n, opts, EQUALS_EXPR_DIALECT, report);
         checkConnectorContract(where, n, opts, report);
+        // Two rows writing one variable: an `outputs` key that is also the response or
+        // error variable. Both rows would be emitted and the later write wins at run time.
+        const response = n.outputVar ?? `${n.id}_response`;
+        const error = n.errorVar ?? `${n.id}_Error`;
+        for (const varId of Object.keys(n.outputs ?? {})) {
+            if (varId !== response && varId !== error)
+                continue;
+            report({
+                level: 'error',
+                code: 'CONNECTOR_OUTPUT_VAR_CLASH',
+                message: `${where}: outputs maps "${varId}", which is already the task's ${varId === response ? 'response' : 'error'} variable ` +
+                    `(\`${varId === response ? 'outputVar' : 'errorVar'}\`); two rows would write it. Map the extra row to another variable, ` +
+                    `or drop it and read \`vars.${varId}\` directly.`,
+            });
+        }
     }
 }
 /**

package/dist/bpmn/connector-lift-verify.d.ts

@@ -0,0 +1,32 @@
+import type { Library } from '../core/library.js';
+import type { ConnectorLiftSummary } from './decompile.js';
+type Moddle = any;
+/** The outcome of verifying one decompile's lifted connector tasks. */
+export interface ConnectorLiftVerdict {
+    /** Lifted elements whose recompiled task differs beyond the regenerated fields, with what differed. */
+    failed: Map<string, string>;
+}
+/**
+ * The part of a connector task that a lift must reproduce, as one comparable
+ * string. Row order does not matter (rows are sorted by name); a scalar row's
+ * `type` attribute and the response row's schema body do not either.
+ */
+export declare function canonicalConnectorTask(el: Moddle): string;
+/**
+ * Whether each lifted connector task recompiles to the task the file carried, the
+ * regenerated fields aside.
+ *
+ * Each call is compiled ON ITS OWN — the decompiled preamble (bindings, variables,
+ * schemas), a start event, the one `.connector()` line, an end event — rather than
+ * the whole process, so a lift the library refuses (a body field it does not carry)
+ * is the only one refused, and a process with no other way to compile (a start event
+ * missing its connection, say) still gets its connector tasks verified.
+ *
+ * @param originalXml - The `.bpmn` that was decompiled.
+ * @param summary - What the lift did: the ids, the calls, and the preamble to compile them under.
+ * @param sdkEntry - Absolute path of the `bpmn-sdk.js` to build against.
+ * @param library - The connector library the lift named operations through.
+ * @returns The lifted elements that did not come back the same, each with the reason.
+ */
+export declare function verifyConnectorLifts(originalXml: string, summary: Pick<ConnectorLiftSummary, 'lifted' | 'calls' | 'preamble'>, sdkEntry: string, library: Library): Promise<ConnectorLiftVerdict>;
+export {};

package/dist/bpmn/connector-lift-verify.js

@@ -0,0 +1,220 @@
+/**
+ * connector-lift-verify — the check that makes decompile's connector lift safe to write.
+ *
+ * A connector task written back as `.connector(key, action, inputs, …)` is NOT
+ * byte-identical on recompile, by design: the SDK regenerates what the canvas wrote
+ * and the file carried — the `metadata` blob (`designTimeMetadata`, `metadataState`,
+ * `telemetryData`), the `operation` verb, the `type` of each scalar row, the response
+ * row's schema body, `activityConfigurationVersion`. Everything else about the task
+ * must come back exactly: the element and its name, every other context row, every
+ * payload row's name, target and value, every output row's name, source and variable.
+ * This builds the lifted source, compiles it with the same library, and compares each
+ * lifted element against the original under exactly that list — so a lift that lost
+ * an input, picked the wrong action or renamed a variable is refused, element by
+ * element, and `decompile-cli` writes those verbatim with the reason.
+ *
+ * Same stance as `lift-verify.ts` for `--style nested`: the lift's rules are an
+ * argument, this is the measurement.
+ */
+import BpmnModdle from 'bpmn-moddle';
+import { createRequire } from 'node:module';
+import { buildSource } from './lift-verify.js';
+import { serialize } from './serialize.js';
+const require = createRequire(import.meta.url);
+const uipathDescriptor = require('./uipath-moddle.v1.json');
+/**
+ * Context rows the SDK regenerates from the library on compile; not compared.
+ * `activity` is the op identity the SDK writes beside `objectName` (the platform
+ * validator requires it, exports omit it) and `operation` the library's verb where
+ * the canvas writes the curated name; `metadata` is the canvas blob; the
+ * configuration version is #1287's stamp.
+ */
+const REGENERATED_CONTEXT = new Set(['metadata', 'operation', 'activity', 'activityConfigurationVersion']);
+function stableJson(value) {
+    return JSON.stringify(value, (_key, v) => v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]))
+        : v);
+}
+/** A row body as a comparable string: parsed JSON when it is JSON, the text otherwise. */
+function bodyText(body) {
+    if (body === undefined || body === null)
+        return undefined;
+    const text = String(body);
+    try {
+        return stableJson(JSON.parse(text));
+    }
+    catch {
+        return text;
+    }
+}
+function payloadOf(el) {
+    return (el.extensionElements?.values ?? []).find((x) => x.$type === 'uipath:Activity');
+}
+/**
+ * The part of a connector task that a lift must reproduce, as one comparable
+ * string. Row order does not matter (rows are sorted by name); a scalar row's
+ * `type` attribute and the response row's schema body do not either.
+ */
+export function canonicalConnectorTask(el) {
+    const payload = payloadOf(el);
+    const context = Object.fromEntries((payload?.context?.input ?? [])
+        .filter((r) => !REGENERATED_CONTEXT.has(r.name))
+        .map((r) => [r.name, r.body !== undefined ? bodyText(r.body) : (r.value ?? '')]));
+    const inputs = (payload?.input ?? [])
+        .map((r) => ({ name: r.name, target: r.target ?? null, value: r.body !== undefined ? bodyText(r.body) : String(r.value ?? '') }))
+        // `.connector()` always writes the request body row, `{}` when nothing fills it;
+        // an export writes none for an operation with no body. The same request either way.
+        .filter((r) => !(r.name === 'body' && r.target === 'body' && r.value === '{}'))
+        .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    const outputs = (payload?.output ?? [])
+        .map((r) => ({ name: r.name, source: r.source ?? null, var: r.var ?? null, custom: r.custom ?? null, target: r.target ?? null }))
+        .sort((a, b) => String(a.name).localeCompare(String(b.name)) || String(a.var).localeCompare(String(b.var)));
+    // The activity's other extensions — tags, retry, error mapping — and its loop
+    // characteristics: options `.connector()` takes, so a lift that lost one is refused.
+    const extensions = (el.extensionElements?.values ?? [])
+        .filter((x) => x.$type !== 'uipath:Activity' && x.$type !== 'uipath:EntryPointId')
+        .map(plain)
+        .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    return stableJson({
+        element: el.$type,
+        name: el.name ?? null,
+        type: payload?.type?.value ?? null,
+        skipCondition: payload?.skipCondition ?? null,
+        context,
+        inputs,
+        outputs,
+        extensions,
+        loop: el.loopCharacteristics ? plain(el.loopCharacteristics) : null,
+    });
+}
+/** A moddle element as plain data: its own properties, recursively, without the `$`-prefixed bookkeeping. */
+function plain(value) {
+    if (Array.isArray(value))
+        return value.map(plain);
+    if (value && typeof value === 'object') {
+        const out = { $type: value.$type };
+        for (const [k, v] of Object.entries(value)) {
+            if (k.startsWith('$'))
+                continue;
+            out[k] = plain(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Every variable id the document declares or a node's output row writes. An isolated
+ * call still reads the process's variables in its expressions (`vars.response11[0].Id`),
+ * and the build's expression check refuses a read of an undeclared one — so the ones
+ * the preamble does not already declare are stubbed into the verification source.
+ */
+function declaredVariableIds(root) {
+    const ids = new Set();
+    const fromExt = (owner) => {
+        for (const ext of owner.extensionElements?.values ?? []) {
+            if (ext.$type !== 'uipath:Variables')
+                continue;
+            for (const list of [ext.input, ext.inputOutput, ext.output])
+                for (const v of list ?? [])
+                    if (v.id)
+                        ids.add(v.id);
+        }
+    };
+    const walk = (container) => {
+        fromExt(container);
+        for (const el of container.flowElements ?? []) {
+            fromExt(el);
+            for (const ext of el.extensionElements?.values ?? [])
+                for (const row of ext.output ?? [])
+                    if (row.var)
+                        ids.add(row.var);
+            if (el.$type === 'bpmn:SubProcess')
+                walk(el);
+        }
+    };
+    for (const r of root.rootElements ?? []) {
+        if (r.$type === 'bpmn:Process')
+            walk(r);
+        else
+            fromExt(r);
+    }
+    return [...ids];
+}
+function elementsById(root) {
+    const out = new Map();
+    const walk = (container) => {
+        for (const el of container.flowElements ?? []) {
+            out.set(el.id, el);
+            if (el.$type === 'bpmn:SubProcess')
+                walk(el);
+        }
+    };
+    for (const r of root.rootElements ?? [])
+        if (r.$type === 'bpmn:Process')
+            walk(r);
+    return out;
+}
+/**
+ * Whether each lifted connector task recompiles to the task the file carried, the
+ * regenerated fields aside.
+ *
+ * Each call is compiled ON ITS OWN — the decompiled preamble (bindings, variables,
+ * schemas), a start event, the one `.connector()` line, an end event — rather than
+ * the whole process, so a lift the library refuses (a body field it does not carry)
+ * is the only one refused, and a process with no other way to compile (a start event
+ * missing its connection, say) still gets its connector tasks verified.
+ *
+ * @param originalXml - The `.bpmn` that was decompiled.
+ * @param summary - What the lift did: the ids, the calls, and the preamble to compile them under.
+ * @param sdkEntry - Absolute path of the `bpmn-sdk.js` to build against.
+ * @param library - The connector library the lift named operations through.
+ * @returns The lifted elements that did not come back the same, each with the reason.
+ */
+export async function verifyConnectorLifts(originalXml, summary, sdkEntry, library) {
+    const failed = new Map();
+    if (summary.lifted.length === 0)
+        return { failed };
+    const moddle = new BpmnModdle({ uipath: uipathDescriptor });
+    const original = (await moddle.fromXML(originalXml, { lax: true })).rootElement;
+    const before = elementsById(original);
+    // Declared by the preamble means a `.var()` call or a `.vars([{ id, … }])` entry — not
+    // a mention in `.preserve({ variableOrder })`, which lists derived declarations the
+    // preamble does not write.
+    const declares = (v) => {
+        const q = JSON.stringify(v).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`\\.var\\(${q}|\\{ id: ${q}, (?:name|type|direction)`).test(summary.preamble);
+    };
+    const stubs = declaredVariableIds(original)
+        .filter((v) => !declares(v))
+        .map((v) => `  .var(${JSON.stringify(v)}, "object")`)
+        .join('\n');
+    for (const id of summary.lifted) {
+        const call = summary.calls.get(id);
+        const a = before.get(id);
+        if (!call || !a) {
+            failed.set(id, call ? 'not in the original' : 'the lift recorded no call for it');
+            continue;
+        }
+        const source = `${summary.preamble}\n${stubs ? `${stubs}\n` : ''}  .startEvent("verify_start")\n  ${call}\n  .endEvent("verify_end")\n` +
+            `  .sequenceFlow("verify_start", ${JSON.stringify(id)})\n  .sequenceFlow(${JSON.stringify(id)}, "verify_end")\n  .build();\n`;
+        let recompiled;
+        try {
+            recompiled = await serialize(await buildSource(source, sdkEntry), { library });
+        }
+        catch (e) {
+            // The first three lines: the refusal and, for a build error, the diagnostic under it.
+            failed.set(id, `the lifted call did not compile: ${e.message.split('\n').slice(0, 3).join(' ').trim()}`);
+            continue;
+        }
+        const b = elementsById((await moddle.fromXML(recompiled, { lax: true })).rootElement).get(id);
+        if (!b) {
+            failed.set(id, 'not in the recompiled process');
+            continue;
+        }
+        const ca = canonicalConnectorTask(a);
+        const cb = canonicalConnectorTask(b);
+        if (ca !== cb)
+            failed.set(id, `recompiled task differs:\n    was ${ca}\n    now ${cb}`);
+    }
+    return { failed };
+}

package/dist/bpmn/connector.d.ts

@@ -33,6 +33,18 @@ export interface ConnectorCtx {
     library?: Library;
     bindings?: Bindings;
     bindingSink: Map<string, Record<string, unknown>>;
+    /**
+     * The bindings the author declared in source (`.binding()`), by id. A connector
+     * naming one of them takes its `resourceKey` and `default` from the declaration,
+     * the way it takes them from a bindings.json entry: without this, a `.binding('c',
+     * { value: '<guid>' })` paired with `connection: 'c'` wrote `resourceKey="c"` into
+     * the task's context — the id where every real export writes the connection's key.
+     */
+    declaredBindings?: ReadonlyMap<string, {
+        name?: string;
+        default?: string;
+        resourceKey?: string;
+    }>;
     /**
      * Declared Maestro `type` for a variable id, for typing an author-mapped output
      * row. Optional so the connector emitter (which writes its own rows) is

package/dist/bpmn/connector.js

@@ -116,6 +116,21 @@ export function createConnectorTask(ctx, n) {
                     },
                 }),
             }),
+            // Extra mapped rows — `outputs: { <var>: '=response.<field>' }`, or the object
+            // form naming and typing the row — after the two the library implies, where
+            // every export puts the rows an author added in the designer.
+            ...Object.entries(n.outputs ?? {}).map(([varId, spec]) => {
+                const row = typeof spec === 'string' ? { source: spec } : spec;
+                const props = {
+                    name: row.name ?? varId,
+                    type: row.type ?? ctx.varTypeOf?.(varId) ?? 'string',
+                    source: row.source,
+                    var: varId,
+                };
+                if (row.custom)
+                    props.custom = true;
+                return m.create('uipath:Output', props);
+            }),
         ],
     });
     return m.create('bpmn:SendTask', {
@@ -180,7 +195,7 @@ export function connectorBindingRef(ctx, name, resource, propertyAttribute, disp
 function bindingRef(ctx, name, resource, propertyAttribute, displayName, companionKey) {
     if (!name)
         return undefined;
-    const entry = ctx.bindings?.entry(name);
+    const entry = (ctx.bindings?.entry(name) ?? ctx.declaredBindings?.get(name));
     const id = entry?.id ?? name;
     // `default` is the deploy-time VALUE the runtime resolves, not the author's symbolic
     // name for the binding. An entry that states only a `resourceKey` — which is what a

package/dist/bpmn/declared-vars.js

@@ -15,7 +15,7 @@ import { typedNodeAdditionalOutputVars, typedNodeOutputVar } from './typed-node.
  * @internal
  */
 export function connectorOutputVars(n) {
-    return { response: n.outputVar ?? `${n.id}_response`, error: `${n.id}_Error` };
+    return { response: n.outputVar ?? `${n.id}_response`, error: n.errorVar ?? `${n.id}_Error` };
 }
 /**
  * The variables a typed node writes — the ONE definition of that set.
@@ -54,7 +54,7 @@ export function typedNodeDeclaredVars(n) {
 export function nodeDeclaredVars(n) {
     if (n.kind === 'connector') {
         const { response, error } = connectorOutputVars(n);
-        return [response, error];
+        return [response, error, ...Object.keys(n.outputs ?? {})];
     }
     if (n.kind === 'typed')
         return typedNodeDeclaredVars(n);

package/dist/bpmn/decompile-cli.js

@@ -4,6 +4,15 @@
  *
  * Usage:
  *   node --experimental-strip-types decompile-cli.js <Name.bpmn> [-o Name.bpmn.ts] [--import <specifier>] [--style explicit|nested] [--keep-flow-ids] [--keep-unused-bindings]
+ *       [--library <library-json dir>] [--connectors-local <overlay dir>] [--connectors lift|verbatim]
+ *
+ * `--connectors lift` (the default when a library opens — `--library`, else the
+ * cache `registry pull` filled) writes a connector task the library can name as
+ * `.connector(key, action, inputs, { connection, folder, … })`, and verifies each
+ * lift by recompiling: a task that does not come back the same, the fields the
+ * SDK regenerates aside, is written verbatim with the reason. `--connectors
+ * verbatim` keeps every task as the file spells it, which is also what happens
+ * with no library at all.
  *
  * The reverse of compile-cli: reads a `.bpmn` and emits builder source whose
  * default export re-serializes to the same XML. `--import` sets the module
@@ -29,6 +38,8 @@ import { defaultSourceOut, writeSource } from '../workdir.js';
 import { flagValue, runWhenInvokedDirectly } from '../cli-run.js';
 import { decompile } from './decompile.js';
 import { sameGraph } from './lift-verify.js';
+import { verifyConnectorLifts } from './connector-lift-verify.js';
+import { openCliLibrary } from '../core/cli-library.js';
 import { BPMN_IMPORT } from '../package-name.js';
 import { fileURLToPath } from 'node:url';
 /**
@@ -62,9 +73,14 @@ export async function run(argv) {
             return 2;
         }
     }
+    const connectors = flagValue(argv, '--connectors') ?? 'lift';
+    if (connectors !== 'lift' && connectors !== 'verbatim') {
+        console.error(`decompile: --connectors must be lift or verbatim, not "${connectors}"`);
+        return 2;
+    }
     const keepFlowIds = argv.includes('--keep-flow-ids');
     const keepUnusedBindings = argv.includes('--keep-unused-bindings');
-    const flags = new Set(['-o', '--import', '--style']);
+    const flags = new Set(['-o', '--import', '--style', '--library', '--connectors-local', '--connectors']);
     const bare = new Set(['--keep-flow-ids', '--keep-unused-bindings']);
     const input = argv.find((a, i) => !bare.has(a) && !flags.has(a) && !flags.has(argv[i - 1]));
     if (!input) {
@@ -74,8 +90,34 @@ export async function run(argv) {
     const xml = readFileSync(input, 'utf8');
     const importSpecifier = flagValue(argv, '--import') ?? BPMN_IMPORT;
     let pruned = [];
-    const base0 = { importSpecifier, keepUnusedBindings, onPrune: (ids) => (pruned = ids) };
-    let source = await decompile(xml, base0);
+    // The connector lift: name each connector task through the library, then keep only
+    // the lifts that verify. One decompile to plan, one verify, and — only when a lift
+    // was refused — one more decompile with those tasks pinned verbatim. The pinned set
+    // then rides into the nested-style passes below, so the flat and nested sources the
+    // nested verify compares make the same connector decisions.
+    const library = connectors === 'lift' ? openCliLibrary(argv) : undefined;
+    const sdkEntry = fileURLToPath(new URL('./bpmn-sdk.js', import.meta.url));
+    let connectorSummary;
+    let verbatimConnectors = new Set();
+    const base0 = {
+        importSpecifier,
+        keepUnusedBindings,
+        onPrune: (ids) => (pruned = ids),
+        ...(library ? { library, connectors: 'lift' } : {}),
+        onConnectorLift: (s) => (connectorSummary = s),
+    };
+    let source = await decompile(xml, { ...base0, verbatimConnectors });
+    if (library && connectorSummary && connectorSummary.lifted.length > 0) {
+        const verdict = await verifyConnectorLifts(xml, connectorSummary, sdkEntry, library);
+        if (verdict.failed.size > 0) {
+            verbatimConnectors = new Set(verdict.failed.keys());
+            source = await decompile(xml, { ...base0, verbatimConnectors });
+            // The summary from the second pass says "did not verify"; carry the measured reason.
+            if (connectorSummary) {
+                connectorSummary.verbatim = connectorSummary.verbatim.map((v) => ({ id: v.id, reason: verdict.failed.get(v.id) ?? v.reason }));
+            }
+        }
+    }
     let lifted;
     let fallback;
     if (style === 'nested') {
@@ -83,10 +125,11 @@ export async function run(argv) {
         // package's own entry, whatever specifier the written file carries — the check is
         // about the graph, not about module resolution. The flow ids the lift renamed are
         // the one sanctioned difference.
-        const sdkEntry = fileURLToPath(new URL('./bpmn-sdk.js', import.meta.url));
         for (const sequenceMode of [true, false]) {
             let summary;
-            const nested = await decompile(xml, { ...base0, style: 'nested', relabelFlows: !keepFlowIds, sequenceMode, onLift: (s) => (summary = s) });
+            const nested = await decompile(xml, {
+                ...base0, verbatimConnectors, style: 'nested', relabelFlows: !keepFlowIds, sequenceMode, onLift: (s) => (summary = s),
+            });
             const renamed = new Map((summary?.renamedFlows ?? []).map((r) => [r.from, r.to]));
             const verdict = await sameGraph(source, nested, sdkEntry, renamed);
             if (verdict.same) {
@@ -107,6 +150,15 @@ export async function run(argv) {
         console.log(`decompile: dropped ${pruned.length} binding(s) nothing references — ${pruned.slice(0, 8).join(', ')}` +
             `${pruned.length > 8 ? `, and ${pruned.length - 8} more` : ''}. Pass --keep-unused-bindings to echo them.`);
     }
+    if (connectorSummary && (connectorSummary.lifted.length || connectorSummary.verbatim.length)) {
+        const kept = connectorSummary.verbatim.length
+            ? `; verbatim: ${connectorSummary.verbatim.map((v) => `${v.id} (${v.reason.split('\n')[0]})`).join('; ')}`
+            : '';
+        console.log(`decompile: connectors — lifted ${connectorSummary.lifted.length} to .connector()${kept}`);
+    }
+    else if (connectors === 'lift' && !library) {
+        console.log('decompile: no connector library found, connector tasks written verbatim — pass --library <library-json dir> to lift them');
+    }
     if (lifted) {
         const flat = lifted.leftFlat.length ? `; left flat: ${lifted.leftFlat.map((r) => `${r.id} (${r.reason})`).join('; ')}` : '';
         const renamed = lifted.renamedFlows.length
@@ -118,7 +170,17 @@ export async function run(argv) {
     else if (fallback) {
         console.log(`decompile: --style nested could not be verified, wrote the flat form — ${fallback}`);
     }
-    reportResult({ path: resolve(out), style: lifted ? 'nested' : 'explicit', ...(lifted ? { lifted } : {}), ...(fallback ? { fallback } : {}) });
+    reportResult({
+        path: resolve(out),
+        style: lifted ? 'nested' : 'explicit',
+        ...(lifted ? { lifted } : {}),
+        ...(fallback ? { fallback } : {}),
+        // What the lift did, when a library was in play: the ids, not the preamble and
+        // calls the verifier consumed.
+        ...(library && connectorSummary && (connectorSummary.lifted.length || connectorSummary.verbatim.length)
+            ? { connectors: { lifted: connectorSummary.lifted, verbatim: connectorSummary.verbatim } }
+            : {}),
+    });
     return 0;
 }
 runWhenInvokedDirectly(import.meta.url, 'decompile', run);

package/dist/bpmn/decompile.d.ts

@@ -1,7 +1,31 @@
+import type { Library } from '../core/library.js';
 /** Options for {@link decompile}. */
 export interface BpmnDecompileOptions {
     /** Module specifier for the emitted `import { bpmn }` line. */
     importSpecifier?: string;
+    /**
+     * The connector library. With one, an `Intsvc.ActivityExecution` the library can
+     * name comes back as `.connector(key, action, inputs, { connection, folder, … })` —
+     * the call an author writes — instead of the verbatim `.activity()` form; see
+     * {@link BpmnDecompileOptions.connectors}. Without one, every connector task stays
+     * verbatim, as before.
+     */
+    library?: Library;
+    /**
+     * How a connector task is written back when a library is given. `'lift'` (the
+     * default) names the operation through the library and drops what the SDK
+     * regenerates on compile — the `metadata` blob the canvas writes
+     * (`designTimeMetadata`, `metadataState`), the CRUD `operation` verb, row types,
+     * the response row's schema body. `'verbatim'` keeps every row as the file spells
+     * it. A lift is best effort by construction and safe only with the check
+     * `decompile-cli` runs (`verifyConnectorLifts`): the lifted call must compile to the
+     * same task, those regenerated fields aside, or the element is written verbatim.
+     */
+    connectors?: 'lift' | 'verbatim';
+    /** Connector tasks to write verbatim whatever `connectors` says — the ones a verify refused. */
+    verbatimConnectors?: ReadonlySet<string>;
+    /** Called with what the connector lift did, after decompiling. */
+    onConnectorLift?: (summary: ConnectorLiftSummary) => void;
     /**
      * `'explicit'` (the default) renders the graph flat: one call per element, one
      * `.sequenceFlow()` per edge. `'nested'` LIFTS the regions that the builder's
@@ -103,4 +127,23 @@ export interface LiftSummary {
     /** Whether the top level was written in `.flowMode('sequence')`. */
     sequence: boolean;
 }
+/** What the connector lift did on one decompile — see `BpmnDecompileOptions.connectors`. */
+export interface ConnectorLiftSummary {
+    /** Element ids written as `.connector()`. */
+    lifted: string[];
+    /** Connector tasks written verbatim, each with the reason. */
+    verbatim: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /**
+     * The source up to the first element — the import, the process call, its metadata,
+     * schemas, bindings and variables — so a verifier can compile one lifted call on its
+     * own (`verifyConnectorLifts`) instead of the whole process, where one refused lift
+     * would take every other down with it.
+     */
+    preamble: string;
+    /** Each lifted call's source line, by element id. */
+    calls: Map<string, string>;
+}
 export declare function decompile(xml: string, options?: BpmnDecompileOptions): Promise<string>;