@uipath/maestro-builder-sdk 6.39.0 → 6.40.1

package/dist/bpmn/serialize.js

@@ -19,6 +19,7 @@ import { createConnectorTask } from './connector.js';
 import { createConnectorEvent, createExternalTask, intsvcOutputVar } from './intsvc.js';
 import { createExtensionPayload, createTypedNode, rowDeclaration, typedNodeOutputVar, verbatimOutputRows } from './typed-node.js';
 import { connectorOutputVars, typedNodeDeclaredVars } from './declared-vars.js';
+import { defaultEntryPointId } from './entry-point-id.js';
 const require = createRequire(import.meta.url);
 const uipathDescriptor = require('./uipath-moddle.v1.json');
 const NS = {
@@ -138,16 +139,7 @@ export async function serialize(built, opts = {}) {
     const meta = built.metadata;
     if (meta?.migrationVersion !== undefined)
         processExt.push(m.create('uipath:MigrationVersion', { version: meta.migrationVersion }));
-    if (meta?.entryPointId !== undefined) {
-        // The package metadata generator discovers entry points by reading the root start
-        // event. A process-level `uipath:entryPointId` looks plausible and validates as XML,
-        // but is invisible to `update-metadata`, which then writes an empty entry-points.json.
-        const start = flowElements.find((element) => element.$type === 'bpmn:StartEvent');
-        if (start) {
-            const extensions = (start.extensionElements ??= m.create('bpmn:ExtensionElements', { values: [] }));
-            (extensions.values ??= []).unshift(m.create('uipath:EntryPointId', { value: meta.entryPointId }));
-        }
-    }
+    stampEntryPointIds(ctx, built, flowElements, meta?.entryPointId);
     if (meta?.tags !== undefined && meta.tags.length > 0)
         processExt.push(m.create('uipath:Tags', { tags: meta.tags.map((t) => m.create('uipath:Tag', { value: t })) }));
     if (meta?.caseManagement !== undefined)
@@ -218,6 +210,57 @@ export function processId(id) {
     return /^[A-Za-z_][\w.-]*$/.test(id) ? id : 'Process_1';
 }
 // ─── Scope (process root or a sub-process body) ───────────────────────────────
+/**
+ * `uipath:entryPointId` on the process's root start events, triggered or manual.
+ *
+ * The package metadata generator discovers entry points by reading the root start
+ * events — a process-level `uipath:entryPointId` looks plausible and validates as XML,
+ * but is invisible to `update-metadata`, which then writes an empty entry-points.json
+ * — and `uip maestro bpmn refresh` requires exactly one, a GUID, on each root manual
+ * start. The canvas writes one on every ROOT start and strips any inside a
+ * `bpmn:SubProcess` on save, so a nested start gets no derived id here, only one the
+ * author set. A root start takes, in order: the event's own option, else
+ * `.metadata({ entryPointId })` for the first root start in chain order, else the
+ * stable derived id (`entry-point-id.ts`, seeded from the builder's own process id, so
+ * two processes with the same start id derive different ids); `false` writes none.
+ */
+function stampEntryPointIds(ctx, built, flowElements, rootDefault) {
+    const { m } = ctx;
+    const own = new Map();
+    for (const n of allNodes(built.nodes)) {
+        if (n.kind === 'startEvent' || n.kind === 'connectorEvent' || n.kind === 'typed')
+            own.set(n.id, n.entryPointId);
+    }
+    let first = true;
+    const stamp = (el, value) => {
+        if (value === undefined || value === false)
+            return;
+        const extensions = (el.extensionElements ??= m.create('bpmn:ExtensionElements', { values: [] }));
+        const values = (extensions.values ??= []);
+        if (values.some((x) => x.$type === 'uipath:EntryPointId'))
+            return;
+        values.unshift(m.create('uipath:EntryPointId', { value }));
+    };
+    const visit = (elements, root) => {
+        for (const el of elements) {
+            if (el.$type === 'bpmn:SubProcess') {
+                visit(el.flowElements ?? [], false);
+                continue;
+            }
+            if (el.$type !== 'bpmn:StartEvent')
+                continue;
+            const explicit = own.get(el.id);
+            if (!root) {
+                stamp(el, explicit);
+                continue;
+            }
+            const value = explicit !== undefined ? explicit : first && rootDefault !== undefined ? rootDefault : defaultEntryPointId(built.id, el.id);
+            first = false;
+            stamp(el, value);
+        }
+    };
+    visit(flowElements, true);
+}
 /** Build the flowElements array for one scope, wiring all references within it. */
 function buildScope(ctx, nodes, flows) {
     const { m } = ctx;

package/dist/bpmn/typed-node.d.ts

@@ -104,7 +104,29 @@ export interface RegistryTypeSpec {
     eventDefinition: string | null;
     /** True when authoring needs a tenant read (a connection, a process, a queue). */
     requiresDiscovery: boolean;
+    /**
+     * The registry's `IsDynamic`: a type whose fields the canvas discovers at design time.
+     * The CLI's merged-body required-field check (`validateMergedBodyFields`) skips exactly
+     * these, so for a dynamic type `check`'s EMPTY_REQUIRED_FIELD is the only gate on a
+     * missing required input (measured on uip 1.205: `A2A.AgentExecution` validates with
+     * one absent); every other merged-body type has its fields read inside the payload.
+     */
+    isDynamic?: boolean;
     bindingPattern: string;
+    /**
+     * The registry's `Placements`: where the canvas offers the type, by placement name
+     * (`Activity`, `StartEvent`, `IntermediateEvent`, `EndEvent`, …), with the BPMN
+     * element and, for an event, its definition. Kept as data; it is NOT an
+     * authorability signal — `{}` is what the case manager's internal nodes carry, but
+     * also `BPMN.ScriptTask`, `Intsvc.TimerTrigger`, `Maestro.AcquireLock` and
+     * `Maestro.NotificationService` (measured on uip 1.205), all of them authored. The
+     * internal set is `CASE_RUNTIME_INTERNAL_TYPES` (typed-node.ts). Absent on a spec that
+     * predates the field.
+     */
+    placements?: Record<string, {
+        element: string | null;
+        eventDefinition: string | null;
+    }>;
 }
 /** Every extension type in the snapshot, sorted. */
 export declare function registryTypeNames(): string[];
@@ -127,6 +149,17 @@ export declare function registryTypeNames(): string[];
  * typo, or no `uip` to ask.
  */
 export declare function registryType(type: string, inline?: RegistryTypeSpec): RegistryTypeSpec;
+/**
+ * The types the case-management runtime writes for itself when it materializes a
+ * case plan into an executable process: scheduler state (`decisions`, the current
+ * execution state, lock and cycle bookkeeping) that only the platform produces. The
+ * canvas offers none of them, and `check` warns on an authored one
+ * (TYPE_RUNTIME_INTERNAL). The ledger (`bpmn-coverage.json`) records each as
+ * `out-of-scope` under `docs/BPMN_BUSINESS_RULES_PLAN.md`; a test pins the two lists
+ * to each other. Not derivable from the spec: `placements: {}` is shared with
+ * authored types (see {@link RegistryTypeSpec.placements}).
+ */
+export declare const CASE_RUNTIME_INTERNAL_TYPES: ReadonlySet<string>;
 /** True when the snapshot itself carries the type — no tenant needed to emit it. */
 export declare function isSnapshotType(type: string): boolean;
 /**
@@ -458,36 +491,4 @@ export declare function missingRequiredInputs(type: string, inputs?: Record<stri
  * agree with the CLI instead of guessing on either side of it.
  */
 context?: Record<string, unknown>, inline?: RegistryTypeSpec): string[];
-/**
- * Whether this type's required payload fields are UNSATISFIABLE on the wire.
- *
- * A platform defect, recorded here because the SDK cannot emit its way around it.
- * `RequiredFieldsRule` builds its required-name set from `InputFields` and then
- * fires when a name is absent from the serialized rows **by name**. Under
- * `mergedBody` and `splitInputsItemData` every payload field collapses into ONE row
- * — named `body` or `ItemData` — so a required input field is never present by
- * name and the rule fires however the node is filled in:
- *
- *     [error] [call] EMPTY_REQUIRED_FIELD: The field 'agentUrl' in node 'call' is
- *                    required but has no value.
- *
- * Note the registry's own `XmlTemplate` for `A2A.AgentExecution` emits exactly the
- * body-only shape that fails, which is the clearest statement that the two halves
- * of the platform disagree rather than that the SDK is writing the wrong thing.
- *
- * Whether a workaround exists is per-type and not derivable from the spec, so it is
- * not encoded here. Measured: `A2A.AgentExecution` accepts redundant sibling rows
- * alongside the merged body (`Valid`); `Maestro.SendMessageEvent` refuses them
- * outright — `does not support input payload "Reference"` as a row, `does not
- * support context input "Reference"` in context, and `ItemData`'s `target="body"`
- * is enforced — so for that type NO artifact satisfies both gates.
- *
- * Selects exactly `A2A.AgentExecution` and `Maestro.SendMessageEvent` today. The
- * three other types with required payload fields are `separateInputs`, whose rows
- * DO carry their own names, and are unaffected.
- *
- * @param type - The extension type.
- * @returns The required payload field names that cannot be expressed, or `[]`.
- */
-export declare function unsatisfiableRequiredInputs(type: string, inline?: RegistryTypeSpec): string[];
 export {};

package/dist/bpmn/typed-node.js

@@ -41,6 +41,25 @@ export function registryType(type, inline) {
     }
     return spec;
 }
+/**
+ * The types the case-management runtime writes for itself when it materializes a
+ * case plan into an executable process: scheduler state (`decisions`, the current
+ * execution state, lock and cycle bookkeeping) that only the platform produces. The
+ * canvas offers none of them, and `check` warns on an authored one
+ * (TYPE_RUNTIME_INTERNAL). The ledger (`bpmn-coverage.json`) records each as
+ * `out-of-scope` under `docs/BPMN_BUSINESS_RULES_PLAN.md`; a test pins the two lists
+ * to each other. Not derivable from the spec: `placements: {}` is shared with
+ * authored types (see {@link RegistryTypeSpec.placements}).
+ */
+export const CASE_RUNTIME_INTERNAL_TYPES = new Set([
+    'Maestro.CaseCycleCommit',
+    'Maestro.CaseCyclePrepare',
+    'Maestro.CaseManagerGuardrails',
+    'Maestro.CaseManagerPlaceholder',
+    'Maestro.CaseRulesEvaluator',
+    'Maestro.RetrieveCaseState',
+    'Maestro.UpdateCaseState',
+]);
 /** True when the snapshot itself carries the type — no tenant needed to emit it. */
 export function isSnapshotType(type) {
     return Object.hasOwn(REGISTRY.types, type);
@@ -726,40 +745,3 @@ context = {}, inline) {
         (f.default ?? '') === '')
         .map((f) => f.name);
 }
