@uipath/maestro-builder-sdk 6.7.0 → 6.8.1

package/dist/api-index.md

@@ -406,8 +406,8 @@ could hand you spans for a version you do not have.
 | `ThrowOpts` | interface | `dist/bpmn/bpmn-sdk.d.ts:616-624` | Option shapes | Options for `.intermediateThrowEvent()` — a `message` to throw, or none. |
 | `TimerLike` | type | `dist/bpmn/bpmn-sdk.d.ts:37-38` | Supporting types | A timer as an ISO-8601 duration string (shorthand for `{ duration }`) or a full spec. |
 | `TimerSpec` | interface | `dist/bpmn/bpmn-sdk.d.ts:28-36` | Supporting types | ISO-8601 timer specification (one of duration / date / cycle). |
-| `TypedContextRow` | interface | `dist/bpmn/typed-node.d.ts:141-172` | Supporting types | One `uipath:context` input row, spelled out. |
+| `TypedContextRow` | interface | `dist/bpmn/typed-node.d.ts:152-183` | Supporting types | One `uipath:context` input row, spelled out. |
 | `TypeDesc` | type | `dist/core/expr.d.ts:323` | Supporting types |  |
-| `TypedOutputRow` | interface | `dist/bpmn/typed-node.d.ts:173-197` | Supporting types | 8 field(s) |
+| `TypedOutputRow` | interface | `dist/bpmn/typed-node.d.ts:184-208` | Supporting types | 8 field(s) |
 | `VarDirection` | type | `dist/bpmn/bpmn-sdk.d.ts:330-334` | Supporting types | How a variable is exposed: `'input'` (read-only entry input), `'output'` (a return value), or `'inputOutput'` (a mutable… |
 | `VarOpts` | interface | `dist/bpmn/bpmn-sdk.d.ts:1231-1255` | Option shapes | Options for `.var()` / `.input()` / `.output()`. |

package/dist/api-members.md

@@ -84,7 +84,7 @@ not find it either.
 | `body` | property | `JsonSchemaType` | `dist/case/case-sdk.d.ts:539` |
 | `body` | property | `PortArm` | `dist/flow-sdk.d.ts:305-306` |
 | `body` | property | `SwitchArm` | `dist/flow-sdk.d.ts:293` |
-| `body` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:162-167` |
+| `body` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:173-178` |
 | `boundaryEvent` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:1370-1377` |
 | `branch` | method | `StepList` | `dist/flow-sdk.d.ts:865-883` |
 | `branches` | property | `HttpInputsBase` | `dist/core/actions.d.ts:31-36` |
@@ -160,7 +160,7 @@ not find it either.
 | `conversationId` | property | `WaitForMessageInputs` | `dist/core/actions.d.ts:632-633` |
 | `count` | property | `BuiltSla` | `dist/case/case-sdk.d.ts:188` |
 | `count` | property | `SlaOpts` | `dist/case/case-sdk.d.ts:167-168` |
-| `custom` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:184-188` |
+| `custom` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:195-199` |
 | `cycle` | property | `TimerSpec` | `dist/bpmn/bpmn-sdk.d.ts:34-35` |
 | `date` | property | `TimerSpec` | `dist/bpmn/bpmn-sdk.d.ts:32-33` |
 | `declare` | method | `BindingsRegistry` | `dist/bpmn/bpmn-sdk.d.ts:1267-1274` |
@@ -200,7 +200,7 @@ not find it either.
 | `description` | method | `StageBuilder` | `dist/case/case-sdk.d.ts:970-976` |
 | `description` | method | `TaskBuilder` | `dist/case/case-sdk.d.ts:906-912` |
 | `description` | property | `TimerTriggerOpts` | `dist/case/case-sdk.d.ts:223` |
-| `description` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:189-190` |
+| `description` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:200-201` |
 | `description` | property | `VarDecl` | `dist/flow-sdk.d.ts:51-52` |
 | `description` | property | `VarSpec` | `dist/flow-sdk.d.ts:68-69` |
 | `detail` | property | `ErrorMappingRow` | `dist/bpmn/bpmn-sdk.d.ts:298-299` |
@@ -581,8 +581,8 @@ not find it either.
 | `name` | property | `TaskRef` | `dist/case/case-sdk.d.ts:410` |
 | `name` | property | `ThrowOpts` | `dist/bpmn/bpmn-sdk.d.ts:618-619` |
 | `name` | property | `TimerTriggerOpts` | `dist/case/case-sdk.d.ts:222` |
-| `name` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:156-157` |
-| `name` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:174-175` |
+| `name` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:167-168` |
+| `name` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:185-186` |
 | `name` | property | `VarDecl` | `dist/flow-sdk.d.ts:48` |
 | `name` | property | `VarOpts` | `dist/bpmn/bpmn-sdk.d.ts:1233-1234` |
 | `nodes` | property | `BuiltBpmn` | `dist/bpmn/bpmn-sdk.d.ts:411-412` |
@@ -704,7 +704,7 @@ not find it either.
 | `required` | property | `InOutField` | `dist/core/actions.d.ts:367-368` |
 | `required` | method | `StageBuilder` | `dist/case/case-sdk.d.ts:977-983` |
 | `required` | method | `TaskBuilder` | `dist/case/case-sdk.d.ts:884-890` |
-| `required` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:170-171` |
+| `required` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:181-182` |
 | `required` | property | `VarOpts` | `dist/bpmn/bpmn-sdk.d.ts:1253-1254` |
 | `requiresConnection` | property | `ConnectorMeta` | `dist/core/connectors.d.ts:64` |
 | `requiresFolderKey` | property | `ConnectorMeta` | `dist/core/connectors.d.ts:65` |
@@ -760,7 +760,7 @@ not find it either.
 | `schema` | method | `BpmnBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2105-2130` |
 | `schema` | property | `BpmnVarDecl` | `dist/bpmn/bpmn-sdk.d.ts:349-350` |
 | `schema` | property | `DynamicExtractInputs` | `dist/core/actions.d.ts:2262-2268` |
-| `schema` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:182-183` |
+| `schema` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:193-194` |
 | `schema` | property | `VarDecl` | `dist/flow-sdk.d.ts:55-56` |
 | `schema` | property | `VarOpts` | `dist/bpmn/bpmn-sdk.d.ts:1239-1252` |
 | `schema` | property | `VarSpec` | `dist/flow-sdk.d.ts:72-73` |
@@ -814,7 +814,7 @@ not find it either.
 | `source` | property | `GuardrailFieldReference` | `dist/core/actions.d.ts:1272` |
 | `source` | property | `InlineAgentInputs` | `dist/core/actions.d.ts:1464-1473` |
 | `source` | property | `TaskOutputBinding` | `dist/case/case-sdk.d.ts:496-497` |
-| `source` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:180-181` |
+| `source` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:191-192` |
 | `source` | property | `VoiceAgentInputs` | `dist/core/actions.d.ts:777-782` |
 | `sourceTrigger` | property | `CaseVarDecl` | `dist/case/case-sdk.d.ts:564-570` |
 | `splitPages` | property | `DocumentClassifyInputs` | `dist/core/actions.d.ts:2234-2235` |
@@ -855,8 +855,8 @@ not find it either.
 | `tags` | property | `ProcessMetadata` | `dist/bpmn/bpmn-sdk.d.ts:442-443` |
 | `target` | property | `BpmnFlow` | `dist/bpmn/bpmn-sdk.d.ts:323-324` |
 | `target` | property | `EscalationRecipient` | `dist/case/case-sdk.d.ts:122-123` |
-| `target` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:168-169` |
-| `target` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:191-196` |
+| `target` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:179-180` |
+| `target` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:202-207` |
 | `task` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:1423-1430` |
 | `task` | method | `StageBuilder` | `dist/case/case-sdk.d.ts:984-1003` |
 | `tasks` | property | `RuleOpts` | `dist/case/case-sdk.d.ts:40-55` |
@@ -910,8 +910,8 @@ not find it either.
 | `type` | property | `ShownField` | `dist/core/actions.d.ts:331` |
 | `type` | property | `TaskInputBinding` | `dist/case/case-sdk.d.ts:487` |
 | `type` | property | `TaskOutputBinding` | `dist/case/case-sdk.d.ts:498` |
-| `type` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:158-159` |
-| `type` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:176-177` |
+| `type` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:169-170` |
+| `type` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:187-188` |
 | `type` | property | `VarDecl` | `dist/flow-sdk.d.ts:49` |
 | `type` | property | `VarSpec` | `dist/flow-sdk.d.ts:66-67` |
 | `typeVersion` | property | `ActivityNodeOpts` | `dist/bpmn/bpmn-sdk.d.ts:1173-1188` |
@@ -939,13 +939,13 @@ not find it either.
 | `value` | property | `ShownField` | `dist/core/actions.d.ts:333-339` |
 | `value` | property | `SwitchArm` | `dist/flow-sdk.d.ts:291` |
 | `value` | property | `TaskInputBinding` | `dist/case/case-sdk.d.ts:485-486` |
-| `value` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:160-161` |
+| `value` | property | `TypedContextRow` | `dist/bpmn/typed-node.d.ts:171-172` |
 | `values` | property | `DataFabricCreateInputs` | `dist/core/actions.d.ts:2142-2147` |
 | `var` | method | `CaseBuilder` | `dist/case/case-sdk.d.ts:1199-1223` |
 | `var` | method | `FlowBuilder` | `dist/flow-sdk.d.ts:1329-1338` |
 | `var` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:1926-1934` |
 | `var` | property | `TaskOutputBinding` | `dist/case/case-sdk.d.ts:494-495` |
-| `var` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:178-179` |
+| `var` | property | `TypedOutputRow` | `dist/bpmn/typed-node.d.ts:189-190` |
 | `variables` | property | `BuiltBpmn` | `dist/bpmn/bpmn-sdk.d.ts:403-404` |
 | `variant` | property | `EscalationRef` | `dist/core/actions.d.ts:1868-1876` |
 | `variant` | property | `HitlInputs` | `dist/core/actions.d.ts:540-544` |

package/dist/bpmn/registry-fallback.d.ts

@@ -0,0 +1,22 @@
+import type { RegistryTypeSpec } from './typed-node.js';
+/**
+ * Shape a raw registry `ExtensionType` into the spec the emitter reads.
+ *
+ * Deliberately the same field-for-field mapping as `trim()` in
+ * `scripts/materialize-bpmn-registry.mjs`. They are pinned together by
+ * `bpmn-registry-fallback.test.ts`, which resolves a type the snapshot ALREADY
+ * carries through this path and asserts the result deep-equals the committed
+ * entry — so the two cannot drift for any type that matters without a red test.
+ */
+export declare function shapeExtensionType(spec: Record<string, any>): RegistryTypeSpec;
+/**
+ * Resolve an extension type the snapshot does not carry, from the registry.
+ *
+ * @param type - The extension type, e.g. `'Maestro.CasePlanScheduler'`.
+ * @returns Its emission spec, or `undefined` when the fallback is disabled, `uip`
+ * cannot answer, or the registry has no such type either — in which case the type
+ * really is wrong, not merely new.
+ */
+export declare function resolveFromRegistry(type: string): RegistryTypeSpec | undefined;
+/** Test seam: forget resolved specs, the pull, and the warning. */
+export declare function resetRegistryFallback(): void;

package/dist/bpmn/registry-fallback.js

@@ -0,0 +1,206 @@
+/**
+ * bpmn/registry-fallback — resolve an extension type the committed snapshot does
+ * not carry, by asking the registry through `uip`.
+ *
+ * `registry-types.json` is a snapshot, and a snapshot is always behind the
+ * platform by however long it has been since someone ran
+ * `scripts/materialize-bpmn-registry.mjs`. Until now a type outside it was simply
+ * unauthorable: `registryType()` threw, and the author had nowhere to go, because
+ * the SDK's whole discovery surface — the typed methods, `dist/api-members.md`,
+ * `registryTypeNames()` — is generated from that same snapshot. A type it has
+ * never heard of is invisible, not merely unsupported.
+ *
+ * That cost a full point on `skill-bpmn-contract-variant-wrappers` in the
+ * 2026-09-23 v1-vs-v2 run: the task wanted `Maestro.CasePlanScheduler`, the
+ * snapshot was stamped `uipVersion: 1.201.0-preview.122` against a `1.204.0-dev`
+ * CLI, the type was not in its 30, and the agent had no way to learn the name.
+ * The v1 arm ran `uip maestro bpmn registry search` and found it in one command.
+ *
+ * So: snapshot first, CLI second. The snapshot stays the fast, offline,
+ * reviewable default and nothing about a hit changes. A miss is no longer fatal
+ * — it costs one subprocess, warns loudly, and tells the author to refresh the
+ * snapshot so the next build is offline again.
+ *
+ * What this deliberately does NOT do:
+ *
+ *   - **Write the snapshot back.** A build that silently rewrites its own spec
+ *     source stops being reproducible, and `registry-types.json` exists so a spec
+ *     change is a reviewable diff. The warning points at the materializer instead.
+ *   - **Run for a type the snapshot already has.** Offline compilation of known
+ *     types is the common path and must not acquire a tenant dependency.
+ *   - **Retry forever.** One `registry get`; if that misses, one
+ *     `registry pull --force` and one more `get`. Both outcomes are remembered
+ *     for the process, so a file with ten unknown nodes costs at most two CLI
+ *     calls, not twenty.
+ */
+import { execFileSync } from 'node:child_process';
+/** The `uip` binary. Matches `scripts/materialize-bpmn-registry.mjs`. */
+const UIP = () => process.env.UIP ?? 'uip';
+/**
+ * Set `FLOW_SDK_BPMN_REGISTRY_FALLBACK=0` to keep the resolver snapshot-only.
+ *
+ * For hermetic builds and for tests that must not reach a tenant: with it off, a
+ * miss throws exactly as it did before this module existed.
+ */
+function fallbackEnabled() {
+    const v = process.env.FLOW_SDK_BPMN_REGISTRY_FALLBACK;
+    return v !== '0' && v !== 'false';
+}
+/** Resolved specs, and misses, for the life of the process. */
+const resolved = new Map();
+/** `registry pull --force` is tried at most once, however many types miss. */
+let pulled = false;
+/** One "you are resolving live" warning per process, not one per type. */
+let warnedLive = false;
+/**
+ * Run `uip` and return the `Data` of its JSON envelope, or `undefined`.
+ *
+ * Never throws: every failure mode here — no `uip` on PATH, not logged in, a
+ * `Result: Failure` envelope, a timeout — means the same thing to the caller
+ * (the type could not be resolved live) and the caller's error message is better
+ * than anything this could raise.
+ *
+ * `uip` prints a self-update failure to stderr before its real output, so stderr
+ * is ignored and stdout is parsed from its first `{`.
+ */
+function uip(args, timeoutMs) {
+    let out;
+    try {
+        out = execFileSync(UIP(), args, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: timeoutMs,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const start = out.indexOf('{');
+    if (start === -1)
+        return undefined;
+    try {
+        const parsed = JSON.parse(out.slice(start));
+        if (parsed.Result !== 'Success')
+            return undefined;
+        return parsed.Data;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The element-specific child a typed node needs beyond its extension payload.
+ *
+ * Same rule as the materializer's: a message event is only a message event
+ * because of its `<bpmn:messageEventDefinition />`, and nothing else in the spec
+ * records that.
+ */
+function eventDefinitionOf(template) {
+    const m = /<(bpmn:\w*EventDefinition)\s*\/?>/i.exec(typeof template === 'string' ? template : '');
+    return m ? m[1] : null;
+}
+/**
+ * Shape a raw registry `ExtensionType` into the spec the emitter reads.
+ *
+ * Deliberately the same field-for-field mapping as `trim()` in
+ * `scripts/materialize-bpmn-registry.mjs`. They are pinned together by
+ * `bpmn-registry-fallback.test.ts`, which resolves a type the snapshot ALREADY
+ * carries through this path and asserts the result deep-equals the committed
+ * entry — so the two cannot drift for any type that matters without a red test.
+ */
+export function shapeExtensionType(spec) {
+    const context = (spec.ContextFields ?? []).map((f) => ({
+        name: f.Name,
+        displayName: f.DisplayName ?? null,
+        type: f.Type ?? 'string',
+        required: Boolean(f.Required),
+        hidden: Boolean(f.Hidden),
+        binding: Boolean(f.Binding),
+        default: f.DefaultValue ?? null,
+        bindingInfo: f.BindingInfo
+            ? {
+                resource: f.BindingInfo.Resource ?? null,
+                propertyAttribute: f.BindingInfo.PropertyAttribute ?? null,
+            }
+            : null,
+    }));
+    const inputs = (spec.InputFields ?? []).map((f) => ({
+        name: f.Name,
+        displayName: f.DisplayName ?? null,
+        type: f.Type ?? 'string',
+        required: Boolean(f.Required),
+        hidden: Boolean(f.Hidden),
+        target: f.Target ?? null,
+        default: f.DefaultValue ?? null,
+    }));
+    // The output is FLAT on the payload — `OutputName`/`OutputType`/`OutputSource`/
+    // `UseRelativeSource`, not a nested `Output` object — and its type defaults to
+    // `jsonSchema`, not `json`. Both were guessed wrong first and caught by the
+    // drift pin in `bpmn-registry-fallback.test.ts`.
+    const output = spec.OutputName == null
+        ? null
+        : {
+            name: spec.OutputName,
+            type: spec.OutputType ?? 'jsonSchema',
+            source: spec.OutputSource ?? null,
+            relative: Boolean(spec.UseRelativeSource),
+        };
+    return {
+        element: spec.BpmnElement ?? null,
+        tag: spec.ExtensionTag ?? null,
+        inputPattern: spec.InputPattern ?? 'none',
+        inputName: spec.InputName ?? null,
+        inputTarget: spec.InputTarget ?? null,
+        context,
+        inputs,
+        output,
+        eventDefinition: eventDefinitionOf(spec.XmlTemplate),
+        requiresDiscovery: Boolean(spec.RequiresDiscovery),
+        bindingPattern: spec.BindingPattern ?? 'none',
+    };
+}
+/** `registry get <type>`, shaped, or `undefined` when the registry has no such type. */
+function get(type) {
+    const data = uip(['maestro', 'bpmn', 'registry', 'get', type, '--output', 'json'], 60_000);
+    const spec = data?.ExtensionType;
+    return spec ? shapeExtensionType(spec) : undefined;
+}
+/**
+ * Resolve an extension type the snapshot does not carry, from the registry.
+ *
+ * @param type - The extension type, e.g. `'Maestro.CasePlanScheduler'`.
+ * @returns Its emission spec, or `undefined` when the fallback is disabled, `uip`
+ * cannot answer, or the registry has no such type either — in which case the type
+ * really is wrong, not merely new.
+ */
+export function resolveFromRegistry(type) {
+    if (!fallbackEnabled())
+        return undefined;
+    const seen = resolved.get(type);
+    if (seen !== undefined)
+        return seen ?? undefined;
+    let spec = get(type);
+    // `registry get` answers from a local cache that does not refresh itself, so a
+    // type added since the last pull reads as absent. One forced pull per process,
+    // then one retry — beyond that the type is genuinely unknown.
+    if (!spec && !pulled) {
+        pulled = true;
+        uip(['maestro', 'bpmn', 'registry', 'pull', '--force', '--output', 'json'], 180_000);
+        spec = get(type);
+    }
+    resolved.set(type, spec ?? null);
+    if (spec && !warnedLive) {
+        warnedLive = true;
+        process.stderr.write(`  warn:  extension type "${type}" is not in the committed registry snapshot; resolved it live `
+            + `through \`uip maestro bpmn registry get\`. This build needed a tenant. Run \`node `
+            + `scripts/materialize-bpmn-registry.mjs\` and commit the result to make it offline again.\n`);
+    }
+    return spec;
+}
+/** Test seam: forget resolved specs, the pull, and the warning. */
+export function resetRegistryFallback() {
+    resolved.clear();
+    pulled = false;
+    warnedLive = false;
+}

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

