@uipath/maestro-builder-sdk 6.13.0 → 6.14.1

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

@@ -378,6 +378,12 @@ export interface BpmnVarDecl {
     schema?: unknown;
     /** Mark the declaration `required="true"`, as a process input can be. */
     required?: boolean;
+    /** The product's "an author added this" flag — see {@link VarOpts.custom}. */
+    custom?: boolean;
+    /** The product's "the platform owns this" flag — see {@link VarOpts.internal}. */
+    internal?: boolean;
+    /** A refinement of `type` the designer carries — see {@link VarOpts.subType}. */
+    subType?: string;
 }
 /**
  * A declared external identifier the process needs supplied at deploy time — a
@@ -393,9 +399,9 @@ export interface BindingDecl {
     resource: string;
     /** Which property of that resource is wanted, e.g. `'ConnectionId'`, `'Key'`. */
     propertyAttribute: string;
-    /** The value used when nothing overrides it — what an offline run resolves to. */
+    /** The value `=bindings.<id>` resolves to — see {@link BindingOpts.value}, the `value` option. */
     default?: string;
-    /** The resource's key, when it differs from `default`. */
+    /** Which resource this is bound to; never resolved — see {@link BindingOpts.resourceKey}. */
     resourceKey?: string;
     /**
      * Narrows the resource, e.g. `'Agent'` for an agent process. Required by some
@@ -403,6 +409,11 @@ export interface BindingDecl {
      */
     resourceSubType?: string;
 }
+/** One entry of {@link BpmnBuilder.bindings} — a `.binding()` call written as data. */
+export interface BindingEntry extends BindingOpts {
+    /** The binding's id — what `=bindings.<id>` refers to. */
+    id: string;
+}
 /** A definitions-level `bpmn:message` declaration, referenced by message events. */
 export interface MessageDecl {
     /** The declaration's id — what an event's `messageRef` points at. */
@@ -419,6 +430,50 @@ export interface ErrorDecl {
     /** The error code the runtime matches on. */
     code?: string;
 }
+/**
+ * Non-authoring state retained by decompile/recompile.
+ *
+ * The BPMN counterpart of the Case SDK's `CaseJsonPreservation`, and named to match it:
+ * one block, carried rather than authored, that a reader can skip.
+ *
+ * Everything here is data the source document carried that NOTHING derives and nothing
+ * executes. It is not a feature to reach for: `decompile` writes it, an author leaves
+ * it alone, and deleting it changes no behaviour — only whether the file still matches
+ * the one it came from.
+ *
+ * It deliberately cannot carry anything authorable. A position, a type, a condition, a
+ * schema — those are the typed builder's job, and hiding one here would make it
+ * invisible to `check` and to whoever reads the source.
+ *
+ * Distinct from LAYOUT, which this does not hold. A diagram is content: a person reads
+ * it, and the Flow SDK lets an author set it (`.layout()`). The members here have no
+ * meaning apart from "what the file said".
+ */
+export interface BpmnPreservation {
+    /**
+     * The order declarations are written in, by id.
+     *
+     * Needed because a declaration folded onto the output row that fills it has no line
+     * of its own to carry its position, and derived declarations would otherwise land
+     * after every declared one. No rule recovers the real order: it is the designer's
+     * creation order, and it follows the owning element's document order in none of the
+     * five exports in `research/bpmn-roundtrip/corpus/` (47, 36, 19, 16 and 22
+     * inversions).
+     *
+     * Nothing reads it at run time — the engine seeds declarations into one scope by id,
+     * and a process input is matched by display `name`, not position. `uip maestro bpmn
+     * validate` answers `Success` on a reordered block. What it buys is the variables
+     * panel listing things as the source did, and a `bpmn merge` whose diff covers what
+     * was edited rather than all hundred declarations.
+     *
+     * It applies WITHIN each direction group — `uipath:input`, then `uipath:inputOutput`,
+     * then `uipath:output` — which is how the product writes them. Ids it omits keep
+     * their relative order, after the ones it names, and an id it does not know is
+     * ignored. `check` reports all three ways of getting it wrong, because every one of
+     * them used to be silent.
+     */
+    variableOrder?: string[];
+}
 /**
  * The built in-memory process graph `.build()` returns — the IR `serialize()`
  * walks into `.bpmn` XML.
@@ -444,6 +499,8 @@ export interface BuiltBpmn {
     metadata?: ProcessMetadata;
     /** Named schemas from `.schema()`, which a row's `schema` may reference by id. */
     schemas: Map<string, unknown>;
+    /** Non-authoring state carried from the source — see {@link BpmnBuilder.preserve}. */
+    preservation?: BpmnPreservation;
 }
 /**
  * Process-level metadata — the `uipath:*` children of the process's own
@@ -887,13 +944,45 @@ export interface SubProcessOpts extends ActivityOpts {
      */
     payload?: ExtensionPayload;
 }
