@uipath/maestro-builder-sdk 6.23.0 → 6.25.0

package/dist/core/actions.d.ts

@@ -106,291 +106,6 @@ export interface InOutField {
     required?: boolean;
 }
 export type FormField = ShownField | AskedField | InOutField;
-/**
- * Where the task is delivered. The four ids are the platform's own — including
- * the lowercase `'teams'`, which is how every deployed recipient spells
- * Microsoft Teams (the canvas's channel list, `hitl-types.ts`).
- */
-export type HitlChannel = 'Slack' | 'teams' | 'Email' | 'ActionCenter';
-/**
- * How the task is assigned, the platform's own vocabulary (canvas
- * `HITL_ASSIGNEE_TYPE`): `'user'` a single user, `'group'` all users of a
- * group, `'staticEmail'`/`'staticGroupName'` literal values instead of
- * directory picks, `'workload'`/`'roundRobin'` distribution over a group, and
- * `'custom'` an expression the engine evaluates (`value` holds it).
- */
-export type HitlAssigneeType = 'user' | 'group' | 'staticEmail' | 'staticGroupName' | 'workload' | 'roundRobin' | 'custom';
-/** A per-channel Integration Service connection (Slack / Teams delivery). */
-export interface HitlConnection {
-    /** The connection's display name. */
-    name?: string | null;
-    /** The connection key the engine resolves, e.g. `'Slack'` for the default. */
-    key: string;
-    /** Folder the connection lives in; `null` for tenant-level defaults. */
-    folderPath?: string | null;
-}
-/**
- * Who gets the task and over which channels. Omit the whole object for the
- * definition's default (Email + Action Center, assigned to a group) — which is
- * what 203 of 233 deployed v1 human tasks carry, and what this SDK has always
- * emitted.
- *
- * ```ts
- * hitl({
- *   recipient: {
- *     channels: ['Email', 'ActionCenter'],
- *     assignee: { type: 'user', value: 'reviewer@acme.test' },
- *   },
- *   …
- * })
- * ```
- */
-export interface HitlRecipient {
-    /** Delivery channels. Defaults to the emitted definition's own default set. */
-    channels?: HitlChannel[];
-    /** Who the task is assigned to. */
-    assignee: {
-        type: HitlAssigneeType;
-        /**
-         * The user email / group name / expression, per `type`. The engine lowers
-         * this to its `{ Value, Type }` recipient contract; without one the task
-         * falls back to the tenant's assignment default.
-         */
-        value?: string;
-        /** Display name the designer shows next to the pick. Cosmetic. */
-        displayName?: string;
-    };
-    /**
-     * Per-channel connections, keyed by channel id (`Slack` / `teams`). Only the
-     * connector-backed channels take one; Email and Action Center do not.
-     */
-    connections?: Partial<Record<'Slack' | 'teams', HitlConnection>>;
-}
-/**
- * The Document Validation task's subject — `variant: 'document-validation'`
- * only. The reviewer gets the platform's validation station (or a custom app
- * with a Validation Control) over a document and its extraction result.
- */
-export interface DocValidationInputs {
-    /**
-     * The extraction result to validate — bind the `ExtractionResult` output of
-     * an upstream Extract step, e.g. `out('extract', 'ExtractionResult')`.
-     * Required: the station has nothing to validate without it.
-     */
-    extractionResult: Expr | string;
-    /** Storage bucket id holding the document. */
-    storageBucket?: string;
-    /** The document's id within the bucket. */
-    documentId?: string;
-    /**
-     * `'standard'` (default) for the native validation station, `'custom'` for a
-     * custom app with a Validation Control — which then requires `taxonomy`.
-     */
-    render?: 'standard' | 'custom';
-    /** The taxonomy the custom app validates against. Required when `render: 'custom'`. */
-    taxonomy?: Expr | string;
-}
-/**
- * One completion button. `action: 'End'` marks an outcome that ENDS the process
- * rather than continuing (the platform's own two-value vocabulary — anything
- * that is not exactly `'End'` reads as continue).
- *
- * `id` is the outcome's wire id — `schema.outcomes[].id`, and the `outcome-<id>`
- * port its edge leaves from. Leave it out and the id is a slug of `name`
- * (`'Needs info'` → `needs-info`). Set it only to keep an id a flow already
- * has, as decompile does for a task the designer drew
- * (`{ name: 'Reject', id: 'outcome-1778015958049' }`): merge keeps the
- * original node, so its edges must use that node's ids.
- *
- * @remarks
- * A bare string is shorthand for `{ name }`.
- */
-export type Outcome = string | {
-    name: string;
-    action?: 'Continue' | 'End';
-    id?: string;
-};
-/**
- * WHICH human-task node type to emit. The platform ships three spellings of the
- * same node; two of them resolve on this tenant and are what this option picks.
- *
- * @remarks
- * - **omitted** — `uipath.human-in-the-loop`, the original node, which chooses
- *   the form kind with `inputs.type: 'quick'`. This is the default and it does
- *   not change: it is where the platform's own versioning continues, and 319 of
- *   the corpus's human tasks are on it.
- * - **`'quick-form'`** — `uipath.human-in-the-loop.quick-form`. Same inline form,
- *   but the node TYPE is the "quick" choice, so no `inputs.type` is written
- *   (165 of its 175 deployed instances omit it). Everything you author is
- *   identical; pick it when something downstream keys on the literal type
- *   string, which flow-v1's own task checkers do.
- * - **`'action-app'`** — `uipath.human-in-the-loop.coded-action-app`. The form is
- *   NOT in the flow: it belongs to a deployed Action App, named by `app`. You
- *   still declare `outcomes` (the flow routes on them); you must NOT declare
- *   `fields` (the app owns them) — `check` says so.
- *
- * - **`'document-validation'`** — `uipath.human-in-the-loop.document-validation`.
- *   A validation station over a document + extraction result, named by
- *   `document`. No `fields` (the station is the form); `outcomes` still route.
- *   The definition is BUNDLED from the workbench manifest — the tenant registry
- *   does not serve the family (same availability note as do-while).
- */
-export type HitlVariant = 'quick-form' | 'action-app' | 'document-validation';
-/**
- * A deployed Action App that supplies a human task's form — the `'action-app'`
- * variant's subject.
- *
- * @remarks
- * The names are the platform's own, from flow-v1's app picker: an app is closed
- * by `key` (its GUID) plus the `folderPath` it is deployed in, with `name` the
- * human-readable title. This SDK is offline and never calls the Apps API, so
- * what you write here is what you already know about the app.
- *
- * ```ts
- * hitl({
- *   variant: 'action-app',
- *   app: {
- *     name: 'Expense Review',
- *     key: 'c0ba97df-8a30-4fe0-b4b4-4611a631d77b',
- *     folderPath: 'Shared',
- *     inputs: { 'Expense Amount': out('fetchExpense', 'total') },
- *   },
- *   outcomes: ['Approve', 'Reject'],
- * })
- * ```
- */
-export interface AppRef {
-    /** The app's display title, e.g. `'Expense Review'`. */
-    name: string;
-    /** The app's key (a GUID) — how the platform resolves which app this is. */
-    key: string;
-    /** Fully-qualified folder the app is deployed in, e.g. `'Shared'`. */
-    folderPath: string;
-    /**
-     * The app's stable system name. `null` until the app's first deployment
-     * assigns one, which is why it is optional and why `null` is a legal value
-     * rather than something to omit.
-     */
-    appSystemName?: string | null;
-    /**
-     * What to send the app, keyed by the app's OWN input parameter names — so the
-     * keys are the app author's, spaces and all (`'Invoice Amount'`), not
-     * identifiers of ours. Values are references, e.g. `out('step', 'field')`.
-     *
-     * Emitted as `inputs.appInputBindings`, the map flow-v1's serializer turns
-     * into the task's `HitlTaskArguments`.
-     */
-    inputs?: Record<string, Expr | string>;
-}
-export interface HitlInputs {
-    /**
-     * Which human-task node type to emit. Omit it for today's default — see
-     * {@link HitlVariant}. Omitting it emits exactly what it always has.
-     */
-    variant?: HitlVariant;
-    /**
-     * The deployed Action App that owns this task's form. Required by — and only
-     * legal with — `variant: 'action-app'`.
-     */
-    app?: AppRef;
-    /** Task title the reviewer sees. Defaults to the step's label. */
-    title?: string;
-    /** Action Center priority. Defaults to `'Low'`. */
-    priority?: 'Low' | 'Medium' | 'High';
-    /**
-     * The form, as an array of field descriptors — `direction: 'input'` for a value
-     * the reviewer reads, `'output'` for one they fill in. An array (not a map)
-     * because the ids are yours and order is the order on the form.
-     *
-     * Required for the inline-form variants (the default and `'quick-form'`).
-     * FORBIDDEN with `variant: 'action-app'`, where the form belongs to the
-     * deployed app rather than to the flow — `check` says so both ways.
-     */
-    fields?: FormField[];
-    /**
-     * The completion buttons, e.g. `['Approve', 'Reject']`. At least one, or the
-     * reviewer has no way to complete the task and the flow waits forever. The
-     * first is the primary (default) one. Each outcome is its own exit,
-     * `outcome-<slug>`: the default node and `'quick-form'` never leave on
-     * `completed` once they have outcomes. On the default node MORE THAN ONE
-     * outcome routes per outcome: the first continues the main path and the rest
-     * are routed with `.stepToList('outcome-<slug>', …)`. With `'quick-form'`,
-     * {@link HitlInputs.outcomePorts | outcomePorts}`: false`, an explicit
-     * `{ version }` or one outcome, `.step()` continues EVERY outcome instead.
-     *
-     * Which one they pressed is also `out('<step>', 'Action')` — that is what the
-     * platform's own routing conditions compare against.
-     */
-    outcomes: Outcome[];
-    /** Who gets the task and how. Omit for the definition's default delivery. */
-    recipient?: HitlRecipient;
-    /** Action Center labels, comma-separated (the platform stores one string). */
-    labels?: string;
-    /**
-     * Whether the task ROUTES per outcome. Each outcome has its own exit either
-     * way (`outcome-<id>`, the name slugified: `'Approve'` → `outcome-approve`).
-     *
-     * `true`: the FIRST outcome continues the main path and the others are routed
-     * with `.stepToList('outcome-<id>', …)`, or the run stalls when the reviewer
-     * picks one. The default node with more than one outcome already does this,
-     * on its **1.1** definition unless a `{ version }` pins another; `'quick-form'`
-     * supports it on its one definition. `false`: EVERY outcome continues to the
-     * next step on its own edge — a task that routes the decision as DATA by
-     * reading `out('<step>', 'Action')`; `'quick-form'` does this by default.
-     * `'action-app'` and `'document-validation'` read their outcomes from the app
-     * and leave on their one `completed` exit, so `true` is refused there.
-     */
-    outcomePorts?: boolean;
-    /**
-     * Expose the task's runtime error as a bindable `out('<step>', 'error')`
-     * object (`{ code, message, detail, category, status }`). Selects the node's
-     * **1.2** definition — which also routes per outcome, so this implies
-     * {@link HitlInputs.outcomePorts | outcomePorts}. Default node only.
-     */
-    exposeError?: boolean;
-    /**
-     * The document to validate. Required by — and only legal with —
-     * `variant: 'document-validation'`.
-     */
-    document?: DocValidationInputs;
-}
-export interface SendMessageInputs {
-    /**
-     * The conversation to post into — from the conversation trigger
-     * (`out('start', 'conversationId')`) or a context read. Required.
-     */
-    conversationId: string | Expr;
-    /**
-     * The exchange (one user turn plus its answers) the message belongs to —
-     * `out('<waitStep>', 'conversationContext.latestExchangeId')`, or the
-     * trigger's exchange for the first answer. Required by the node's schema.
-     */
-    exchangeId: string | Expr;
-    /** What to say. Markdown — the node's only supported `mimeType`. Required. */
-    content: string | Expr;
-    /**
-     * Whether this message CLOSES the exchange. The platform's legacy default is
-     * to end it; pass `false` to keep the exchange open for another message.
-     */
-    endExchange?: boolean;
-}
-export interface WaitForMessageInputs {
-    /** The conversation to wait on. Required. */
-    conversationId: string | Expr;
-    /**
-     * How many past exchanges the returned context carries. 1–40 in the
-     * designer; the platform default is 20.
-     */
-    numExchanges?: number;
-}
-export interface ConversationContextInputs {
-    /** The conversation to read. Required. */
-    conversationId: string | Expr;
-    /**
-     * How many exchanges to return, 1–40. The platform default is 20.
-     */
-    exchangeLimit?: number;
-}
 /**
  * How a conversational agent gets its turn — the node's own
  * `conversationalAgentSettings` sub-object.
@@ -1737,10 +1452,6 @@ export interface ContextIndexRef {
  * whole body rather than an inputs payload.
  */
 export interface FlowActionSpecs {
-    /** The spec {@link hitl} builds. */
-    hitl: {
-        inputs: HitlInputs;
-    };
     /** The spec {@link rpaWorkflow} builds. */
     rpaWorkflow: {
         inputs: RpaWorkflowInputs;
@@ -1753,18 +1464,6 @@ export interface FlowActionSpecs {
     publishedFunction: {
         inputs: PublishedFunctionInputs;
     };
-    /** The spec {@link sendMessage} builds. */
-    sendMessage: {
-        inputs: SendMessageInputs;
-    };
-    /** The spec {@link waitForMessage} builds. */
-    waitForMessage: {
-        inputs: WaitForMessageInputs;
-    };
-    /** The spec {@link conversationContext} builds. */
-    conversationContext: {
-        inputs: ConversationContextInputs;
-    };
     /** The spec {@link createOutgoingCall} builds. */
     createOutgoingCall: {
         inputs: CreateOutgoingCallInputs;
@@ -1856,58 +1555,6 @@ export declare function builtinActionSpec<S extends object>(spec: S): S;
  * @returns The same spec, as a `FlowTrigger` instance.
  */
 export declare function builtinTriggerSpec<S extends object>(spec: S): S;
-/**
- * Declare a human task — a step that pauses for a person to read some values,
- * fill others in, and press one of the outcome buttons.
- *
- * @remarks
- * Read an answer with `out('review', '<fieldId>')`, and which button they pressed
- * with `out('review', 'Action')` — branch on that for per-outcome routing.
- *
- * ### Picking a node type with `variant`
- *
- * The example above emits `uipath.human-in-the-loop`, the original node, and
- * that stays the default. Two other spellings of the same human task exist
- * ({@link HitlVariant}), and `variant` is how you say which:
- *
- * ```ts
- * // Same inline form, the newer node type — no `inputs.type` is written.
- * hitl({ variant: 'quick-form', fields: […], outcomes: ['Approve', 'Reject'] })
- *
- * // The form lives in a DEPLOYED APP: no `fields`, but still your outcomes.
- * hitl({
- *   variant: 'action-app',
- *   app: { name: 'Expense Review', key: '<guid>', folderPath: 'Shared',
- *          inputs: { 'Expense Amount': out('fetchExpense', 'total') } },
- *   outcomes: ['Approve', 'Reject'],
- * })
- * ```
- *
- * What every variant shares: one `completed` port, and the same two outputs
- * (`output`, carrying the answers, and `status`, carrying the outcome name) —
- * all three definitions declare them identically, so downstream reads do not
- * change when you switch.
- *
- * @example
- * **Pause for a person to approve, then read their decision**
- * ```ts
- * .step('review', hitl({
- *   title: 'Review Expense',
- *   fields: [
- *     { id: 'amount',   type: 'number',  direction: 'input',  value: input('amount') },
- *     { id: 'approved', type: 'boolean', direction: 'output' },
- *     { id: 'comments', type: 'text',    direction: 'output' },
- *   ],
- *   outcomes: ['Approve', 'Reject'],
- * }))
- * .step('log', script({ code: 'return "Decision: " + $vars.review.output.approved;' }))
- * ```
- *
- * @param inputs - The form's fields, outcomes and recipient.
- * @returns An action spec for `.step(...)`.
- * @example example-eval/GallerySubmission.flow.ts
- */
-export declare function hitl(inputs: HitlInputs): ActionSpec;
 /**
  * Extract fields from a document with a published IxP project — the platform's
  * **Extract** node (`uipath.ixp.*`, service contract `IXP.Extraction`).
@@ -2068,57 +1715,6 @@ export declare function apiWorkflow(inputs: ApiWorkflowInputs): ActionSpec;
  * @returns An action spec to pass to `.step(...)`.
  */
 export declare function publishedFunction(inputs: PublishedFunctionInputs): ActionSpec;
-/**
- * Post an assistant message into a live conversation
- * (`uipath.conversational.send-message`).
- *
- * ```ts
- * .step('answer', sendMessage({
- *   conversationId: out('start', 'conversationId'),
- *   exchangeId: out('listen', 'conversationContext.latestExchangeId'),
- *   content: 'Your order ships tomorrow.',
- * }))
- * ```
- *
- * The message is Markdown (`text/markdown` is the node's only supported type)
- * and the role is always `assistant` — a flow speaks as the assistant.
- *
- * @param inputs - The conversation, the exchange, and what to say.
- * @returns An action spec to pass to `.step(...)`.
- */
-export declare function sendMessage(inputs: SendMessageInputs): ActionSpec;
-/**
- * PAUSE until the person sends their next message
- * (`uipath.conversational.wait-for-message`) — a catch event, like
- * `waitForEvent`, so the flow suspends rather than polling.
- *
- * ```ts
- * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
- * ```
- *
- * It resumes with the conversation context:
- * `out('listen', 'conversationContext.messages')` is the transcript and
- * `…conversationContext.latestExchangeId` is the turn to answer.
- *
- * @param inputs - The conversation to wait on, and how much history to return.
- * @returns An action spec to pass to `.step(...)`.
- */
-export declare function waitForMessage(inputs: WaitForMessageInputs): ActionSpec;
-/**
- * READ a conversation's transcript so far without waiting
- * (`uipath.conversational.get-conversation-context`) — the shape a
- * conversational agent takes as its turn context.
- *
- * ```ts
- * .step('history', conversationContext({
- *   conversationId: out('start', 'conversationId'), exchangeLimit: 10,
- * }))
- * ```
- *
- * @param inputs - The conversation to read, and how many exchanges to return.
- * @returns An action spec to pass to `.step(...)`.
- */
-export declare function conversationContext(inputs: ConversationContextInputs): ActionSpec;
 /**
  * Place an outgoing phone call
  * (`uipath.conversational.voice.create-outgoing-call`) and get back the

package/dist/core/actions.js

@@ -88,60 +88,6 @@ export function builtinActionSpec(spec) {
 export function builtinTriggerSpec(spec) {
     return new BuiltinTrigger(spec);
 }
-/**
- * Declare a human task — a step that pauses for a person to read some values,
- * fill others in, and press one of the outcome buttons.
- *
- * @remarks
- * Read an answer with `out('review', '<fieldId>')`, and which button they pressed
- * with `out('review', 'Action')` — branch on that for per-outcome routing.
- *
- * ### Picking a node type with `variant`
- *
- * The example above emits `uipath.human-in-the-loop`, the original node, and
- * that stays the default. Two other spellings of the same human task exist
- * ({@link HitlVariant}), and `variant` is how you say which:
- *
- * ```ts
- * // Same inline form, the newer node type — no `inputs.type` is written.
- * hitl({ variant: 'quick-form', fields: […], outcomes: ['Approve', 'Reject'] })
- *
- * // The form lives in a DEPLOYED APP: no `fields`, but still your outcomes.
- * hitl({
- *   variant: 'action-app',
- *   app: { name: 'Expense Review', key: '<guid>', folderPath: 'Shared',
- *          inputs: { 'Expense Amount': out('fetchExpense', 'total') } },
- *   outcomes: ['Approve', 'Reject'],
- * })
- * ```
- *
- * What every variant shares: one `completed` port, and the same two outputs
- * (`output`, carrying the answers, and `status`, carrying the outcome name) —
- * all three definitions declare them identically, so downstream reads do not
- * change when you switch.
- *
- * @example
- * **Pause for a person to approve, then read their decision**
- * ```ts
- * .step('review', hitl({
- *   title: 'Review Expense',
- *   fields: [
- *     { id: 'amount',   type: 'number',  direction: 'input',  value: input('amount') },
- *     { id: 'approved', type: 'boolean', direction: 'output' },
- *     { id: 'comments', type: 'text',    direction: 'output' },
- *   ],
- *   outcomes: ['Approve', 'Reject'],
- * }))
- * .step('log', script({ code: 'return "Decision: " + $vars.review.output.approved;' }))
- * ```
- *
- * @param inputs - The form's fields, outcomes and recipient.
- * @returns An action spec for `.step(...)`.
- * @example example-eval/GallerySubmission.flow.ts
- */
-export function hitl(inputs) {
-    return builtinActionSpec({ kind: 'hitl', inputs });
-}
 /**
  * Extract fields from a document with a published IxP project — the platform's
  * **Extract** node (`uipath.ixp.*`, service contract `IXP.Extraction`).
@@ -310,63 +256,6 @@ export function apiWorkflow(inputs) {
 export function publishedFunction(inputs) {
     return builtinActionSpec({ kind: 'publishedFunction', inputs });
 }
-/**
- * Post an assistant message into a live conversation
- * (`uipath.conversational.send-message`).
- *
- * ```ts
- * .step('answer', sendMessage({
- *   conversationId: out('start', 'conversationId'),
- *   exchangeId: out('listen', 'conversationContext.latestExchangeId'),
- *   content: 'Your order ships tomorrow.',
- * }))
- * ```
- *
- * The message is Markdown (`text/markdown` is the node's only supported type)
- * and the role is always `assistant` — a flow speaks as the assistant.
- *
- * @param inputs - The conversation, the exchange, and what to say.
- * @returns An action spec to pass to `.step(...)`.
- */
-export function sendMessage(inputs) {
-    return builtinActionSpec({ kind: 'sendMessage', inputs });
-}
-/**
- * PAUSE until the person sends their next message
- * (`uipath.conversational.wait-for-message`) — a catch event, like
- * `waitForEvent`, so the flow suspends rather than polling.
- *
- * ```ts
- * .step('listen', waitForMessage({ conversationId: out('start', 'conversationId') }))
- * ```
- *
- * It resumes with the conversation context:
- * `out('listen', 'conversationContext.messages')` is the transcript and
- * `…conversationContext.latestExchangeId` is the turn to answer.
- *
- * @param inputs - The conversation to wait on, and how much history to return.
- * @returns An action spec to pass to `.step(...)`.
- */
-export function waitForMessage(inputs) {
-    return builtinActionSpec({ kind: 'waitForMessage', inputs });
-}
-/**
- * READ a conversation's transcript so far without waiting
- * (`uipath.conversational.get-conversation-context`) — the shape a
- * conversational agent takes as its turn context.
- *
- * ```ts
- * .step('history', conversationContext({
- *   conversationId: out('start', 'conversationId'), exchangeLimit: 10,
- * }))
- * ```
- *
- * @param inputs - The conversation to read, and how many exchanges to return.
- * @returns An action spec to pass to `.step(...)`.
- */
-export function conversationContext(inputs) {
-    return builtinActionSpec({ kind: 'conversationContext', inputs });
-}
 /**
  * Place an outgoing phone call
  * (`uipath.conversational.voice.create-outgoing-call`) and get back the

package/dist/core/form-field-type.d.ts

@@ -31,3 +31,19 @@ import type { FormFieldType } from './actions.js';
  * sdkFormFieldType('integer')  // undefined
  */
 export declare function sdkFormFieldType(wire: unknown): FormFieldType | undefined;
+/**
+ * Why a form-field type is refused: a product spelling of a type the SDK
+ * models (`"string"` is the platform's own name for text), or a type
+ * the SDK does not model at all. `unknownWhy` is the caller's reason for the
+ * second case; the default is a human task's.
+ */
+export declare function formFieldTypeWhy(type: unknown, unknownWhy?: string): string;
+/** The form-field types the SDK models. */
+export declare const FORM_FIELD_TYPES: string[];
+/** The `suggestion` for an unknown form-field type: the nearest valid one, else `type: 'text'`. */
+export declare function formFieldTypeHint(type: unknown): string;
+/** JSON-Schema type per form-field type, as flow-v1's form serializer maps them (quick-form escalations and human tasks). */
+export declare const FORM_FIELD_JSON_TYPE: Record<FormFieldType, {
+    type: string;
+    format?: string;
+}>;

package/dist/core/form-field-type.js

@@ -1,3 +1,4 @@
+import { nearestName } from './edit-distance.js';
 const PRODUCT_SPELLINGS = {
     text: 'text',
     string: 'text',
@@ -28,3 +29,35 @@ const PRODUCT_SPELLINGS = {
 export function sdkFormFieldType(wire) {
     return typeof wire === 'string' && Object.hasOwn(PRODUCT_SPELLINGS, wire) ? PRODUCT_SPELLINGS[wire] : undefined;
 }
+/**
+ * Why a form-field type is refused: a product spelling of a type the SDK
+ * models (`"string"` is the platform's own name for text), or a type
+ * the SDK does not model at all. `unknownWhy` is the caller's reason for the
+ * second case; the default is a human task's.
+ */
+export function formFieldTypeWhy(type, unknownWhy = `which the platform does not recognize. Older runtimes read it as text, newer ones reject `
+    + `the form`) {
+    const alias = sdkFormFieldType(type);
+    return alias !== undefined
+        ? `which is the platform's spelling of the SDK's '${alias}' — the SDK writes '${alias}'`
+        : unknownWhy;
+}
+/** Every FormFieldType, once; `Record<FormFieldType, …>` makes tsc refuse a missing or extra one. */
+const FORM_FIELD_TYPE_SET = { text: true, number: true, boolean: true, 'date-time': true };
+/** The form-field types the SDK models. */
+export const FORM_FIELD_TYPES = Object.keys(FORM_FIELD_TYPE_SET);
+/** The `suggestion` for an unknown form-field type: the nearest valid one, else `type: 'text'`. */
+export function formFieldTypeHint(type) {
+    const alias = sdkFormFieldType(type);
+    if (alias !== undefined)
+        return `type: '${alias}'`;
+    const nearest = nearestName(String(type), FORM_FIELD_TYPES);
+    return nearest !== undefined ? `type: '${nearest}'` : `type: 'text'`;
+}
+/** JSON-Schema type per form-field type, as flow-v1's form serializer maps them (quick-form escalations and human tasks). */
+export const FORM_FIELD_JSON_TYPE = {
+    text: { type: 'string' },
+    number: { type: 'number' },
+    boolean: { type: 'boolean' },
+    'date-time': { type: 'string', format: 'date-time' },
+};

package/dist/core/hitl-routing.d.ts

@@ -69,7 +69,21 @@
  * type, including the two app-backed variants, so that `serialize` and `check`
  * refuse them there with their own message rather than silently ignoring them.
  */
-import type { HitlInputs } from './actions.js';
+/**
+ * The fields of a human task's inputs the routing model reads — structural, so
+ * this module stays in `core/` while the authoring type (`HitlInputs`) belongs
+ * to the HITL family (nodes/hitl/flow/).
+ */
+export interface HitlRoutingInputs {
+    readonly variant?: unknown;
+    readonly outcomes?: ReadonlyArray<string | {
+        readonly name?: unknown;
+        readonly action?: unknown;
+        readonly id?: unknown;
+    }>;
+    readonly outcomePorts?: boolean;
+    readonly exposeError?: boolean;
+}
 /**
  * An outcome's stable id — the slug that names its `outcome-<id>` port.
  *
@@ -117,9 +131,9 @@ export type HitlExitModel = {
 export declare const OUTCOME_HANDLE_NODE_TYPES: ReadonlySet<string>;
 /** The same test on the authored side: no variant (the base node), or quick-form. */
 export declare function hitlDerivesOutcomeHandles(variant: unknown): boolean;
-export declare function hitlExitModel(inputs: HitlInputs | undefined, pinnedVersion?: string): HitlExitModel;
+export declare function hitlExitModel(inputs: HitlRoutingInputs | undefined, pinnedVersion?: string): HitlExitModel;
 /** Does this task route PER OUTCOME (primary continues, the rest are routed)? */
-export declare function hitlRoutesPerOutcome(inputs: HitlInputs | undefined, pinnedVersion?: string): boolean;
+export declare function hitlRoutesPerOutcome(inputs: HitlRoutingInputs | undefined, pinnedVersion?: string): boolean;
 type NodeLike = {
     id?: unknown;
     type?: unknown;

package/dist/core/stable-id.d.ts

@@ -59,3 +59,12 @@ export declare function fnv1aX4Uuid(seed: string): string;
  * Consumer: a Case entry point's `uniqueId` in `entry-points.json` (`case/compile-cli.ts`).
  */
 export declare function sha256Uuid(seed: string): string;
+/**
+ * A deterministic UUID for the form schema, derived from the flow and node ids.
+ *
+ * The platform uses `schemaId` to identify and cache a form, so it has to be
+ * stable across builds of the same flow — a random one would make every rebuild a
+ * different form and every emitted `.flow` a different file. Shaped as a v5 UUID
+ * (SHA-1 based, version + variant bits set) because that is what the field holds.
+ */
+export declare function schemaId(flowId: string, nodeId: string): string;