@@ -98,12 +98,23 @@ export declare function registryTypeNames(): string[];
 /**
  * The spec for one extension type.
  *
+ * Snapshot first — that is the offline, reviewable, common path, and a hit costs
+ * a property read. On a MISS the registry is asked directly through `uip`
+ * ({@link resolveFromRegistry}), because a snapshot is always behind the platform
+ * by however long it has been since the last refresh, and a type outside it used
+ * to be unauthorable rather than merely unsupported: the typed methods,
+ * `dist/api-members.md` and {@link registryTypeNames} are all generated from this
+ * same file, so an author had no way even to learn the name. Set
+ * `FLOW_SDK_BPMN_REGISTRY_FALLBACK=0` to keep resolution snapshot-only.
+ *
  * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
  * @returns Its emission spec.
- * @throws If the type is not in the committed snapshot — which means either a
- * typo or a registry refresh the snapshot has not caught up with.
+ * @throws If the type is in neither the snapshot nor the registry — which means a
+ * typo, or no `uip` to ask.
  */
 export declare function registryType(type: string): RegistryTypeSpec;
+/** True when the snapshot itself carries the type — no tenant needed to emit it. */
+export declare function isSnapshotType(type: string): boolean;
 /**
  * Facts the platform enforces but the registry does not state.
  *

package/dist/bpmn/typed-node.js

@@ -1,4 +1,5 @@
 import { createRequire } from 'node:module';
+import { resolveFromRegistry } from './registry-fallback.js';
 const require = createRequire(import.meta.url);
 const REGISTRY = require('./registry-types.json');
 /** Every extension type in the snapshot, sorted. */