+/**
+ * One entry of {@link ScopeBuilder.vars} — a `.var()` / `.input()` / `.output()` call
+ * written as data.
+ */
+export interface VarEntry extends VarOpts {
+    /** The variable's id — what expressions read as `vars.<id>`. */
+    id: string;
+    /** A `types.*` descriptor. */
+    type: TypeDesc;
+    /** Which declaration this is. Defaults to `'inputOutput'`, the `.var()` kind. */
+    direction?: VarDirection;
+}
+/** One entry of {@link BpmnBuilder.schemas} — a `.schema()` call written as data. */
+export interface SchemaEntry {
+    /** The schema's id, referenced by a `schema: '<id>'` option. */
+    id: string;
+    /** The JSON Schema itself. */
+    body: unknown;
+}
 /** Options for `.binding()`. */
 export interface BindingOpts {
     /** Display name the designer shows. Defaults to the binding's id. */
     name?: string;
     /**
-     * The value the binding resolves to when nothing overrides it — which is what
-     * an offline run reads, so it is the one field a local run needs.
+     * **The value.** What `=bindings.<id>` evaluates to, and the only field of a binding
+     * the runtime reads.
+     *
+     * Resolution is `supplied[id] ?? supplied[name] ?? value` — a deploy, or
+     * `flow-debug --bindings`, overrides it; absent an override this is used; with
+     * neither the binding is UNRESOLVED and a dispatching run refuses to start, naming
+     * every one (`local-engine/src/v2/dispatch/bindings.ts`). So a binding with no
+     * `value` is a promise that something else will supply it.
+     *
+     * Real exports leave it out for exactly one thing: a `folderPath`, which is not
+     * knowable when the resource is picked. 524 of the 528 bindings in
+     * `research/bpmn-roundtrip/corpus/` follow "no `value` iff `propertyAttribute` is
+     * `folderPath`".
+     *
+     * Not to be confused with {@link BindingOpts.resourceKey}, which is never resolved.
      */
     value?: string;
     /**
@@ -905,7 +994,33 @@ export interface BindingOpts {
     resource?: string;
     /** Which property of that resource is wanted. Defaults to `'value'`. */
     propertyAttribute?: string;
-    /** The resource's key, when it differs from {@link BindingOpts.value}. */
+    /**
+     * **Which resource this is bound to** — design-time provenance, never resolved.
+     *
+     * Nothing at run time reads it: it identifies the tenant resource the binding was
+     * bound to, so a deploy can re-resolve {@link BindingOpts.value} against the target
+     * tenant and the canvas can show what the binding points at.
+     *
+     * It equals `value` exactly when the property asked for IS the resource's identity —
+     * a queue is identified by its name, so a `name` binding's key and value are the
+     * same string (196 of 202 in the corpus). It differs whenever they are different
+     * things:
+     *
+     *  - a `folderKey` binding's key is the CONNECTION's key, because the folder is
+     *    resolved through the connection, while its value is the folder's own key
+     *    (9 of 9; `folderCompanionKeys` in `serialize.ts` exists to write this);
+     *  - a compound process key `<folderPath>.<name>` projects onto the pair of bindings
+     *    as its two halves — the `folderPath` binding's value is the folder, the `name`
+     *    binding's value is the name;
+     *  - a renamed resource keeps the key it was bound under and tracks the new name in
+     *    `value`.
+     *
+     * **The author-side `bindings.json` uses this field the other way round** — there
+     * `resourceKey` is the real tenant value to inline and `default` is an offline
+     * placeholder, which is why `Bindings.resolve()` prefers `resourceKey` while the
+     * engine reads only `value`. Both are right for their own file; `connector.ts`
+     * translates between them. This option is the WIRE meaning.
+     */
     resourceKey?: string;
     /**
      * Narrows the resource, e.g. `'Agent'` for an agent process.
@@ -1414,6 +1529,33 @@ export interface VarOpts {
     schema?: unknown;
     /** Mark the declaration `required="true"`, as a process input can be. */
     required?: boolean;
+    /**
+     * The product's `custom="true"` flag: an author added this declaration, as opposed
+     * to its coming with a node's contract.
+     *
+     * The designer writes it on every variable a person typed into the variables panel
+     * and on no variable it derived from a node's output row, which makes it the one
+     * attribute that says which of the two a declaration is. Measured over
+     * `research/bpmn-roundtrip/corpus/`: 119 of 842 declarations carry it, and the split
+     * is clean — a node-output declaration never does.
+     *
+     * Nothing executes differently either way; it is designer bookkeeping, carried so an
+     * import round-trips and so `implicitNodeVars` has an explicit signal rather than an
+     * inferred one.
+     */
+    custom?: boolean;
+    /**
+     * The product's `internal="true"` flag: the platform owns this declaration, not the
+     * author — `internalCustomInstanceId` and its kind. 3 in the corpus. Carried, not
+     * interpreted.
+     */
+    internal?: boolean;
+    /**
+     * A refinement of `type` the designer carries, e.g. `subType="object"` on a
+     * `jsonSchema` variable that holds an object rather than an array. 5 in the corpus.
+     * Carried, not interpreted.
+     */
+    subType?: string;
 }
 /**
  * Boundary events declared on the activity they attach to — the callback every
@@ -2772,6 +2914,32 @@ declare abstract class ScopeBuilder {
      * @returns This builder, so calls chain.
      */
     output(id: string, type: TypeDesc, opts?: VarOpts): this;
