@uipath/maestro-builder-sdk 6.24.0 → 6.25.1

package/dist/nodes/hitl/flow/node-type.js

@@ -0,0 +1,601 @@
+/**
+ * The four human-task node types: the base `uipath.human-in-the-loop` (1.0, 1.1,
+ * 1.2) and its `.quick-form` (1.0, 1.1), `.coded-action-app` (1.0, 1.1) and
+ * `.document-validation` (1.0) variants. They share the `hitl` kind; `variant`
+ * picks one (`matches`), and the base node's inputs pick its version (`select`).
+ * Moved from serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, printed source,
+ * codes and messages unchanged.
+ *
+ * How a task LEAVES its node is `core/hitl-routing.ts`'s `hitlExitModel`, which
+ * the pipeline's flow-level routing rules read too: its tails here, its exits
+ * for `.stepSwitch`, and the edge rule (`hitlExitViolation`) serialize holds
+ * every edge out of an outcome-handle node to.
+ */
+import { Expr, toExpr } from '../../../core/expr.js';
+import { FORM_FIELD_JSON_TYPE, sdkFormFieldType } from '../../../core/form-field-type.js';
+import { isAnswerField } from '../../../core/hitl-answers.js';
+import { OUTCOME_HANDLE_NODE_TYPES, hitlExitModel, outcomeIdOf, outcomeSlug } from '../../../core/hitl-routing.js';
+import { jsonClone } from '../../../core/json-file.js';
+import { ownEntry } from '../../../core/own-entry.js';
+import { schemaId } from '../../../core/stable-id.js';
+import { wireExprBody } from '../../../core/wire-expr.js';
+import { checkHitl, checkHitlRead } from './check.js';
+const BASE = 'uipath.human-in-the-loop';
+const QUICK_FORM = 'uipath.human-in-the-loop.quick-form';
+const ACTION_APP = 'uipath.human-in-the-loop.coded-action-app';
+const DOC_VALIDATION = 'uipath.human-in-the-loop.document-validation';
+const VARIANTS = ['quick-form', 'action-app', 'document-validation'];
+/**
+ * A human task's inputs, and the outputs its form implies.
+ *
+ * Three things the author does not state and the platform needs:
+ *
+ * 1. **`type: 'quick'`** — the node type carries both an inline quick form and an
+ *    App-backed task, selected by this field. flow-v1's serializer defaults an
+ *    absent value to `quick`, but a reader cannot rely on that default, so the
+ *    serializer writes it (the same "the encoding is the serializer's job" call as
+ *    the scheduled trigger's `timerPreset`/`timerValue` split). **Only on the base
+ *    node type**: on either suffixed variant the node TYPE is the choice, so no
+ *    `inputs.type` is written — 165 of the 175 deployed `.quick-form` instances
+ *    omit it, neither variant's definition declares it, and flow-v1's serializer
+ *    DERIVES its `hitlType` from the node type rather than reading the field
+ *    (`hitl-serialization.ts:140-146`).
+ * 2. **`recipient`** — who gets the task. Emitted from the definition's own
+ *    `inputDefaults`: Email + Action Center, assigned to a group. That is what
+ *    203 of 233 deployed, debug-green v1 human tasks carry, unchanged.
+ * 3. **`schema.schemaId`** — the stable id the backend caches the form under
+ *    (229 of those 233 flows have one). Derived from the flow and node ids so the
+ *    emitted `.flow` is byte-stable across builds.
+ *
+ * And the outputs, which the DEFINITION cannot declare: a quick form's result keys
+ * are its own answer fields, so `uipath.human-in-the-loop@1.0` says only
+ * `output: { type: 'object' }` and the instance carries the shape — `properties`
+ * per answer field plus `Action` enumerated over the outcome names, and `status`
+ * (the platform's `=result.Action` projection) enumerated the same way. This is
+ * exactly what deployed v1 flows carry, and it is what lets `gen-tests` synthesize
+ * a replay fixture a downstream read can actually use.
+ */
+function hitlInputs(inputs, nodeType, ctx) {
+    const isApp = nodeType === ACTION_APP;
+    const fields = (inputs?.fields ?? []).map((f) => {
+        const base = {
+            id: f.id,
+            label: f.label ?? f.id,
+            type: f.type,
+            direction: f.direction,
+        };
+        if (f.direction === 'input') {
+            // The platform reads a field's `binding` as a variable PATH (`vars.…`),
+            // not as an expression — so the Expr's `$vars.x` form is rewritten here
+            // rather than asked of the author.
+            base.binding = bindingPath(f.value, ctx);
+        }
+        else if (f.direction === 'inOut') {
+            // Pre-filled AND editable: `binding` is the canonical pre-fill (the data
+            // contract flow-v1's serializer reads), and the WRITE target is the field
+            // id itself — deliberately decoupled from the binding, so no `variable`.
+            base.binding = bindingPath(f.value, ctx);
+            if (f.required)
+                base.required = true;
+        }
+        else {
+            // The answer's landing variable. The platform falls back to the field id
+            // when this is absent; naming it keeps the emitted flow explicit and
+            // matches what the designer writes.
+            base.variable = `vars.${f.id}`;
+            if (f.required)
+                base.required = true;
+        }
+        return base;
+    });
+    const outcomes = (inputs?.outcomes ?? []).map((o, i) => {
+        const name = typeof o === 'string' ? o : o?.name;
+        const action = typeof o === 'string' ? 'Continue' : (o?.action ?? 'Continue');
+        return { id: outcomeIdOf(o, i), name, type: 'string', isPrimary: i === 0, action };
+    });
+    const properties = {};
+    for (const f of inputs?.fields ?? []) {
+        // inOut fields land in the answers too — their reviewed value flows back.
+        if (!isAnswerField(f))
+            continue;
+        properties[f.id] = { ...ownEntry(FORM_FIELD_JSON_TYPE, String(f.type)) };
+    }
+    const names = outcomes.map((o) => o.name).filter((n) => typeof n === 'string');
+    if (names.length > 0) {
+        properties.Action = { type: 'string', enum: names, default: names[0] };
+    }
+    // The app reference and its input map, for the `action-app` variant only. The
+    // keys are flow-v1's own app-picker names (`name`/`key`/`folderPath`, plus the
+    // `appSystemName` that stays null until an app's first deployment); the
+    // bindings map the app's OWN parameter names to `=`-prefixed expressions,
+    // which is the form v1's serializer turns into `HitlTaskArguments`.
+    const app = inputs?.app;
+    const appInputBindings = {};
+    for (const [name, value] of Object.entries(app?.inputs ?? {})) {
+        appInputBindings[name] = appBindingExpr(value, ctx);
+    }
+    // The author's recipient when given; the definition's own default otherwise
+    // (unchanged — that default is what 203 of 233 deployed v1 tasks carry).
+    // `1.0`: every human-task type's first bundled definition, which is the one
+    // the pipeline read this default from before the port (`defByType`).
+    const defaultRecipient = jsonClone(ctx.definition(nodeType, '1.0')?.inputDefaults?.recipient ?? {});
+    const r = inputs?.recipient;
+    const recipient = r
+        ? {
+            channels: r.channels ?? (defaultRecipient.channels ?? []),
+            // Preserve the default's shape: quick-form's default carries an empty
+            // `connections` map, the others none — keep whichever, unless the
+            // author supplies their own.
+            ...(r.connections !== undefined
+                ? { connections: r.connections }
+                : 'connections' in defaultRecipient ? { connections: defaultRecipient.connections } : {}),
+            assignee: {
+                type: r.assignee.type,
+                ...(r.assignee.value !== undefined ? { value: r.assignee.value } : {}),
+                ...(r.assignee.displayName !== undefined ? { displayName: r.assignee.displayName } : {}),
+            },
+        }
+        : defaultRecipient;
+    // Document Validation carries the station's own inputs instead of a form; the
+    // expressions ride as `=js:` strings, EV-wrapped by the profile migration like
+    // any other input (the family is not in UNWRAPPED_INPUTS).
+    // The station's expression fields ride as PLAIN `$vars.…` strings — the
+    // property panel's own placeholder shape, and what the platform validator
+    // reads (it string-checks them directly; an ExpressionValue envelope fails
+    // with "extractionResult?.trim is not a function").
+    const docPath = (v) => {
+        const e = toExpr(v);
+        return e.literal ? String(e.value) : ctx.renameRefs(e.js);
+    };
+    const doc = inputs?.document;
+    const docvalInputs = nodeType === DOC_VALIDATION && doc
+        ? {
+            validationRenderType: doc.render ?? 'standard',
+            extractionResult: docPath(doc.extractionResult),
+            ...(doc.storageBucket !== undefined ? { storageBucket: doc.storageBucket } : {}),
+            ...(doc.documentId !== undefined ? { documentId: doc.documentId } : {}),
+            ...(doc.taxonomy !== undefined ? { taxonomy: docPath(doc.taxonomy) } : {}),
+        }
+        : {};
+    // 1.2's error output, verbatim from the bundled definition — the instance
+    // outputs replace the definition's (see the caller), so the slot is re-added
+    // here when the author asked for it.
+    const errorOutput = inputs?.exposeError
+        ? (ctx.definition(BASE, '1.2')?.outputDefinition)?.error
+        : undefined;
+    return {
+        inputs: {
+            // The base node type alone needs the discriminator — see the doc block.
+            ...(nodeType === BASE ? { type: 'quick' } : {}),
+            title: inputs?.title ?? ctx.step,
+            priority: inputs?.priority ?? 'Low',
+            ...(inputs?.labels !== undefined ? { labels: inputs.labels } : {}),
+            recipient,
+            ...docvalInputs,
+            ...((isApp || (nodeType === DOC_VALIDATION && doc?.render === 'custom')) && app
+                ? {
+                    app: {
+                        displayName: app.name,
+                        name: app.name,
+                        key: app.key,
+                        folderPath: app.folderPath,
+                        ...(app.appSystemName !== undefined ? { appSystemName: app.appSystemName } : {}),
+                    },
+                    ...(Object.keys(appInputBindings).length > 0 ? { appInputBindings } : {}),
+                }
+                : {}),
+            // The app variant still carries a `schema` — with NO fields (the app owns
+            // the form) but WITH the outcomes, because the flow's own routing and its
+            // `Action`/`status` outputs are derived from them. Both of flow-v1's
+            // app-task node references write exactly this shape.
+            schema: { schemaId: schemaId(ctx.flowId, ctx.nodeId), fields, outcomes },
+        },
+        outputs: {
+            output: {
+                type: 'object',
+                description: 'Task result data',
+                source: '=result',
+                var: 'output',
+                ...(Object.keys(properties).length > 0 ? { properties } : {}),
+            },
+            status: {
+                type: 'string',
+                description: 'Task completion status',
+                source: '=result.Action',
+                var: 'status',
+                ...(names.length > 0 ? { enum: names, default: names[0] } : {}),
+            },
+            ...(errorOutput !== undefined ? { error: jsonClone(errorOutput) } : {}),
+        },
+    };
+}
+/**
+ * One `appInputBindings` value: the expression sent to a deployed app's input.
+ *
+ * flow-v1 writes these `=`-prefixed and WITHOUT `js:` (`"=vars.<node>.output.<f>"`
+ * — `hitl-node-apptask.md`), and its serializer normalizes each to `=js:<body>`
+ * when it builds `HitlTaskArguments`. So the flow-level form is the bare
+ * `=`-prefixed path, which is what our own `$vars.` expressions become once the
+ * prefix is dropped. A plain string passes through as written.
+ */
+function appBindingExpr(value, ctx) {
+    if (!(value instanceof Expr))
+        return String(value ?? '');
+    const js = ctx.renameRefs(value.js).trim();
+    const path = js.startsWith('$vars.') ? js.slice('$vars.'.length) : js;
+    return path.startsWith('=') ? path : `=${path.startsWith('vars.') ? path : `vars.${path}`}`;
+}
+/**
+ * A shown field's `binding`: the platform resolves it as a path against the
+ * workflow's variables (`vars.<flowInput>`, `vars.<node>.output.<field>`), so the
+ * `$vars.` prefix our expressions carry is dropped. A computed expression cannot
+ * be a path — `check` rejects one (HITL_FIELD_VALUE_NOT_PATH) before we get here.
+ */
+function bindingPath(value, ctx) {
+    if (!(value instanceof Expr))
+        return String(value ?? '');
+    const js = ctx.renameRefs(value.js).trim();
+    const path = js.startsWith('$vars.') ? js.slice('$vars.'.length) : js;
+    // `vars.`-prefixed, which is what 526 of 528 bound fields in deployed v1 flows
+    // carry. flow-v1's serializer does prefix a bare identifier itself
+    // (`hitl-serialization.ts`), but only for `HitlTaskArguments` — the
+    // `__hitlInputBindings` the designer reads back stores the binding verbatim.
+    return path.startsWith('vars.') ? path : `vars.${path}`;
+}
+/**
+ * The exits `.stepSwitch` routes over, or why the task has none — read off the
+ * same model the task's tails come from.
+ */
+function hitlExits({ inputs }, pinnedVersion) {
+    const model = hitlExitModel(inputs, pinnedVersion);
+    if (model.shape === 'placeholder') {
+        // WHY it has no outcome exits decides what the author can do about it, so
+        // the caller gets the specific one rather than "ports are off".
+        if ((inputs?.outcomes ?? []).length === 0) {
+            return { reason: 'it declares no outcomes', suggestion: `outcomes: ['Approve', 'Reject']` };
+        }
+        return {
+            reason: `the '${inputs?.variant}' variant reads its outcomes from its app and leaves on its single 'completed' exit`,
+            suggestion: `Use .step() and switch on out('<step>', 'Action').`,
+        };
+    }
+    // A quick-form task and a pinned one continue every outcome under `.step()`,
+    // but their outcome handles are real, so `.stepSwitch` routes them. The
+    // other fan-out reasons leave nothing to route.
+    if (model.shape === 'every-outcome' && model.why !== 'quick-form' && model.why !== 'pinned') {
+        if (model.why === 'outcomePorts: false') {
+            return {
+                reason: 'outcomePorts: false continues every outcome to the next step',
+                suggestion: 'Drop `outcomePorts: false`.',
+            };
+        }
+        if (model.why === 'one outcome') {
+            return {
+                reason: 'a single outcome has a single exit, so there is nothing to route',
+                suggestion: 'Use .step() — the next step follows it unconditionally.',
+            };
+        }
+        return {
+            reason: 'every outcome ends the process, so no exit distinguishes them',
+            suggestion: 'Use .step().',
+        };
+    }
+    return model.exits.map((e) => ({
+        value: e.value,
+        port: e.port,
+        ...(e.endsProcess ? { endsProcess: true } : {}),
+    }));
+}
+/** The outcome ids in a human task's `inputs.schema.outcomes`. */
+function outcomeIdsOfNode(node) {
+    const outcomes = (node.inputs?.schema?.outcomes ?? []);
+    return Array.isArray(outcomes)
+        ? outcomes.map((o) => o?.id).filter((id) => typeof id === 'string' && id !== '')
+        : [];
+}
+function liftHitl(node, typeName, ctx) {
+    const n = node;
+    const i = n.inputs ?? {};
+    const schema = (i.schema ?? {});
+    const plain = (v) => {
+        const raw = ctx.sourceText(v);
+        return raw === undefined || raw === '' ? undefined : raw;
+    };
+    const variant = typeName === QUICK_FORM ? 'quick-form'
+        : typeName === ACTION_APP ? 'action-app'
+            : typeName === DOC_VALIDATION ? 'document-validation'
+                : undefined;
+    const expr = (js) => ctx.expr(`=js:${js}`);
+    // A field row's binding is a variable PATH (`vars.x`), not an expression —
+    // serialize rewrote the author's `$vars.x` on the way out, so put it back.
+    const bindingExpr = (v) => {
+        const raw = plain(v);
+        if (raw === undefined)
+            return undefined;
+        const js = wireExprBody(raw);
+        return expr(js.startsWith('vars.') ? `$${js}` : js);
+    };
+    const rows = (Array.isArray(schema.fields) ? schema.fields : []);
+    const fields = rows.map((f) => {
+        const id = String(f.id ?? '');
+        const direction = String(f.direction ?? 'output');
+        const value = direction === 'input' || direction === 'inOut' ? bindingExpr(f.binding) : undefined;
+        return {
+            id,
+            // serialize defaults a row's label to its id.
+            ...(typeof f.label === 'string' && f.label !== id ? { label: f.label } : {}),
+            // The product's own spelling (`"string"`, `"datetime"`, …) → the SDK's (#1143).
+            type: sdkFormFieldType(f.type ?? 'text') ?? String(f.type),
+            direction,
+            ...(value !== undefined ? { value } : {}),
+            ...(f.required === true ? { required: true } : {}),
+        };
+    });
+    const outcomeRows = (Array.isArray(schema.outcomes) ? schema.outcomes : []);
+    const outcomes = outcomeRows.map((o, idx) => {
+        const name = String(o.name ?? '');
+        // The file's id comes back only when serialize would not derive it from the
+        // name: a designer-drawn task's ids (`outcome-1778015958049`) are not slugs,
+        // and merge keeps the ORIGINAL node, so recompiled edges must use its ids
+        // (#1130). An SDK-written task's ids are slugs and stay implicit.
+        const id = typeof o.id === 'string' && o.id !== '' && o.id !== outcomeSlug(name, idx) ? o.id : undefined;
+        // A bare string is the shorthand; `action: 'End'` or a kept id needs the object.
+        return o.action === 'End' || id !== undefined
+            ? { name, ...(o.action === 'End' ? { action: 'End' } : {}), ...(id !== undefined ? { id } : {}) }
+            : name;
+    });
+    // Delivery: only an override comes back. The definition's own default is what
+    // serialize emits when the author wrote nothing.
+    const def = ctx.definition();
+    const defaultRecipient = JSON.stringify(def?.inputDefaults?.recipient ?? null);
+    const rec = i.recipient;
+    let recipient;
+    if (rec !== undefined && JSON.stringify(rec) !== defaultRecipient) {
+        const assignee = (rec.assignee ?? {});
+        recipient = {
+            ...(Array.isArray(rec.channels) ? { channels: rec.channels } : {}),
+            assignee: {
+                type: String(assignee.type ?? 'user'),
+                ...(typeof assignee.value === 'string' ? { value: assignee.value } : {}),
+                ...(typeof assignee.displayName === 'string' ? { displayName: assignee.displayName } : {}),
+            },
+        };
+    }
+    // The deployed app that owns the form (action-app, and a custom-render
+    // validation station). `app.inputs` is a VALUE map, keyed by the app's own
+    // parameter names, that lowers to a SIBLING key, `appInputBindings`, whose
+    // values are `=vars.…` paths (or literals). Not a type map, and not inside
+    // `app`: both are easy to assume and both round-trip wrong.
+    const app = i.app;
+    const bindings = (i.appInputBindings ?? {});
+    const appInputs = Object.keys(bindings).length === 0 ? undefined : Object.fromEntries(Object.entries(bindings).map(([k, v]) => {
+        const raw = String(v ?? '');
+        return [k, raw.startsWith('=') ? expr(wireExprBody(raw)) : raw];
+    }));
+    const liftedApp = app === undefined ? undefined : {
+        // `displayName` is serialize's echo of `name`; only `name` is authored.
+        name: String(app.name ?? ''),
+        key: String(app.key ?? ''),
+        ...(typeof app.folderPath === 'string' && app.folderPath !== '' ? { folderPath: app.folderPath } : {}),
+        ...(app.appSystemName === null ? { appSystemName: null }
+            : typeof app.appSystemName === 'string' ? { appSystemName: app.appSystemName } : {}),
+        ...(appInputs !== undefined ? { inputs: appInputs } : {}),
+    };
+    // The validation station's own inputs ride as PLAIN `$vars.…` paths. Anything
+    // but a `$vars.` reference stays the wire text verbatim.
+    const stationExpr = (v) => {
+        const raw = plain(v);
+        if (raw === undefined)
+            return undefined;
+        const js = wireExprBody(raw);
+        return js.startsWith('$vars.') ? expr(js) : raw;
+    };
+    const render = plain(i.validationRenderType);
+    const document = typeName !== DOC_VALIDATION ? undefined : {
+        extractionResult: stationExpr(i.extractionResult) ?? '',
+        ...(plain(i.storageBucket) !== undefined ? { storageBucket: plain(i.storageBucket) } : {}),
+        ...(plain(i.documentId) !== undefined ? { documentId: plain(i.documentId) } : {}),
+        // 'standard' is the definition's default.
+        ...(render !== undefined && render !== 'standard' ? { render } : {}),
+        ...(stationExpr(i.taxonomy) !== undefined ? { taxonomy: stationExpr(i.taxonomy) } : {}),
+    };
+    // On the base node the VERSION says it: 1.1 routes per outcome, 1.2 adds the
+    // error output (and implies the routing). Everywhere else — quick-form, a
+    // base task on 1.0 — the EDGES say it: outcomes that lead to different places
+    // are routed per outcome (`outcomePorts: true`, which a pinned 1.0 keeps at
+    // 1.0), and outcomes that all lead to one step are a fan-out, which the
+    // task's default recompiles to.
+    const version = String(n.typeVersion ?? '');
+    const versionRoutes = typeName === BASE && (version === '1.1' || version === '1.2');
+    const outPorts = ctx.outPorts();
+    const derivesHandles = OUTCOME_HANDLE_NODE_TYPES.has(typeName);
+    const outcomePorts = (typeName === BASE && version === '1.1')
+        || (derivesHandles && !versionRoutes && !ctx.convergedFanOut()
+            && outPorts.some((p) => p.startsWith('outcome-')));
+    // A lone `completed` edge on a task with several outcomes is the shape the
+    // designer stopped drawing: before flow-workbench #3512 (09-08) it was
+    // unconditioned, so every outcome continued down it; since then Studio Web and
+    // the converter remap it to the primary outcome only. Recompiling writes one
+    // `outcome-<id>` edge per outcome to the same step — the first meaning — so
+    // this is the one place decompile→compile is deliberately not exact. Say so.
+    const legacyCompleted = derivesHandles && outcomeIdsOfNode(n).length > 1 && outPorts.includes('completed');
+    // Both a converged fan-out and a legacy lone `completed` mean "every outcome
+    // continues to the next step". Say so in the source with `outcomePorts: false`
+    // rather than leaving it to the `{ version }` pin, so the intent survives an
+    // author dropping the pin.
+    const fanOut = !outcomePorts && derivesHandles && !versionRoutes && outcomeIdsOfNode(n).length > 1
+        && (legacyCompleted || ctx.convergedFanOut());
+    if (legacyCompleted) {
+        ctx.warn(`human task ${JSON.stringify(n.id)} leaves on the legacy 'completed' handle, which Studio Web no longer draws `
+            + `once a task has outcomes (it reads the edge as the primary outcome only). Recompiling emits one `
+            + `outcome-<id> edge per outcome to the same step, so every outcome continues — what the edge meant `
+            + `before flow-workbench #3512.`);
+    }
+    const title = plain(i.title);
+    const priority = plain(i.priority);
+    const lifted = {
+        ...(variant !== undefined ? { variant } : {}),
+        // serialize defaults the title to the step's own name.
+        ...(title !== undefined && title !== n.id ? { title } : {}),
+        ...(priority !== undefined && priority !== 'Low' ? { priority } : {}),
+        ...(plain(i.labels) !== undefined ? { labels: plain(i.labels) } : {}),
+        ...(recipient !== undefined ? { recipient } : {}),
+        ...(liftedApp !== undefined ? { app: liftedApp } : {}),
+        ...(document !== undefined ? { document } : {}),
+        // An app task and a validation station own no inline form; an empty array
+        // there is serialize's own, not the author's.
+        ...(fields.length || (variant !== 'action-app' && variant !== 'document-validation') ? { fields } : {}),
+        outcomes,
+        ...(outcomePorts ? { outcomePorts: true } : fanOut ? { outcomePorts: false } : {}),
+        ...(version === '1.2' ? { exposeError: true } : {}),
+    };
+    return { kind: 'hitl', inputs: lifted };
+}
+/** `{ k: v, … }` over the entries that are set, or '' when none is — the decompiler's `opts`. */
+function obj(entries, ctx) {
+    const parts = entries.filter(([, v]) => v !== undefined).map(([k, v]) => `${ctx.key(k)}: ${v}`);
+    return parts.length ? `{ ${parts.join(', ')} }` : '';
+}
+function printHitl({ inputs }, ctx) {
+    const h = inputs;
+    const val = (v) => (v instanceof Expr ? ctx.value(v) : ctx.string(v));
+    const recipient = h.recipient === undefined ? undefined : obj([
+        ['channels', h.recipient.channels ? `[${h.recipient.channels.map((c) => ctx.string(c)).join(', ')}]` : undefined],
+        ['assignee', obj([
+                ['type', ctx.string(h.recipient.assignee.type)],
+                ['value', h.recipient.assignee.value !== undefined ? ctx.string(h.recipient.assignee.value) : undefined],
+                ['displayName', h.recipient.assignee.displayName !== undefined ? ctx.string(h.recipient.assignee.displayName) : undefined],
+            ], ctx)],
+    ], ctx);
+    const app = h.app === undefined ? undefined : obj([
+        ['name', ctx.string(h.app.name)],
+        ['key', ctx.string(h.app.key)],
+        ['folderPath', h.app.folderPath !== undefined ? ctx.string(h.app.folderPath) : undefined],
+        ['appSystemName', h.app.appSystemName === null ? 'null'
+                : h.app.appSystemName !== undefined ? ctx.string(h.app.appSystemName) : undefined],
+        ['inputs', h.app.inputs !== undefined
+                ? obj(Object.entries(h.app.inputs).map(([k, v]) => [k, val(v)]), ctx) : undefined],
+    ], ctx);
+    const document = h.document === undefined ? undefined : obj([
+        ['extractionResult', val(h.document.extractionResult)],
+        ['storageBucket', h.document.storageBucket !== undefined ? ctx.string(h.document.storageBucket) : undefined],
+        ['documentId', h.document.documentId !== undefined ? ctx.string(h.document.documentId) : undefined],
+        ['render', h.document.render !== undefined ? ctx.string(h.document.render) : undefined],
+        ['taxonomy', h.document.taxonomy !== undefined ? val(h.document.taxonomy) : undefined],
+    ], ctx);
+    const fields = h.fields?.map((f) => obj([
+        ['id', ctx.string(f.id)],
+        ['label', f.label !== undefined ? ctx.string(f.label) : undefined],
+        ['type', ctx.string(f.type)],
+        ['direction', ctx.string(f.direction)],
+        ['value', f.value !== undefined ? ctx.value(f.value) : undefined],
+        ['required', f.required ? 'true' : undefined],
+    ], ctx));
+    const outcomes = h.outcomes.map((o) => (typeof o === 'string' ? ctx.string(o) : obj([
+        ['name', ctx.string(o.name)],
+        ['action', o.action !== undefined ? ctx.string(o.action) : undefined],
+        ['id', o.id !== undefined ? ctx.string(o.id) : undefined],
+    ], ctx)));
+    return {
+        factory: 'hitl',
+        options: [
+            ['variant', h.variant !== undefined ? ctx.string(h.variant) : undefined],
+            ['title', h.title !== undefined ? ctx.string(h.title) : undefined],
+            ['priority', h.priority !== undefined ? ctx.string(h.priority) : undefined],
+            ['labels', h.labels !== undefined ? ctx.string(h.labels) : undefined],
+            ['recipient', recipient],
+            ['app', app],
+            ['document', document],
+            ['fields', fields !== undefined ? `[${fields.join(', ')}]` : undefined],
+            ['outcomes', `[${outcomes.join(', ')}]`],
+            ['outcomePorts', h.outcomePorts === true ? 'true' : h.outcomePorts === false ? 'false' : undefined],
+            ['exposeError', h.exposeError ? 'true' : undefined],
+        ],
+    };
+}
+function hitlAt(typeName, version, factory) {
+    return {
+        kind: 'hitl', typeName, version, factory: 'hitl', definition: 'bundled',
+        rawNode: { factory },
+        serialize: ({ inputs }, ctx) => {
+            // How the task leaves its node — `hitlExitModel` (core/hitl-routing.ts)
+            // has the product rule and what `.step()` means after each shape. An
+            // explicit pin wins over the inferred 1.1 (`select`) — `flow validate`
+            // accepts `outcome-<id>` edges on base@1.0 — but not over `exposeError`,
+            // whose output only 1.2 declares.
+            const pinned = ctx.pinnedVersion;
+            const exitModel = hitlExitModel(inputs, pinned);
+            if (typeName !== BASE && inputs?.exposeError === true) {
+                throw new Error(`"${ctx.step}": exposeError needs the base human task's 1.2 definition, which adds the `
+                    + `error output — the '${inputs?.variant}' variant has no such version. Drop the variant or exposeError.`);
+            }
+            if (inputs?.outcomePorts === true && !OUTCOME_HANDLE_NODE_TYPES.has(typeName)) {
+                throw new Error(`"${ctx.step}": outcomePorts: true, but the '${inputs?.variant}' variant reads its outcomes `
+                    + `from its app and leaves on its single 'completed' exit. Route on out('${ctx.step}', 'Action') downstream.`);
+            }
+            if (inputs?.exposeError === true && pinned !== undefined && pinned !== '1.2') {
+                throw new Error(`"${ctx.step}": exposeError needs the task's 1.2 definition, but { version: '${pinned}' } pins it. `
+                    + `Drop the pin or match it.`);
+            }
+            const { inputs: nodeInputs, outputs } = hitlInputs(inputs, typeName, ctx);
+            // The definition's `outputDefinition` gives the two output SLOTS; the form
+            // gives their shape (see hitlInputs), so the instance's outputs replace it.
+            const contribution = { inputs: nodeInputs, outputs, replaceOutputs: true };
+            if (exitModel.shape === 'per-outcome') {
+                // The PRIMARY (first) outcome continues the main path; the author routes
+                // the rest with .stepToList('outcome-<id>', …) or as .stepSwitch arms.
+                return { ...contribution, port: exitModel.exits[0]?.port ?? `outcome-${outcomeSlug(undefined, 0)}` };
+            }
+            if (exitModel.shape === 'every-outcome') {
+                // Fan-out: every outcome continues to the next step, each on its own
+                // handle. End outcomes are marked, and `emit` ends them.
+                return { ...contribution, fanOut: exitModel.exits.map((e) => ({ port: e.port, ...(e.endsProcess ? { endsRun: true } : {}) })) };
+            }
+            // Every human-task definition declares one static source handle,
+            // `completed`: the real exit on an app-backed task and on one with no outcomes.
+            return { ...contribution, port: 'completed' };
+        },
+        deserialize: (node, ctx) => liftHitl(node, typeName, ctx),
+        print: printHitl,
+        check: ({ inputs }, ctx) => checkHitl(inputs, ctx),
+        // A human task's only expressions are the values its shown fields display.
+        // Without this a typo'd reference inside a form field would reach the
+        // deployed task as an unresolvable path and show the reviewer nothing.
+        expressions: ({ inputs }) => (inputs?.fields ?? [])
+            .filter((f) => f?.direction === 'input')
+            .map((f) => ({ value: f.value })),
+        output: ({ inputs }) => ({ kind: 'reader', read: (read, report) => checkHitlRead(read, inputs, report) }),
+        exits: hitlExits,
+        // The base node and quick-form draw one `outcome-<id>` handle per outcome,
+        // whatever the version; their definitions declare only `completed`.
+        derivesPort: ({ inputs }, port) => OUTCOME_HANDLE_NODE_TYPES.has(typeName)
+            && (inputs?.outcomes ?? []).some((o, i) => port === `outcome-${outcomeIdOf(o, i)}`),
+    };
+}
+function hitlType(typeName, versions, factory, variant) {
+    return {
+        kind: 'hitl', typeName, factory: 'hitl', defaultVersion: '1.0',
+        versions: Object.fromEntries(versions.map((v) => [v, hitlAt(typeName, v, factory)])),
+        // The base node is the one an absent or UNKNOWN variant resolves to, as it
+        // always has: `check` reports the unknown one (HITL_VARIANT_UNKNOWN).
+        matches: ({ inputs }) => (variant === undefined
+            ? !VARIANTS.includes(inputs?.variant)
+            : inputs?.variant === variant),
+        // Only the BASE node has definition versions to select: `exposeError` picks
+        // 1.2 (which adds the `error` output), and a task that routes per outcome
+        // picks 1.1. A variant routes per outcome on the one definition it has.
+        // `select` runs only when the step is unpinned (a pin wins upstream), so it
+        // asks the routing model with no pin, while `exits` and `serialize` get it.
+        ...(variant === undefined ? {
+            select: ({ inputs }) => (inputs?.exposeError ? '1.2'
+                : hitlExitModel(inputs, undefined).shape === 'per-outcome' ? '1.1' : '1.0'),
+        } : {}),
+    };
+}
+export const hitlNodeTypes = [
+    hitlType(BASE, ['1.0', '1.1', '1.2'], 'hitl()', undefined),
+    hitlType(QUICK_FORM, ['1.0', '1.1'], "hitl({ variant: 'quick-form' })", 'quick-form'),
+    hitlType(ACTION_APP, ['1.0', '1.1'], "hitl({ variant: 'action-app' })", 'action-app'),
+    hitlType(DOC_VALIDATION, ['1.0'], "hitl({ variant: 'document-validation' })", 'document-validation'),
+];