@uipath/maestro-builder-sdk 6.38.0 → 6.40.0

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

@@ -112,6 +112,8 @@ export type BpmnNode = {
      * BPMN's default, interrupting, and writes no attribute.
      */
     interrupting?: boolean;
+    /** A start event's own `uipath:entryPointId`; `false` writes none. */
+    entryPointId?: string | false;
 } | {
     kind: 'boundaryEvent';
     id: string;
@@ -175,6 +177,8 @@ export type BpmnNode = {
     name?: string;
     /** The registry extension type, e.g. `'Intsvc.UnifiedHttpRequest'`. */
     type: string;
+    /** When emitted as a `bpmn:startEvent`: its `uipath:entryPointId`; `false` writes none. */
+    entryPointId?: string | false;
     /** `uipath:context` values, by field name. */
     context: Record<string, unknown>;
     /** The payload, shaped by the type's `inputPattern`. */
@@ -203,6 +207,8 @@ export type BpmnNode = {
     kind: 'connectorEvent';
     id: string;
     name?: string;
+    /** A trigger's `uipath:entryPointId`; `false` writes none. */
+    entryPointId?: string | false;
     /**
      * `trigger` STARTS the process (`Intsvc.EventTrigger`, a `bpmn:startEvent`
      * carrying a message event definition); `event` pauses one mid-flow
@@ -539,8 +545,15 @@ export interface ProcessMetadata {
      * The root start event's package entry-point id (`uipath:entryPointId`). A GUID —
      * the one `bpmn init` assigned, or `crypto.randomUUID()`; `validate` refuses any
      * other value and `check` reports `ENTRYPOINT_ID_NOT_GUID`.
+     *
+     * Optional since every start event gets a stable derived id when none is set
+     * (`entry-point-id.ts`): the canvas writes one on every start, and
+     * `uip maestro bpmn refresh` requires one on every root manual start. `false`
+     * writes none on the root start — what `decompile` emits for an import that
+     * carried none, so the round trip stays faithful. A start event other than the
+     * first root one takes its id on the event itself (`StartOpts.entryPointId`).
      */
-    entryPointId?: string;
+    entryPointId?: string | false;
     /** Free-form document tags (`uipath:tags` / `uipath:tag`). */
     tags?: string[];
     /** Case-management marker (`uipath:caseManagement`) — `version` plus its body value. */
@@ -685,6 +698,15 @@ export interface StartOpts {
      * {@link ScopeBuilder.eventSubProcess} sets this from its own `interrupting` option.
      */
     interrupting?: boolean;
+    /**
+     * This start event's `uipath:entryPointId`. Unset, a root start derives a stable id
+     * from the process and event ids — which therefore changes if either is renamed, so
+     * pin the old id here when renaming in a deployed process; `false` writes none (what
+     * `decompile` emits for an imported start that carried none). The first root start
+     * may also take it from `.metadata({ entryPointId })`. A start inside a sub-process
+     * derives nothing (the canvas strips ids there) and writes only a value set here.
+     */
+    entryPointId?: string | false;
 }
 /**
  * Options for `.endEvent()`. `terminate`, `error`, or `message` picks the event
@@ -1497,6 +1519,11 @@ export interface ConnectorEventOpts extends ActivityOpts {
     outputs?: Record<string, string>;
     /** `=`-expression that skips the node when truthy. */
     skipCondition?: string;
+    /**
+     * `.eventTrigger()` only: the start event's `uipath:entryPointId`. Unset, a stable
+     * id is derived; `false` writes none. Ignored by `.waitForEvent()`.
+     */
+    entryPointId?: string | false;
 }
 /** Options for `.externalAgent()` / `.externalWorkflow()`. */
 export interface ExternalTaskOpts extends ActivityOpts {
@@ -1607,6 +1634,12 @@ export interface ActivityNodeOpts extends ActivityOpts {
      * writing `.activity()` by hand wants the defaults.
      */
     contextVerbatim?: boolean;
+    /**
+     * When the registry type is emitted as a `bpmn:startEvent` (a trigger such as
+     * `Intsvc.EventTrigger`): its `uipath:entryPointId`. Unset, a stable id is derived;
+     * `false` writes none, as `decompile` emits for an imported start that carried none.
+     */
+    entryPointId?: string | false;
 }
 /**
  * The BPMN task elements that are legal with NO `uipath:*` payload.
@@ -1892,6 +1925,8 @@ export interface EventSubProcessOpts {
     startName?: string;
     /** A payload on the start event, spelled out by hand — see {@link ExtensionPayload}. Exclusive with `errorVar`. */
     startPayload?: ExtensionPayload;
+    /** The nested start event's `uipath:entryPointId`, written only when set: the canvas strips ids inside a sub-process, so none is derived. */
+    startEntryPointId?: string | false;
     /** `uipath:tags` on the sub-process — see {@link ActivityOpts.tags}. */
     tags?: Record<string, string>;
     /** A `uipath:mapping` on the sub-process itself — see {@link SubProcessOpts.payload}. */

package/dist/bpmn/bpmn-sdk.js

@@ -697,6 +697,7 @@ class ScopeBuilder {
         return this.push({
             kind: 'startEvent',
             id,
+            entryPointId: opts.entryPointId,
             name: opts.name,
             payload: opts.payload,
             interrupting: opts.interrupting === false ? false : undefined,
@@ -1754,6 +1755,7 @@ class ScopeBuilder {
         return this.push({
             kind: 'connectorEvent',
             id,
+            entryPointId: opts.entryPointId,
             name: opts.name,
             subscribe: 'trigger',
             key: connector,
@@ -1907,6 +1909,7 @@ class ScopeBuilder {
             outputRows: opts.outputRows,
             skipCondition: opts.skipCondition,
             contextVerbatim: opts.contextVerbatim,
+            entryPointId: opts.entryPointId,
             tags: opts.tags,
             retry: opts.retry,
             errorMapping: opts.errorMapping,
@@ -2036,6 +2039,7 @@ class ScopeBuilder {
         sb._begin({
             kind: 'startEvent',
             id: startId,
+            entryPointId: opts.startEntryPointId,
             name: opts.startName,
             event,
             payload: opts.startPayload ?? (capture !== undefined ? errorCapturePayload(capture, 'startEvent') : undefined),

package/dist/bpmn/check.js

@@ -67,6 +67,7 @@ export function check(built, opts = {}) {
     checkVariableOrder(built, diags);
     checkDocumentIds(built, diags);
     checkFolderBindings(built, diags);
+    checkIntsvcActivities(built, diags);
     checkEntryPointId(built, diags);
     checkMethodParentheses(built, diags);
     checkConnectorRows(built, diags);
@@ -309,15 +310,25 @@ const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
  * main one agent spent its whole turn budget there. Reported here, at the first rung.
  */
 function checkEntryPointId(built, diags) {
+    const report = (where, id, at) => {
+        diags.push({
+            level: 'error',
+            code: 'ENTRYPOINT_ID_NOT_GUID',
+            message: `${where} "${id}" is not a GUID; \`uip maestro bpmn validate\` refuses it. Use the id \`bpmn init\` ` +
+                `assigned (decompile the stub it wrote to carry it), a fresh one from \`crypto.randomUUID()\`, or leave it ` +
+                `unset and the SDK derives a stable one.`,
+            ...(at !== undefined ? { where: at } : {}),
+        });
+    };
     const id = built.metadata?.entryPointId;
-    if (id === undefined || GUID.test(id))
-        return;
-    diags.push({
-        level: 'error',
-        code: 'ENTRYPOINT_ID_NOT_GUID',
-        message: `metadata.entryPointId "${id}" is not a GUID; \`uip maestro bpmn validate\` refuses it. Use the id \`bpmn init\` ` +
-            `assigned (decompile the stub it wrote to carry it), or a fresh one from \`crypto.randomUUID()\`.`,
-    });
+    if (typeof id === 'string' && !GUID.test(id))
+        report('metadata.entryPointId', id);
+    for (const n of allNodes(built.nodes)) {
+        if (n.kind !== 'startEvent' && n.kind !== 'connectorEvent' && n.kind !== 'typed')
+            continue;
+        if (typeof n.entryPointId === 'string' && !GUID.test(n.entryPointId))
+            report(`"${n.id}" entryPointId`, n.entryPointId, n.id);
+    }
 }
 /**
  * A `folderKey` binding must be keyed by its CONNECTION, not by the folder.
@@ -380,6 +391,242 @@ function checkFolderBindings(built, diags) {
         }
     }
 }
+/** The `method` vocabulary of the Integration Service activity catalog (`MethodName`). */
+const INTSVC_METHODS = new Set(['GET', 'GETBYID', 'POST', 'PUT', 'PATCH', 'DELETE']);
+/** The catalog's identity fields on an `Intsvc.ActivityExecution` task, in the order the message names them. */
+const INTSVC_IDENTITY = ['connectorKey', 'objectName', 'operation', 'method', 'path'];
+/**
+ * A hand-filled `Intsvc.ActivityExecution` task: what the catalog, the refresh and
+ * the runtime require of its context that `uip maestro bpmn validate` does not report.
+ *
+ * `.connector()` and `.dataService()` write this task from the library; an author
+ * who reaches for `.activity(id, 'Intsvc.ActivityExecution', …)` — the route the skill
+ * names for a connector the library lacks — fills the identity rows by hand from
+ * `uip is activities list <key>`, and the 2026-10-16 eval run measured what goes wrong
+ * (141 SDK-authored files, 109 such tasks): `objectName: 'N/A'` and `method: 'N/A'`
+ * copied from the catalog's GENERIC rows (5 tasks — `validate` reported them Valid, and
+ * they dispatch to nothing), an empty `operation` (5), `<METHOD_FROM_CLI>`-style template
+ * placeholders left in place, and a `connection` that `uip maestro bpmn refresh` then
+ * refused with `connection must reference a root binding as "=bindings.<id>"`.
+ *
+ * What the registry's own field notes say the rows are: `operation` is the catalog
+ * activity's `Name`, `objectName` its `ObjectName`, `method` its `MethodName`, `path` the
+ * request path `is resources describe` returns, and `connection` "points to a root binding
+ * for a Connection resource" with `folderKey` a second binding for the same key. Real
+ * exports agree on the shape and differ on one spelling: `operation` is the catalog Name
+ * on the canvas (`UpdateEntityRecordV2`) and the CRUD verb in 94 of 108 hand-written v1
+ * tasks (`Create`, `Retrieve`), so that field is held to "an identifier", not a list.
+ * `method` IS a closed list: GET, GETBYID, POST, PUT, PATCH, DELETE, measured over every
+ * task in both arms and the corpus.
+ *
+ * Errors where the task cannot dispatch or the platform refuses it; warnings where it
+ * deploys but the SDK cannot tell it is right.
+ */
+function checkIntsvcActivities(built, diags) {
+    // The bindings the compiled process will carry: the ones declared with `.binding()`,
+    // and the ones `serialize` synthesizes for every `.connector()`, `.eventTrigger()` /
+    // `.waitForEvent()` and external task from the symbolic names they read (ids equal
+    // to the names, `connector.ts` `bindingRef`) — a hand-filled task may reuse those.
+    const declared = new Map(built.bindings.map((b) => [b.id, { resource: String(b.resource ?? ''), propertyAttribute: String(b.propertyAttribute ?? '') }]));
+    for (const n of allNodes(built.nodes)) {
+        if (n.kind !== 'connector' && n.kind !== 'connectorEvent' && n.kind !== 'externalTask')
+            continue;
+        if (n.connection && !declared.has(n.connection))
+            declared.set(n.connection, { resource: 'Connection', propertyAttribute: 'ConnectionId' });
+        if (n.folder && !declared.has(n.folder))
+            declared.set(n.folder, { resource: 'Connection', propertyAttribute: 'folderKey' });
+    }
+    const expr = (v) => typeof v === 'string' && v.startsWith('=');
+    const text = (v) => (typeof v === 'string' ? v : v === undefined || v === null ? undefined : String(v));
+    for (const n of allNodes(built.nodes)) {
+        if (n.kind !== 'typed' || n.type !== 'Intsvc.ActivityExecution')
+            continue;
+        // `contextRows`, when given, REPLACE `context` at emission (typed-node.ts), so only
+        // the rows are the task's context then; a record field beside them is not emitted.
+        const ctx = {};
+        if (n.contextRows)
+            for (const row of n.contextRows)
+                ctx[row.name] = row.value ?? row.body ?? '';
+        else
+            Object.assign(ctx, n.context);
+        const where = n.id;
+        const key = text(ctx['connectorKey']) ?? '<connector-key>';
+        // 1. A catalog placeholder: `N/A` from a generic row, or a template's `<…>`.
+        for (const field of INTSVC_IDENTITY) {
+            const v = text(ctx[field]);
+            if (v === undefined)
+                continue;
+            const placeholder = /^n\/a$/i.test(v.trim()) || /^(<|&lt;)[^<>]*(>|&gt;)$/.test(v.trim());
+            if (!placeholder)
+                continue;
+            diags.push({
+                level: 'error',
+                code: 'INTSVC_CATALOG_PLACEHOLDER',
+                message: `"${n.id}" (Intsvc.ActivityExecution) has ${field}="${v}", which dispatches to nothing. ` +
+                    (/^n\/a$/i.test(v.trim())
+                        ? `"N/A" is what \`uip is activities list ${key}\` prints on a GENERIC record verb (Create/Retrieve/Update/Delete Record), ` +
+                            `whose object is chosen at design time: set objectName to an object from \`uip is resources list ${key} --connection-id <id>\`, ` +
+                            `method to that verb's HTTP method, and path from \`uip is resources describe ${key} <object> --operation <Verb> --connection-id <id>\`. ` +
+                            `For a curated activity, objectName and method are the row's ObjectName and MethodName.`
+                        : `Replace the placeholder with the catalog's value (\`uip is activities list ${key} --output json\`: Name → operation, ObjectName → objectName, MethodName → method; ` +
+                            `\`uip is resources describe\` → path).`) +
+                    ` Or let the library write the task: \`uip maestro registry prepare ${key} --action <name>\` then \`.connector()\`.`,
+                where,
+            });
+        }
+        // 2. `method` is the catalog's closed vocabulary.
+        const method = text(ctx['method']);
+        // An empty one is EMPTY_REQUIRED_FIELD's (the registry marks it required), as for `operation`.
+        if (method !== undefined && method.trim() !== '' && !expr(method) && !/^n\/a$/i.test(method.trim()) && !/^(<|&lt;)/.test(method.trim()) && !INTSVC_METHODS.has(method.trim())) {
+            diags.push({
+                level: 'error',
+                code: 'INTSVC_METHOD_UNKNOWN',
+                message: `"${n.id}" (Intsvc.ActivityExecution) has method="${method}"; the activity catalog's MethodName is one of ` +
+                    `${[...INTSVC_METHODS].join(', ')}` +
+                    (INTSVC_METHODS.has(method.trim().toUpperCase()) ? ` — write it in upper case: "${method.trim().toUpperCase()}".` : `. Read it from \`uip is activities list ${key} --output json\` (MethodName).`),
+                where,
+            });
+        }
+        // 3. `operation` is the catalog activity's Name (or the CRUD verb hand-written exports use): an identifier.
+        const operation = text(ctx['operation']);
+        if (operation !== undefined && operation.trim() !== '' && !expr(operation) && !/^n\/a$/i.test(operation.trim()) && !/^(<|&lt;)/.test(operation.trim())
+            && !/^[A-Za-z][A-Za-z0-9_]*$/.test(operation.trim())) {
+            diags.push({
+                level: 'error',
+                code: 'INTSVC_OPERATION_NOT_IDENTIFIER',
+                message: `"${n.id}" (Intsvc.ActivityExecution) has operation="${operation}"; the registry defines it as the activity catalog's Name ` +
+                    `(\`uip is activities list ${key}\`: CreateTestSet, QueryEntityRecordsCurated) — an identifier, not a REST slug or a label.`,
+                where,
+            });
+        }
+        // 4. `objectName` spelled as a REST path: validates, dispatches to nothing. Only a
+        // `/` says so — `::` is in curated ObjectNames too (`v2::webSearch`, airdk).
+        const objectName = text(ctx['objectName']);
+        if (objectName !== undefined && !expr(objectName) && objectName.includes('/')) {
+            diags.push({
+                level: 'warning',
+                code: 'INTSVC_OBJECT_NAME_SLUG',
+                message: `"${n.id}" (Intsvc.ActivityExecution) has objectName="${objectName}", which reads as a REST path, not an object. The platform matches ` +
+                    `on the catalog's ObjectName (\`uip is activities list ${key}\`: TestSet, UploadAttachment, v2::webSearch); a path validates and then dispatches to nothing.`,
+                where,
+            });
+        }
+        // 5. The path's placeholders each need a `target: 'path'` input row of that name.
+        const path = text(ctx['path']);
+        if (path !== undefined && !expr(path)) {
+            if (!path.startsWith('/')) {
+                diags.push({
+                    level: 'warning',
+                    code: 'INTSVC_PATH_NOT_ABSOLUTE',
+                    message: `"${n.id}" (Intsvc.ActivityExecution) has path="${path}"; the request path \`is resources describe\` returns starts with "/" (e.g. "/v2/{ProjectId}/testsets").`,
+                    where,
+                });
+            }
+            const params = [...path.matchAll(/\{([^{}]+)\}/g)].map((m) => m[1]);
+            if (params.length > 0) {
+                // Bound by a row of that name targeting the path, or by a path AGGREGATE —
+                // `inputs: { pathParameters: { ProjectId } }` emits one `target="pathParameters"`
+                // row holding every placeholder (an expression-valued aggregate binds them all).
+                const PATH_TARGETS = new Set(['path', 'pathvariable', 'pathparameters']);
+                const bound = new Set();
+                let aggregateExpression = false;
+                const aggregate = (value) => {
+                    if (expr(value))
+                        aggregateExpression = true;
+                    else if (value && typeof value === 'object')
+                        for (const k of Object.keys(value))
+                            bound.add(k);
+                };
+                for (const r of n.inputRows ?? []) {
+                    const target = (r.target ?? '').toLowerCase();
+                    if (target === 'pathparameters' || target === 'pathvariable' || PATH_TARGETS.has(r.name.toLowerCase()))
+                        aggregate(r.body ?? r.value);
+                    if (PATH_TARGETS.has(target))
+                        bound.add(r.name);
+                }
+                if (!n.inputRows)
+                    for (const key of ['pathParameters', 'pathVariable'])
+                        if (key in (n.inputs ?? {}))
+                            aggregate(n.inputs[key]);
+                const unbound = aggregateExpression ? [] : params.filter((p) => !bound.has(p));
+                if (unbound.length > 0) {
+                    diags.push({
+                        level: 'warning',
+                        code: 'INTSVC_PATH_PARAM_UNBOUND',
+                        message: `"${n.id}" (Intsvc.ActivityExecution) path "${path}" has placeholder(s) ${unbound.map((p) => `{${p}}`).join(', ')} with no input row ` +
+                            `of that name targeting the path. Write \`inputs: { pathParameters: { ${unbound[0]}: '…' } }\` (the other fields stay ` +
+                            `beside it), or an \`inputRows\` row \`{ name: '${unbound[0]}', type: 'string', value: '…', target: 'path' }\` — a bare ` +
+                            `\`inputs: { ${unbound[0]} }\` lands in the body and leaves the placeholder unfilled.`,
+                        where,
+                    });
+                }
+            }
+        }
+        // 6. The connection and folder rows: binding references to declared Connection bindings.
+        const bindingRow = (field, attribute) => {
+            const v = text(ctx[field]);
+            if (v === undefined || v.trim() === '')
+                return;
+            if (!v.startsWith('=bindings.')) {
+                // A literal gets the binding to declare with that value; any other
+                // expression (`=vars.connId`) is told what refresh needs instead — a
+                // connection is resolved from a root binding, never computed at run time.
+                const label = field === 'connection' ? 'conn' : 'folder';
+                const refusal = `\`uip maestro bpmn refresh\` refuses it with \`${field} must reference a root binding as "=bindings.<id>"\``;
+                diags.push({
+                    level: 'error',
+                    code: 'INTSVC_CONNECTION_NOT_BINDING',
+                    message: expr(v)
+                        ? `"${n.id}" (Intsvc.ActivityExecution) has ${field}="${v}", an expression; ${refusal}. A ${field} is resolved from a root binding, ` +
+                            `not computed: declare \`.binding('${label}', { resource: 'Connection', propertyAttribute: '${attribute}', value: '<${field === 'connection' ? 'connection id' : 'folder key'}>' })\` ` +
+                            `and write ${field}: '=bindings.${label}'.`
+                        : `"${n.id}" (Intsvc.ActivityExecution) has ${field}="${v}", a literal; ${refusal}. Declare ` +
+                            `\`.binding('${label}', { resource: 'Connection', propertyAttribute: '${attribute}', value: '${v}' })\` ` +
+                            `and write ${field}: '=bindings.${label}'.`,
+                    where,
+                });
+                return;
+            }
+            const id = v.slice('=bindings.'.length);
+            const b = declared.get(id);
+            if (!b) {
+                diags.push({
+                    level: 'error',
+                    code: 'INTSVC_BINDING_UNDECLARED',
+                    message: `"${n.id}" (Intsvc.ActivityExecution) reads ${field}="${v}" but the process declares no binding "${id}" ` +
+                        `(\`uip maestro bpmn validate\` reports MISSING_BINDING). Declare it at the root: ` +
+                        `\`.binding('${id}', { resource: 'Connection', propertyAttribute: '${attribute}', value: '<${field === 'connection' ? 'connection id' : 'folder key'}>' })\`` +
+                        (field === 'folderKey' ? ' — keyed by its connection; the builder pairs it with the connection this task reads.' : '.'),
+                    where,
+                });
+                return;
+            }
+            const attr = b.propertyAttribute;
+            const resource = b.resource;
+            if (attr.toLowerCase() !== attribute.toLowerCase() || resource.toLowerCase() !== 'connection') {
+                diags.push({
+                    level: 'error',
+                    code: 'INTSVC_BINDING_MISMATCH',
+                    message: `"${n.id}" (Intsvc.ActivityExecution) reads ${field}="${v}", but binding "${id}" is resource "${resource}" / ` +
+                        `propertyAttribute "${attr}"; the ${field} row needs resource "Connection" / propertyAttribute "${attribute}".`,
+                    where,
+                });
+            }
+        };
+        bindingRow('connection', 'ConnectionId');
+        bindingRow('folderKey', 'folderKey');
+        if (text(ctx['connection']) === undefined) {
+            diags.push({
+                level: 'warning',
+                code: 'INTSVC_CONNECTION_MISSING',
+                message: `"${n.id}" (Intsvc.ActivityExecution) names no connection. The registry says to omit \`connection\` and \`folderKey\` only ` +
+                    `when the activity uses none; a connector activity almost always does. Declare a Connection binding and read it as ` +
+                    `connection: '=bindings.<id>' (\`uip is connections list ${key} --all-folders --output json\` lists the ids).`,
+                where,
+            });
+        }
+    }
+}
 /**
  * Every `id` in the document must be unique — including across KINDS.
  *

package/dist/bpmn/decompile.js

@@ -61,6 +61,7 @@ import { BPMN_SCHEMA_VERSIONS } from './format-profile.js';
 import { preserveSchemaVersion } from '../schema-version.js';
 import { commentText } from '../core/comment-text.js';
 import { tsLiteral, tsText } from '../core/ts-literal.js';
+import { defaultEntryPointId } from './entry-point-id.js';
 const require = createRequire(import.meta.url);
 const uipathDescriptor = require('./uipath-moddle.v1.json');
 /**
@@ -717,6 +718,47 @@ function emitOutputRows(payload) {
     return `[${rendered.join(', ')}]`;
 }
 // ─── Element emitters ─────────────────────────────────────────────────────────
+/**
+ * The process being decompiled, for the entry-point spelling below: the builder id
+ * the derived default is seeded from, the root start events, and the one root start
+ * whose id `.metadata({ entryPointId })` spells — the only root start, when there is
+ * exactly one. With several, every root start spells its own on the event, because
+ * `serialize` hands `.metadata()`'s id to the first root start in CHAIN order and the
+ * chain is emitted manual-first, which need not be document order.
+ */
+let runEntryPoints = {
+    builderProcessId: '',
+    rootStartIds: new Set(),
+};
+/**
+ * How an imported start event's `uipath:entryPointId` is spelled on the event's own
+ * call, or `undefined` for none. A root start: the value as text when the file
+ * carries one the SDK would not derive; nothing when it equals the derived default
+ * (compile writes it back unprompted); `false` when the file carries none, so the
+ * recompile adds nothing. The lone root start is `.metadata()`'s and gets nothing
+ * here. A nested start derives nothing on compile, so it is spelled only when the
+ * file carries a value.
+ */
+function entryPointOption(el) {
+    if (localName(el.$type) !== 'startEvent' || el.id === runEntryPoints.metadataStartId)
+        return undefined;
+    const legacy = runEntryPoints.processLevel;
+    const value = entryPointValueOf(el) ?? (legacy !== undefined && legacy.startId === el.id ? legacy.value : undefined);
+    if (!runEntryPoints.rootStartIds.has(el.id))
+        return value === undefined ? undefined : tsText(value);
+    return entryPointText(el.id, value);
+}
+/** The `uipath:entryPointId` value a start event carries, if any. */
+function entryPointValueOf(el) {
+    const row = (el.extensionElements?.values ?? []).find((x) => x.$type === 'uipath:EntryPointId');
+    return row?.value !== undefined ? String(row.value) : undefined;
+}
+/** `entryPointOption`'s spelling for a ROOT start event id and the value it carries. */
+function entryPointText(startId, value) {
+    if (value === undefined)
+        return 'false';
+    return value === defaultEntryPointId(runEntryPoints.builderProcessId, startId) ? undefined : tsText(value);
+}
 /**
  * A registry-typed node.
  *
@@ -776,6 +818,7 @@ function emitTypedNode(chain, el, payload, type) {
         ['outputs', verbatimRows === undefined ? record(extras) : undefined],
         ['skipCondition', payload.skipCondition !== undefined ? tsText(payload.skipCondition) : undefined],
         ['contextVerbatim', Object.keys(ctx).length ? 'true' : undefined],
+        ['entryPointId', entryPointOption(el)],
         ['tags', tagsOf(el)],
         ['retry', emitRetry(retryOf(el))],
         ['errorMapping', emitErrorMapping(errorMappingOf(el))],
@@ -1489,6 +1532,7 @@ function renderEventSubProcess(plan, sp, depth, indent) {
         ],
         ['startId', start.id !== `${sp.id}_start` ? tsText(start.id) : undefined],
         ['startName', start.name !== undefined ? tsText(start.name) : undefined],
+        ['startEntryPointId', entryPointOption(start)],
         ['startPayload', payload && type && capture === undefined ? opts([['type', tsText(type)], ['outputRows', emitOutputRows(payload) ?? '[]']]) : undefined],
         ['tags', tagsOf(sp)],
         ['payload', spPayload && spType ? opts([['type', tsText(spType)], ['outputRows', emitOutputRows(spPayload) ?? '[]']]) : undefined],
@@ -1665,6 +1709,7 @@ function emitTriggerStartEvent(chain, el, payload, type) {
         ['name', el.name !== undefined ? tsText(el.name) : undefined],
         ...eventOptions(el),
         ['trigger', trigger],
+        ['entryPointId', entryPointOption(el)],
     ])})`);
 }
 /**
@@ -1748,6 +1793,7 @@ function emitEvent(chain, el, kind, payload, type) {
         // Only a start event can be non-interrupting, and only the exception is
         // spelled — the builder's default is BPMN's.
         ['interrupting', kind === 'startEvent' && el.isInterrupting === false ? 'false' : undefined],
+        ['entryPointId', entryPointOption(el)],
         ['payload', eventPayload],
     ]))})`);
 }
@@ -2086,6 +2132,26 @@ export async function decompile(xml, options = {}) {
     const migration = findExt('uipath:MigrationVersion');
     const rootStart = (process.flowElements ?? []).find((x) => x.$type === 'bpmn:StartEvent');
     const entryPoint = (rootStart?.extensionElements?.values ?? []).find((x) => x.$type === 'uipath:EntryPointId') ?? findExt('uipath:EntryPointId');
+    const rootStarts = (process.flowElements ?? []).filter((x) => x.$type === 'bpmn:StartEvent');
+    // `bpmn(process.id)` is what the source will say, so it is the seed on both sides.
+    const builderId = String(process.id ?? '');
+    const processLevelEntryPoint = findExt('uipath:EntryPointId');
+    runEntryPoints = {
+        builderProcessId: builderId,
+        rootStartIds: new Set(rootStarts.map((x) => x.id)),
+        metadataStartId: rootStarts.length === 1 ? rootStart?.id : undefined,
+        ...(rootStarts.length > 1 && rootStart !== undefined && processLevelEntryPoint?.value !== undefined
+            && !(rootStart.extensionElements?.values ?? []).some((x) => x.$type === 'uipath:EntryPointId')
+            ? { processLevel: { startId: rootStart.id, value: String(processLevelEntryPoint.value) } }
+            : {}),
+    };
+    // A lone root start's id is `.metadata()`'s: the file's own value when the SDK would
+    // not derive it, `false` when the file carries none (so the recompile adds none), and
+    // nothing when it equals the derived default. With several root starts each spells
+    // its own on the event (see `runEntryPoints`).
+    const rootEntryPointText = rootStarts.length === 1 && rootStart !== undefined
+        ? entryPointText(rootStart.id, entryPoint?.value !== undefined ? String(entryPoint.value) : undefined)
+        : undefined;
     const tagsExt = findExt('uipath:Tags');
     const caseMgmt = findExt('uipath:CaseManagement');
     const tagValues = (tagsExt?.tags ?? []).map((t) => t.value).filter((v) => typeof v === 'string');
@@ -2103,13 +2169,13 @@ export async function decompile(xml, options = {}) {
     const schema = preserveSchemaVersion(BPMN_SCHEMA_VERSIONS, migration?.version);
     if (schema.call)
         chain.add(schema.call);
-    if (entryPoint !== undefined ||
+    if (rootEntryPointText !== undefined ||
         tagValues.length > 0 ||
         caseMgmt !== undefined ||
         nonExecutable) {
         chain.add(`.metadata(${opts([
             ['executable', nonExecutable ? 'false' : undefined],
-            ['entryPointId', entryPoint?.value !== undefined ? tsText(entryPoint.value) : undefined],
+            ['entryPointId', rootEntryPointText],
             ['tags', tagValues.length > 0 ? `[${tagValues.map((t) => tsText(t)).join(', ')}]` : undefined],
             [
                 'caseManagement',

package/dist/bpmn/entry-point-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The default `uipath:entryPointId` for one start event.
+ *
+ * @param builderProcessId - The id `bpmn(id)` was called with — not the `bpmn:process` id
+ *   on the wire, which `processId()` folds every non-identifier name to `Process_1`, so
+ *   two such processes would share every start's id.
+ * @param startEventId - The start event's element id.
+ */
+export declare function defaultEntryPointId(builderProcessId: string, startEventId: string): string;

package/dist/bpmn/entry-point-id.js

@@ -0,0 +1,35 @@
+/**
+ * The entry-point id a start event carries when nobody chose one.
+ *
+ * The canvas writes `uipath:entryPointId` on every root start event, and the CLI's
+ * packaging (`uip maestro bpmn refresh`, UiPath/cli `bpmn-packaging/entry-points.ts`)
+ * requires exactly one, a GUID, on every root manual start — "read from the BPMN,
+ * never minted, so the derived entry-points.json is stable across runs".
+ *
+ * A root start with no id of its own gets this one: the first 128 bits of SHA-256
+ * over the builder's process id and the start event id, in GUID shape — the derivation
+ * the Case compiler uses for an entry point's `uniqueId`. It is the same on every
+ * compile and machine, differs between processes and between starts, and is
+ * reproducible by `decompile`, which omits an id equal to it.
+ *
+ * It is derived from two names, so it CHANGES when either is renamed. The entry point's
+ * `uniqueId` is what Orchestrator rebinds a release by on upgrade
+ * (`ReleasesManager.cs`, `UniqueId`): rename `bpmn('Invoice')` or its start in a
+ * process that is already deployed, and on the next upgrade Orchestrator finds no
+ * entry point with the old `uniqueId` and silently rebinds the release to the main
+ * entry point. Pin the old id on the start (`.startEvent(id, { entryPointId })` or
+ * `.metadata({ entryPointId })`) when renaming either; `decompile` of the deployed
+ * file carries it.
+ */
+import { sha256Uuid } from '../core/stable-id.js';
+/**
+ * The default `uipath:entryPointId` for one start event.
+ *
+ * @param builderProcessId - The id `bpmn(id)` was called with — not the `bpmn:process` id
+ *   on the wire, which `processId()` folds every non-identifier name to `Process_1`, so
+ *   two such processes would share every start's id.
+ * @param startEventId - The start event's element id.
+ */
+export function defaultEntryPointId(builderProcessId, startEventId) {
+    return sha256Uuid(`uipath:entryPointId/${builderProcessId}/${startEventId}`);
+}