+    /**
+     * Several declarations as one call — the array form of `.var()` / `.input()` /
+     * `.output()`.
+     *
+     * Identical in effect, and there for how it READS: a real process declares dozens,
+     * and one `.var(…)` per line is a wall of repeated method names that the eye has to
+     * scan past to find the data. As an array the block indents, the prefix is written
+     * once, and the declarations line up as the table they are. `decompile` emits this
+     * form; the singular calls are unchanged and can be mixed with it freely.
+     *
+     * Each entry's `direction` picks which of the three it is, defaulting to
+     * `inputOutput` — so one block can carry a process's inputs, its internal state and
+     * its outputs in the order the document had them.
+     *
+     * ```ts
+     * .vars([
+     *   { id: 'invoiceId', type: 'string', direction: 'input', required: true },
+     *   { id: 'total', type: 'number', default: 0 },
+     *   { id: 'approved', type: 'boolean', direction: 'output' },
+     * ])
+     * ```
+     *
+     * @param entries - The declarations, in the order they should be written.
+     * @returns This builder, so calls chain.
+     */
+    vars(entries: VarEntry[]): this;
     private declareVar;
 }
 /**
@@ -3042,6 +3210,24 @@ export declare class BpmnBuilder extends ScopeBuilder {
     private readonly _id;
     private _name?;
     private _metadata?;
+    /** Non-authoring state pinned by `.preserve()`. */
+    private _preservation?;
+    /**
+     * Carry non-authoring state from a source document — **written by `decompile`; a
+     * greenfield author never needs this.**
+     *
+     * See {@link BpmnPreservation} for what belongs here and why. In one line: data the
+     * document carried that no rule derives and nothing executes, kept so a
+     * decompile/edit/recompile loop produces the file it started from. An agent editing
+     * such a file should leave the call alone — there is nothing in it to reason about,
+     * and no behaviour to change by changing it.
+     *
+     * Calling it twice REPLACES the block, matching `.layout()` on the Flow side.
+     *
+     * @param preservation - The carried state — see {@link BpmnPreservation}.
+     * @returns This builder, so calls chain.
+     */
+    preserve(preservation: BpmnPreservation): this;
     /**
      * @param _id - The process id, as passed to `bpmn()`.
      * @returns The top-level builder.
@@ -3127,10 +3313,23 @@ export declare class BpmnBuilder extends ScopeBuilder {
      * ```
      */
     schema(id: string, schema: unknown): this;