@@ -8,19 +9,35 @@ export function registryTypeNames() {
 /**
  * The spec for one extension type.
  *
+ * Snapshot first — that is the offline, reviewable, common path, and a hit costs
+ * a property read. On a MISS the registry is asked directly through `uip`
+ * ({@link resolveFromRegistry}), because a snapshot is always behind the platform
+ * by however long it has been since the last refresh, and a type outside it used
+ * to be unauthorable rather than merely unsupported: the typed methods,
+ * `dist/api-members.md` and {@link registryTypeNames} are all generated from this
+ * same file, so an author had no way even to learn the name. Set
+ * `FLOW_SDK_BPMN_REGISTRY_FALLBACK=0` to keep resolution snapshot-only.
+ *
  * @param type - The extension type, e.g. `'Intsvc.UnifiedHttpRequest'`.
  * @returns Its emission spec.
- * @throws If the type is not in the committed snapshot — which means either a
- * typo or a registry refresh the snapshot has not caught up with.
+ * @throws If the type is in neither the snapshot nor the registry — which means a
+ * typo, or no `uip` to ask.
  */
 export function registryType(type) {
-    const spec = REGISTRY.types[type];
+    const spec = REGISTRY.types[type] ?? resolveFromRegistry(type);
     if (!spec) {
-        throw new Error(`unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types; ` +
-            'refresh it with `node scripts/materialize-bpmn-registry.mjs` if the platform added one.');
+        throw new Error(`unknown extension type "${type}". The committed registry snapshot has ${REGISTRY.provenance.typeCount} types `
+            + `(uip ${REGISTRY.provenance.uipVersion}) and the registry could not be asked for this one either — `
+            + 'no `uip` on PATH, not logged in, or the type does not exist. '
+            + 'Check the spelling with `uip maestro bpmn registry search <term>`, then refresh the snapshot with '
+            + '`node scripts/materialize-bpmn-registry.mjs`.');
     }
     return spec;
 }
+/** True when the snapshot itself carries the type — no tenant needed to emit it. */
+export function isSnapshotType(type) {
+    return Object.hasOwn(REGISTRY.types, type);
+}
 /**
  * Facts the platform enforces but the registry does not state.
  *

package/dist/check.js

@@ -1250,7 +1250,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
             const declared = specs?.[named];
             const by = value.__lookup.by;
             if (declared && typeof by === 'string' && !declared.by.includes(by)) {
-                const { target, call } = lookupPhrases(named, declared);
+                const { target, call } = lookupPhrases(named, declared, spec);
                 diags.push({
                     level: 'error',
                     code: 'LOOKUP_UNKNOWN_MATCH_KEY',
@@ -1302,7 +1302,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
         const literal = value instanceof Expr ? value.value : value;
         if (typeof literal !== 'string')
             return;
-        const { target, call } = lookupPhrases(field, lookup);
+        const { target, call } = lookupPhrases(field, lookup, spec);
         diags.push({
             level: 'warning',
             code: 'LOOKUP_LITERAL_ID',
@@ -1439,13 +1439,32 @@ function checkConnectorContract(step, spec, opts, diags) {
         }
     }
 }
-/** The two phrases every lookup diagnostic needs: what the field sends, and how to resolve it. */
-function lookupPhrases(field, lookup) {
+/**
+ * The two phrases every lookup diagnostic needs: what the field sends, and how
+ * to resolve it.
+ *
+ * The `call` names BOTH authoring forms, and names which one the alias belongs
+ * to. Printing `lookup(<Descriptor>, 'entityName').byDisplayName('<value>')`
+ * alone — the old text — was a remedy with an unstated precondition: aliases
+ * are generated onto the descriptor, and `<Descriptor>` is a placeholder the
+ * reader has to fill from somewhere. An author holding the connector key and
+ * action instead (the form the library's Generic CRUD half is authored in, and
+ * the majority of its lookup fields) substitutes those for the placeholder,
+ * keeps the alias, and gets `lookup(...).byDisplayName is not a function`. Six
+ * flow-eval tasks did precisely that, each losing a check-edit-check round to
+ * a message that had told them to.
+ */
+function lookupPhrases(field, lookup, spec) {
     const target = `${lookup.objectName ?? lookup.path}.${lookup.value}`;
+    const by = lookup.by[0] ?? 'id';
     const alias = Object.keys(lookup.aliases)[0];
+    // The key/action form first: it needs no import, so it is the one line that
+    // is paste-ready from the message alone.
+    const generic = `lookup('${spec.key}', '${spec.action}', '${field}').by('${by}', '<value>')`;
     const call = alias
-        ? `lookup(<Descriptor>, '${field}').${alias}('<value>')`
-        : `lookup(<Descriptor>, '${field}').by('${lookup.by[0] ?? 'id'}', '<value>')`;
+        ? `${generic}\n  or \`lookup(D, '${field}').${alias}('<value>')\`, where D is the `
+            + `descriptor \`${prepareCommand(spec.key, spec.action)}\` generates — the aliases exist only there`
+        : generic;
     return { target, call };
 }
 /**
@@ -1502,7 +1521,7 @@ function runtimeLookupDiagnostic(step, spec, field, lookup, value) {
         || leaf.toLowerCase() === valueLeaf.toLowerCase()
         || (valueIsEmail && EMAIL_LEAF.test(leaf))))
         return undefined;
-    const { target, call } = lookupPhrases(field, lookup);
+    const { target, call } = lookupPhrases(field, lookup, spec);
     const searchesByEmail = lookup.by.some((b) => EMAIL_LEAF.test(b));
     const isEmail = !!leaf && EMAIL_LEAF.test(leaf) && !valueIsEmail && !searchesByEmail;
     const message = `Connector step "${step}": \`${field}\` is a lookup field bound to the runtime expression `

package/dist/core/actions.d.ts

@@ -1401,7 +1401,7 @@ export interface InlineAgentInputs {
      * argument after the reference PATH, `__`-joined. For a flow input the two
      * coincide (`$vars.notes` → `notes`); for a step output they do not, and a sidecar
      * still saying `{{input.claim}}` templates against a key that is not there — the
-     * literal text reaches the model. See `skill/references/inline-agent.md`
+     * literal text reaches the model. See the inline-agent node reference (`website/reference/inline-agent.md`)
      * §"The three prompt DIALECTS".
      *
      * If the agent has to answer in a shape the flow then reads, say so here. The
@@ -2611,7 +2611,7 @@ export declare function batchTransform(inputs: BatchTransformInputs): ActionSpec
  * with zero envelopes among them. The RUNTIME
  * accepts both, so only `uip maestro flow validate` sees a wrong one; the
  * emitter's exemption lives in `migrate.ts` (`UNWRAPPED_INPUTS`).
- * See `skill/references/ixp.md` §3.
+ * See the IxP node reference (`website/reference/ixp.md`) §3.
  *
  * @example
  * **Extract an invoice total and read it out of the nested result**
@@ -3130,9 +3130,9 @@ export declare function dynamicExtract(inputs: DynamicExtractInputs): ActionSpec
  * ```
  *
  * A connector operation's body fields come from the entity, so the library
- * cannot carry them: run `npx flow-sdk registry prepare uipath-uipath-dataservice
- * get-entity-record-by-id -f entityName=<Entity>` first (`uip maestro registry
- * prepare …` is the same command when you are driving through the UiPath CLI).
+ * cannot carry them: run `uip maestro registry prepare uipath-uipath-dataservice
+ * get-entity-record-by-id -f entityName=<Entity>` first (`npx flow-sdk registry
+ * prepare …` is the same command when invoking the package's own bin directly).
  * The routing table is in the `data-fabric.md` reference and the parent-field
  * loop in `connector-params.md` — cited by name rather than linked, because this
  * comment renders both into the flat corpus, where those files sit alongside

package/dist/core/actions.js

@@ -345,7 +345,7 @@ export function batchTransform(inputs) {
  * with zero envelopes among them. The RUNTIME
  * accepts both, so only `uip maestro flow validate` sees a wrong one; the
  * emitter's exemption lives in `migrate.ts` (`UNWRAPPED_INPUTS`).
- * See `skill/references/ixp.md` §3.
+ * See the IxP node reference (`website/reference/ixp.md`) §3.
  *
  * @example
  * **Extract an invoice total and read it out of the nested result**
@@ -917,9 +917,9 @@ export function dynamicExtract(inputs) {
  * ```
  *
  * A connector operation's body fields come from the entity, so the library
- * cannot carry them: run `npx flow-sdk registry prepare uipath-uipath-dataservice
- * get-entity-record-by-id -f entityName=<Entity>` first (`uip maestro registry
- * prepare …` is the same command when you are driving through the UiPath CLI).
+ * cannot carry them: run `uip maestro registry prepare uipath-uipath-dataservice
+ * get-entity-record-by-id -f entityName=<Entity>` first (`npx flow-sdk registry
+ * prepare …` is the same command when invoking the package's own bin directly).
  * The routing table is in the `data-fabric.md` reference and the parent-field
  * loop in `connector-params.md` — cited by name rather than linked, because this
  * comment renders both into the flat corpus, where those files sit alongside

package/dist/core/lookups.js

@@ -46,7 +46,53 @@ export function isLookupToken(v) {
 export function lookupKey(nodeType, field, by, value) {
     return JSON.stringify([nodeType, field, by, value]);
 }
-function makeBuilder(nodeType, field, spec) {
+/**
+ * An alias-shaped property: `byEmail`, `byDisplayName`, `byAccountId`.
+ *
+ * Narrow on purpose. The builder is handed to whatever inspects it next —
+ * `util.inspect`, a `then` probe on an accidental `await`, a spread — and a
+ * trap that answered for EVERY absent name would turn those into throws. Only
+ * a name the author could have meant as an alias is intercepted.
+ */
+const ALIAS_SHAPE = /^by[A-Z]/;
+/**
+ * Why `.byDisplayName()` is absent, in the terms of the form that was used.
+ *
+ * Aliases are generated from the descriptor's own `lookups` table, so the
+ * string form — which has no table to read — offers only `.by(name, value)`.
+ * That is a deliberate trade (see the overload's `@remarks`), but the author
+ * who trips it learns it as `lookup(...).byDisplayName is not a function`: a
+ * bare `TypeError` naming neither the field, the form, nor the way out. Six
+ * flow-eval tasks lost turns to exactly that message, every one of them having
+ * copied an alias out of a diagnostic or a descriptor's doc comment and pasted
+ * it onto the key/action form they happened to be holding.
+ */
+function missingAliasMessage(nodeType, field, alias, spec, generic) {
+    const head = `lookup(${nodeType}, '${field}'): \`.${alias}()\` does not exist. `;
+    if (!spec) {
+        // The remedy names the author's OWN key and action rather than a
+        // placeholder: a remedy with a hole in it is what produced this call.
+        const here = generic
+            ? `lookup('${generic.key}', '${generic.action}', '${field}')`
+            : `lookup(…, '${field}')`;
+        return head
+            + `Aliases are generated onto the descriptor, and this call has no descriptor `
+            + `to read them from, so only \`.by(name, value)\` exists here. Search by name:\n`
+            + `  ${here}.by('<searchable name>', <value>)\n`
+            + `\`check\` and \`${prepareCommand()}\` both print the names this field is `
+            + `searchable by. Or import the descriptor `
+            + (generic ? `\`${prepareCommand(generic.key, generic.action)}\` generates ` : '')
+            + `and call \`.${alias}(<value>)\` on that.`;
+    }
+    const aliases = Object.keys(spec.aliases);
+    return head
+        + (aliases.length
+            ? `Generated aliases for this field: ${aliases.map((a) => `\`.${a}()\``).join(', ')}. `
+            : `This field earns no alias — two of its names camelise to one, so both were dropped. `)
+        + `Every searchable name is reachable as `
+        + `\`.by(${spec.by.map((b) => `'${b}'`).join(' | ')}, <value>)\`.`;
+}
+function makeBuilder(nodeType, field, spec, generic) {
     const token = (by, value) => ({ __lookup: { nodeType, field, by, value } });
     const builder = {
         by(name, value) {
@@ -63,7 +109,19 @@ function makeBuilder(nodeType, field, spec) {
     for (const [alias, byName] of Object.entries(spec?.aliases ?? {})) {
         builder[alias] = (value) => token(byName, value);
     }
-    return builder;
+    // The throw is deferred to the CALL rather than raised on the property read,
+    // so the stack points at `.byDisplayName('Inbox')` — the line the author
+    // wrote — instead of at the property access the engine desugared it into.
+    return new Proxy(builder, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string' && !(prop in target) && ALIAS_SHAPE.test(prop)) {
+                return () => {
+                    throw new Error(missingAliasMessage(nodeType, field, prop, spec, generic));
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
 }
 export function lookup(a, b, c) {
     if (typeof a === 'string') {
@@ -71,7 +129,7 @@ export function lookup(a, b, c) {
             throw new Error("lookup(key, action, field) needs all three arguments; " +
                 "did you mean lookup(descriptor, field)?");
         }
-        return makeBuilder(`uipath.connector.${a}.${b}`, c);
+        return makeBuilder(`uipath.connector.${a}.${b}`, c, undefined, { key: a, action: b });
     }
     if (!('nodeType' in a) || a.nodeType === undefined) {
         const event = a;

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export { serialize as serializeCase } from './case/serialize.js';
 export { decompile as decompileCase, decompileWithDiagnostics as decompileCaseWithDiagnostics } from './case/decompile.js';
 export { bpmn } from './bpmn/bpmn-sdk.js';
 export type { BuiltBpmn, BpmnNode, BpmnFlow, BpmnVarDecl, EventDef, GatewayKind, EventKind, LoopSpec, RetrySpec, ActivityOpts, HttpOpts, } from './bpmn/bpmn-sdk.js';
-export { registryTypeNames, registryType } from './bpmn/typed-node.js';
+export { registryTypeNames, registryType, isSnapshotType } from './bpmn/typed-node.js';
 export type { RegistryTypeSpec, RegistryContextField, RegistryOutput } from './bpmn/typed-node.js';
 export { serialize as serializeBpmn } from './bpmn/serialize.js';
 export { check as checkBpmn } from './bpmn/check.js';

package/dist/index.js

@@ -28,8 +28,10 @@ export { decompile as decompileCase, decompileWithDiagnostics as decompileCaseWi
 // BPMN authoring API. `bpmn()` exposes only BPMN methods.
 export { bpmn } from './bpmn/bpmn-sdk.js';
 // The registry snapshot the typed nodes emit from — exposed so the coverage
-// ledger and its audit read the same source the emitter does.
-export { registryTypeNames, registryType } from './bpmn/typed-node.js';
+// ledger and its audit read the same source the emitter does. `isSnapshotType`
+// separates the two answers `registryType` now gives: a type the snapshot carries
+// emits offline, one it does not is resolved from the registry through `uip`.
+export { registryTypeNames, registryType, isSnapshotType } from './bpmn/typed-node.js';
 export { serialize as serializeBpmn } from './bpmn/serialize.js';
 export { check as checkBpmn } from './bpmn/check.js';
 export { check as checkCase } from './case/check.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.7.0",
+  "version": "6.8.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "598c3b8dd2e0f063680d817fee10b2a6dd21ec6a"
+  "gitref": "5ec4e9cb4aeac6a5297078cfd071d7c38784fed3"
 }