-/**
- * Whether this type's required payload fields are UNSATISFIABLE on the wire.
- *
- * A platform defect, recorded here because the SDK cannot emit its way around it.
- * `RequiredFieldsRule` builds its required-name set from `InputFields` and then
- * fires when a name is absent from the serialized rows **by name**. Under
- * `mergedBody` and `splitInputsItemData` every payload field collapses into ONE row
- * — named `body` or `ItemData` — so a required input field is never present by
- * name and the rule fires however the node is filled in:
- *
- *     [error] [call] EMPTY_REQUIRED_FIELD: The field 'agentUrl' in node 'call' is
- *                    required but has no value.
- *
- * Note the registry's own `XmlTemplate` for `A2A.AgentExecution` emits exactly the
- * body-only shape that fails, which is the clearest statement that the two halves
- * of the platform disagree rather than that the SDK is writing the wrong thing.
- *
- * Whether a workaround exists is per-type and not derivable from the spec, so it is
- * not encoded here. Measured: `A2A.AgentExecution` accepts redundant sibling rows
- * alongside the merged body (`Valid`); `Maestro.SendMessageEvent` refuses them
- * outright — `does not support input payload "Reference"` as a row, `does not
- * support context input "Reference"` in context, and `ItemData`'s `target="body"`
- * is enforced — so for that type NO artifact satisfies both gates.
- *
- * Selects exactly `A2A.AgentExecution` and `Maestro.SendMessageEvent` today. The
- * three other types with required payload fields are `separateInputs`, whose rows
- * DO carry their own names, and are unaffected.
- *
- * @param type - The extension type.
- * @returns The required payload field names that cannot be expressed, or `[]`.
- */
-export function unsatisfiableRequiredInputs(type, inline) {
-    const spec = registryType(type, inline);
-    if (spec.inputPattern !== 'mergedBody' && spec.inputPattern !== 'splitInputsItemData')
-        return [];
-    return spec.inputs.filter((f) => f.required).map((f) => f.name);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.39.0",
+  "version": "6.40.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "df5d45c8b0eb17d5a82da37146e5b8130be03fab"
+  "gitref": "416f96b5db0e4bbfd59f19f8bd548f138a4a6918"
 }