+    /**
+     * Several named schemas as one call — the array form of {@link BpmnBuilder.schema}.
+     *
+     * Same reason as {@link ScopeBuilder.vars}: a process that repeats one shape across
+     * twenty nodes declares a handful of these, and the array indents them into a block
+     * instead of a column of repeated prefixes. `decompile` emits this form.
+     *
+     * @param entries - The schemas to declare.
+     * @returns This builder, so calls chain.
+     */
+    schemas(entries: SchemaEntry[]): this;
     /**
      * Declare an external identifier the process needs supplied — a base URL, a
      * folder path, a process name (`uipath:binding`). Expressions read it as
-     * `=bindings.<id>`, and an offline run resolves it to `value`.
+     * `=bindings.<id>`, and it resolves to `value` unless a deploy or `--bindings`
+     * overrides it — with neither, the binding is unresolved and a dispatching run
+     * refuses to start.
      *
      * @remarks
      * A connector's `connection`/`folder` already produce their own bindings at
@@ -3148,10 +3347,22 @@ export declare class BpmnBuilder extends ScopeBuilder {
      * ```
      *
      * @param id - The binding's id — what `=bindings.<id>` refers to.
-     * @param opts - Display `name`, the `value` it defaults to, and which resource it addresses.
+     * @param opts - Display `name`, the `value` it resolves to, and which resource it addresses.
      * @returns This builder, so calls chain.
      */
     binding(id: string, opts?: BindingOpts): this;
+    /**
+     * Several bindings as one call — the array form of {@link BpmnBuilder.binding}.
+     *
+     * This is the block the array form was wanted for: bindings come in pairs, one per
+     * resource the process touches, and a real export carries dozens — 73 in
+     * `InvoiceApproval.bpmn.ts`, which was the single largest run of repeated method
+     * names in the file. `decompile` emits this form.
+     *
+     * @param entries - The bindings to declare, in document order.
+     * @returns This builder, so calls chain.
+     */
+    bindings(entries: BindingEntry[]): this;
     /**
      * Finish the process and return the graph the serializer turns into XML.
      *

package/dist/bpmn/bpmn-sdk.js

@@ -2097,6 +2097,36 @@ class ScopeBuilder {
     output(id, type, opts = {}) {
         return this.declareVar(id, type, 'output', opts);
     }
+    /**
+     * Several declarations as one call — the array form of `.var()` / `.input()` /
+     * `.output()`.
+     *
+     * Identical in effect, and there for how it READS: a real process declares dozens,
+     * and one `.var(…)` per line is a wall of repeated method names that the eye has to
+     * scan past to find the data. As an array the block indents, the prefix is written
+     * once, and the declarations line up as the table they are. `decompile` emits this
+     * form; the singular calls are unchanged and can be mixed with it freely.
+     *
+     * Each entry's `direction` picks which of the three it is, defaulting to
+     * `inputOutput` — so one block can carry a process's inputs, its internal state and
+     * its outputs in the order the document had them.
+     *
+     * ```ts
+     * .vars([
+     *   { id: 'invoiceId', type: 'string', direction: 'input', required: true },
+     *   { id: 'total', type: 'number', default: 0 },
+     *   { id: 'approved', type: 'boolean', direction: 'output' },
+     * ])
+     * ```
+     *
+     * @param entries - The declarations, in the order they should be written.
+     * @returns This builder, so calls chain.
+     */
+    vars(entries) {
+        for (const e of entries)
+            this.declareVar(e.id, e.type, e.direction ?? 'inputOutput', e);
+        return this;
+    }
     declareVar(id, type, direction, opts) {
         this._vars.push({
             id,
@@ -2107,6 +2137,9 @@ class ScopeBuilder {
             elementId: opts.elementId,
             schema: opts.schema,
             required: opts.required,
+            custom: opts.custom,
+            internal: opts.internal,
+            subType: opts.subType,
         });
         return this;
     }
@@ -2433,6 +2466,27 @@ export class BpmnBuilder extends ScopeBuilder {
     _id;
     _name;
     _metadata;
+    /** Non-authoring state pinned by `.preserve()`. */
+    _preservation;
+    /**
+     * Carry non-authoring state from a source document — **written by `decompile`; a
+     * greenfield author never needs this.**
+     *
+     * See {@link BpmnPreservation} for what belongs here and why. In one line: data the
+     * document carried that no rule derives and nothing executes, kept so a
+     * decompile/edit/recompile loop produces the file it started from. An agent editing
+     * such a file should leave the call alone — there is nothing in it to reason about,
+     * and no behaviour to change by changing it.
+     *
+     * Calling it twice REPLACES the block, matching `.layout()` on the Flow side.
+     *
+     * @param preservation - The carried state — see {@link BpmnPreservation}.
+     * @returns This builder, so calls chain.
+     */
+    preserve(preservation) {
+        this._preservation = preservation;
+        return this;
+    }
     /**
      * @param _id - The process id, as passed to `bpmn()`.
      * @returns The top-level builder.
@@ -2536,10 +2590,27 @@ export class BpmnBuilder extends ScopeBuilder {
         this._schemas.set(id, schema);
         return this;
     }
+    /**
+     * Several named schemas as one call — the array form of {@link BpmnBuilder.schema}.
+     *
+     * Same reason as {@link ScopeBuilder.vars}: a process that repeats one shape across
+     * twenty nodes declares a handful of these, and the array indents them into a block
+     * instead of a column of repeated prefixes. `decompile` emits this form.
+     *
+     * @param entries - The schemas to declare.
+     * @returns This builder, so calls chain.
+     */
+    schemas(entries) {
+        for (const e of entries)
+            this._schemas.set(e.id, e.body);
+        return this;
+    }
     /**
      * Declare an external identifier the process needs supplied — a base URL, a
      * folder path, a process name (`uipath:binding`). Expressions read it as
-     * `=bindings.<id>`, and an offline run resolves it to `value`.
+     * `=bindings.<id>`, and it resolves to `value` unless a deploy or `--bindings`
+     * overrides it — with neither, the binding is unresolved and a dispatching run
+     * refuses to start.
      *
      * @remarks
      * A connector's `connection`/`folder` already produce their own bindings at
@@ -2557,7 +2628,7 @@ export class BpmnBuilder extends ScopeBuilder {
      * ```
      *
      * @param id - The binding's id — what `=bindings.<id>` refers to.
-     * @param opts - Display `name`, the `value` it defaults to, and which resource it addresses.
+     * @param opts - Display `name`, the `value` it resolves to, and which resource it addresses.
      * @returns This builder, so calls chain.
      */
     binding(id, opts = {}) {
@@ -2575,6 +2646,22 @@ export class BpmnBuilder extends ScopeBuilder {
         });
         return this;
     }
+    /**
+     * Several bindings as one call — the array form of {@link BpmnBuilder.binding}.
+     *
+     * This is the block the array form was wanted for: bindings come in pairs, one per
+     * resource the process touches, and a real export carries dozens — 73 in
+     * `InvoiceApproval.bpmn.ts`, which was the single largest run of repeated method
+     * names in the file. `decompile` emits this form.
+     *
+     * @param entries - The bindings to declare, in document order.
+     * @returns This builder, so calls chain.
+     */
+    bindings(entries) {
+        for (const e of entries)
+            this.binding(e.id, e);
+        return this;
+    }
     /**
      * Finish the process and return the graph the serializer turns into XML.
      *
@@ -2643,6 +2730,7 @@ export class BpmnBuilder extends ScopeBuilder {
             nodes: this._nodes,
             flows: this._flows,
             schemas: this._schemas,
+            preservation: this._preservation,
         };
         // First-level validation, intrinsic to running the SDK: catch a reference to
         // an undeclared `vars.<name>` HERE — the one thing `uip maestro bpmn validate`

package/dist/bpmn/check.js

@@ -64,6 +64,7 @@ export function check(built) {
     const seenIds = new Set();
     checkScope(built.nodes, built.flows, 'process', diags, seenIds, true);
     checkScopedVars(built, diags);
+    checkVariableOrder(built, diags);
     checkDocumentIds(built, diags);
     checkFolderBindings(built, diags);
     checkEntryPointId(built, diags);
@@ -304,6 +305,91 @@ function checkDocumentIds(built, diags) {
     for (const e of built.errors)
         claim(e.id, `error "${e.name}"`);
 }
+/**
+ * A pinned declaration order must name the declarations it is ordering.
+ *
+ * `.preserve({ variableOrder })` is round-trip bookkeeping — `decompile` writes it because a
+ * declaration folded onto its output row has no line of its own to carry its
+ * position, and nothing derives that position (it is the designer's creation order,
+ * which follows the owning element's document order in none of the five exports in
+ * `research/bpmn-roundtrip/corpus/`). An author never writes one.
+ *
+ * Which is exactly why it needs checking. Every malformed list is applied in silence:
+ * an id no declaration has is ignored, a DUPLICATE is harmless, and a PARTIAL list
+ * promotes what it names and demotes everything else — the mistake an author editing
+ * a decompiled file makes by adding a variable and not the array. Nothing else
+ * reports it: the order changes no behaviour, `uip maestro bpmn validate` answers
+ * `Success` on a reordered block, and the only symptom is a variables panel that
+ * lists things differently than the file it came from.
+ *
+ * Warnings, not errors, because nothing it can say makes the process invalid.
+ */
+function checkVariableOrder(built, diags) {
+    const order = built.preservation?.variableOrder;
+    if (!order?.length)
+        return;
+    // Two sets, because the order applies to ONE `uipath:variables` block. `root` is what
+    // the order governs and so what it has to be complete over; `anywhere` also holds the
+    // sub-process blocks, whose ids are legal to name (they rank last and keep their
+    // relative order) and must not be reported as unknown.
+    //
+    // Without that split, every process with a sub-process block was INCOMPLETE by
+    // construction — `billing-disputes` reported its 24 sub-process declarations as left
+    // out, when a sub-process declaration is never folded and so already states its
+    // position by its line.
+    const root = new Set();
+    // A derived declaration is not in `built.variables` — it is created at serialize
+    // time from the row that fills it — so ask the derivation itself rather than
+    // re-deriving the rule here, which is how the two sets drifted apart before.
+    for (const v of [...built.variables, ...implicitNodeVars(built.nodes, built.variables)])
+        root.add(v.id);
+    const anywhere = new Set(root);
+    const collectNested = (nodes) => {
+        for (const n of nodes) {
+            if (n.kind !== 'subProcess')
+                continue;
+            for (const v of n.variables)
+                anywhere.add(v.id);
+            for (const v of implicitNodeVars(n.nodes, n.variables))
+                anywhere.add(v.id);
+            collectNested(n.nodes);
+        }
+    };
+    collectNested(built.nodes);
+    const seen = new Set();
+    for (const id of order) {
+        if (!anywhere.has(id))
+            diags.push({
+                level: 'warning',
+                code: 'VARIABLE_ORDER_UNKNOWN_ID',
+                message: `.preserve({ variableOrder }) names "${id}", which no declaration has. It is ignored — ` +
+                    `the order is round-trip bookkeeping written by decompile, so a stale id usually means ` +
+                    `a variable was renamed or removed without updating the list.`,
+                where: id,
+            });
+        if (seen.has(id))
+            diags.push({
+                level: 'warning',
+                code: 'VARIABLE_ORDER_DUPLICATE_ID',
+                message: `.preserve({ variableOrder }) names "${id}" more than once. The first position wins; drop the rest.`,
+                where: id,
+            });
+        seen.add(id);
+    }
+    // The dangerous shape: a list that names SOME of them. Everything it leaves out is
+    // written after everything it names, which reorders declarations the author never
+    // touched — and looks like nothing went wrong.
+    const missing = [...root].filter((id) => !seen.has(id));
+    if (missing.length)
+        diags.push({
+            level: 'warning',
+            code: 'VARIABLE_ORDER_INCOMPLETE',
+            message: `.preserve({ variableOrder }) leaves out ${missing.length} declaration(s) — ${missing.slice(0, 5).join(', ')}` +
+                `${missing.length > 5 ? `, and ${missing.length - 5} more` : ''}. ` +
+                `They are written after every id the list names, which reorders the block. List them all, or drop the call.`,
+            where: missing[0],
+        });
+}
 /**
  * A variable scoped with `elementId` must name an element that exists.
  *

package/dist/bpmn/decompile-cli.js

@@ -3,7 +3,7 @@
  * decompile-cli — `<Name>.bpmn` → `<Name>.bpmn.ts`
  *
  * Usage:
- *   node --experimental-strip-types decompile-cli.js <Name.bpmn> [-o Name.bpmn.ts] [--import <specifier>] [--style explicit|nested] [--keep-flow-ids]
+ *   node --experimental-strip-types decompile-cli.js <Name.bpmn> [-o Name.bpmn.ts] [--import <specifier>] [--style explicit|nested] [--keep-flow-ids] [--keep-unused-bindings]
  *
  * 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
@@ -42,7 +42,7 @@ function opt(argv, name) {
  */
 export async function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-        console.error('usage: decompile <Name.bpmn> [-o Name.bpmn.ts] [--import <specifier>] [--style explicit|nested] [--keep-flow-ids]');
+        console.error('usage: decompile <Name.bpmn> [-o Name.bpmn.ts] [--import <specifier>] [--style explicit|nested] [--keep-flow-ids] [--keep-unused-bindings]');
         return 2;
     }
     const style = opt(argv, '--style') ?? 'explicit';
@@ -67,15 +67,19 @@ export async function run(argv) {
         }
     }
     const keepFlowIds = argv.includes('--keep-flow-ids');
+    const keepUnusedBindings = argv.includes('--keep-unused-bindings');
     const flags = new Set(['-o', '--import', '--style']);
-    const input = argv.find((a, i) => a !== '--keep-flow-ids' && !flags.has(a) && !flags.has(argv[i - 1]));
+    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) {
         console.error('decompile: missing <Name.bpmn>');
         return 2;
     }
     const xml = readFileSync(input, 'utf8');
     const importSpecifier = opt(argv, '--import') ?? BPMN_IMPORT;
-    let source = await decompile(xml, { importSpecifier });
+    let pruned = [];
+    const base0 = { importSpecifier, keepUnusedBindings, onPrune: (ids) => (pruned = ids) };
+    let source = await decompile(xml, base0);
     let lifted;
     let fallback;
     if (style === 'nested') {
@@ -86,7 +90,7 @@ export async function run(argv) {
         const sdkEntry = fileURLToPath(new URL('./bpmn-sdk.js', import.meta.url));
         for (const sequenceMode of [true, false]) {
             let summary;
-            const nested = await decompile(xml, { importSpecifier, style: 'nested', relabelFlows: !keepFlowIds, sequenceMode, onLift: (s) => (summary = s) });
+            const nested = await decompile(xml, { ...base0, 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) {
@@ -102,6 +106,11 @@ export async function run(argv) {
     const out = opt(argv, '-o') ?? defaultSourceOut(`${base}.bpmn.ts`);
     writeFileSync(out, source);
     console.log(`decompile: wrote ${out}`);
+    if (pruned.length) {
+        // Never silent: these are declarations the source had and the output does not.
+        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 (lifted) {
         const flat = lifted.leftFlat.length ? `; left flat: ${lifted.leftFlat.map((r) => `${r.id} (${r.reason})`).join('; ')}` : '';
         const renamed = lifted.renamedFlows.length

package/dist/bpmn/decompile.d.ts

@@ -48,6 +48,35 @@ export interface BpmnDecompileOptions {
     sequenceMode?: boolean;
     /** Receives what the nested style lifted and what it left flat, and why. */
     onLift?: (summary: LiftSummary) => void;
+    /**
+     * Echo binding declarations that NOTHING in the document references. Defaults to
+     * `false` — they are dropped, and {@link BpmnDecompileOptions.onPrune} is told.
+     *
+     * The designer writes a binding pair every time a resource is picked and collects
+     * none of them, so a real export accumulates rows that no `=bindings.<id>` reads:
+     * 298 of 528 across `research/bpmn-roundtrip/corpus/`, including four `folderPath`
+     * rows for one queue and a whole earlier naming of two others. There is no way to
+     * remove one from the canvas, so an author who never decompiles is stuck with them.
+     *
+     * They are not inert. A binding with no `value` is UNRESOLVED, and the engine
+     * refuses to start a dispatching run listing every one of them
+     * (`local-engine/src/v2/dispatch/bindings.ts`, `describeMissingBindings`) — 105 on
+     * `billing-disputes`, 74 of which nothing references. `uip maestro bpmn validate`
+     * reports none of this: it answers `Success` on every corpus file.
+     *
+     * Dropping one is safe in the direction that matters. Solution resources are
+     * derived by walking NODES and matching each one's connection back to a binding
+     * (`connectionResources` in `bindings-v2.ts`), so a row no node uses provisions
+     * nothing. And "referenced" is decided over the whole document text, so any mention
+     * at all keeps the row — the failure mode is keeping a dead binding, never dropping
+     * a live one.
+     *
+     * Set `true` (`--keep-unused-bindings`) for a byte-exact round trip, which is what
+     * `research/bpmn-roundtrip/roundtrip.sh` measures.
+     */
+    keepUnusedBindings?: boolean;
+    /** Receives the binding ids dropped as unreferenced — see {@link BpmnDecompileOptions.keepUnusedBindings}. */
+    onPrune?: (droppedBindingIds: string[]) => void;
 }
 /** What `style: 'nested'` did — see {@link BpmnDecompileOptions.style}. */
 export interface LiftSummary {