@sonisoft/now-sdk-ext-core 6.6.3 → 6.8.0

package/dist/sn/workflow/WorkflowManager.js

@@ -1,11 +1,39 @@
+import { randomBytes } from "node:crypto";
 import { Logger } from "../../util/Logger.js";
 import { ServiceNowRequest } from "../../comm/http/ServiceNowRequest.js";
+import { SessionManager } from "../../comm/http/SessionManager.js";
 import { TableAPIRequest } from "../../comm/http/TableAPIRequest.js";
+import { FormRecordWriter } from "../../comm/http/FormRecordWriter.js";
+import { InvalidParameterException } from "../../exception/InvalidParameterException.js";
+import { WorkflowValidationError } from "../../exception/WorkflowValidationError.js";
+import { READ_ONLY } from "../../policy/PolicyTypes.js";
+import { VariableDefinitions } from "../variables/VariableDefinitions.js";
+import { WorkflowDiagramClient } from "./WorkflowDiagramClient.js";
+import { planFlowConversion } from "./WorkflowFlowConversion.js";
+import { generateFluentFlow } from "./WorkflowFluentGenerator.js";
+const SYS_ID = /^[0-9a-f]{32}$/i;
+const VERSION_FIELDS = [
+    'sys_id', 'workflow', 'name', 'table', 'description', 'published', 'active', 'checked_out', 'checked_out_by',
+    'checked_out_by.name', 'condition', 'condition_type', 'start', 'full_sequences', 'sys_created_on', 'sys_updated_on'
+].join(',');
+const CONDITION_FIELDS = [
+    'sys_id', 'activity', 'name', 'condition', 'order', 'else_flag', 'error', 'event', 'event_name',
+    'short_description', 'skip_during_generate'
+].join(',');
 /**
- * Manages ServiceNow workflow lifecycle operations including creating workflows,
- * versions, activities, transitions, conditions, and publishing.
- * Also provides a high-level orchestration method to create a complete workflow
- * from a single specification.
+ * Manages legacy ServiceNow workflows (the Workflow Editor's wf_* records).
+ *
+ * Two families of methods live here:
+ *
+ * - **Editor-parity methods** (`newWorkflow`, `checkout`, `addActivity`, `publish`, …)
+ *   drive the same server endpoints the Workflow Editor uses — its diagram processor for
+ *   structure and lifecycle, and the classic `wf_activity` form for activity
+ *   configuration — so checkout's deep copy, publish's validation and version swap, and
+ *   activity variables (`sys_variable_value`) all behave exactly as they do in the UI.
+ *   Editing methods require a draft checked out to the current user.
+ * - **Record methods** (`createWorkflow`, `createActivity`, …, `createCompleteWorkflow`)
+ *   insert wf_* records directly through the Table API. They predate the editor-parity
+ *   methods and are kept for compatibility.
  */
 export class WorkflowManager {
     static WF_WORKFLOW = 'wf_workflow';
@@ -13,14 +41,23 @@ export class WorkflowManager {
     static WF_ACTIVITY = 'wf_activity';
     static WF_TRANSITION = 'wf_transition';
     static WF_CONDITION = 'wf_condition';
+    /** The form view the Workflow Editor uses for activity dialogs. */
+    static ACTIVITY_VIEW = 'diagrammer';
     _logger = new Logger("WorkflowManager");
     _req;
     _tableAPI;
     _instance;
+    _diagram;
+    _forms;
+    _variables;
+    _currentUser;
     constructor(instance) {
         this._instance = instance;
         this._req = new ServiceNowRequest(instance);
         this._tableAPI = new TableAPIRequest(instance);
+        this._diagram = new WorkflowDiagramClient(instance);
+        this._forms = new FormRecordWriter(instance);
+        this._variables = new VariableDefinitions(instance);
     }
     /**
      * Create a new workflow record.
@@ -121,6 +158,9 @@ export class WorkflowManager {
             throw new Error('Workflow version sys_id is required');
         }
         this._logger.info(`Creating activity: ${options.name} for version ${options.workflowVersionSysId}`);
+        if (options.variables !== undefined) {
+            return await this.createActivityThroughForm(options);
+        }
         const body = {
             name: options.name,
             workflow_version: options.workflowVersionSysId
@@ -235,7 +275,11 @@ export class WorkflowManager {
         throw new Error(`Failed to create condition '${options.name}'. Status: ${response?.status ?? 'unknown'}`);
     }
     /**
-     * Publish a workflow version by setting published=true and the start activity.
+     * Set a workflow version's start activity and publish it.
+     *
+     * Publishes through the Workflow Editor's publish (without its validation prompt, as
+     * this method never validated), so the version swap, path computation and update-set
+     * capture match a publish from the editor. Use {@link publish} for validation.
      *
      * @param options Publish options including version sys_id and start activity sys_id
      * @throws Error if the API call fails
@@ -248,16 +292,26 @@ export class WorkflowManager {
             throw new Error('Start activity sys_id is required');
         }
         this._logger.info(`Publishing workflow version ${options.versionSysId} with start activity ${options.startActivitySysId}`);
-        const body = {
-            published: true,
-            start: options.startActivitySysId
-        };
-        const response = await this._tableAPI.put(WorkflowManager.WF_WORKFLOW_VERSION, options.versionSysId, body);
-        if (response && response.status === 200 && response.bodyObject?.result) {
-            this._logger.info(`Successfully published workflow version ${options.versionSysId}`);
-            return;
+        const response = await this._tableAPI.put(WorkflowManager.WF_WORKFLOW_VERSION, options.versionSysId, { start: options.startActivitySysId });
+        if (!(response && response.status === 200 && response.bodyObject?.result)) {
+            throw new Error(`Failed to publish workflow version ${options.versionSysId}. Status: ${response?.status ?? 'unknown'}`);
         }
-        throw new Error(`Failed to publish workflow version ${options.versionSysId}. Status: ${response?.status ?? 'unknown'}`);
+        let answered = false;
+        try {
+            answered = !!(await this._diagram.publish(options.versionSysId, false)).graph?.published;
+        }
+        catch (error) {
+            // The processor publishes, then fails to draw a diagram holding an activity with no
+            // type (which these record methods can create) and answers with an empty page.
+            this._logger.debug(`publish_novalidate gave no diagram for ${options.versionSysId}: ${error.message}`);
+        }
+        if (!answered) {
+            const version = await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `sys_id=${options.versionSysId}`, 'published', 1);
+            if (str(version[0]?.published) !== 'true') {
+                throw new Error(`Failed to publish workflow version ${options.versionSysId}: the instance did not publish it`);
+            }
+        }
+        this._logger.info(`Successfully published workflow version ${options.versionSysId}`);
     }
     /**
      * Create a complete workflow from a single specification.
@@ -318,7 +372,8 @@ export class WorkflowManager {
                 width: activitySpec.width,
                 height: activitySpec.height,
                 script: activitySpec.script,
-                vars: activitySpec.vars
+                vars: activitySpec.vars,
+                variables: activitySpec.variables
             });
             // Store by id if provided, and always by index
             if (activitySpec.id) {
@@ -384,5 +439,1378 @@ export class WorkflowManager {
             startActivity: startActivityKey
         };
     }
+    // ============================================================
+    // Reading workflows
+    // ============================================================
+    /**
+     * Find workflows, with the state of their published and checked-out versions.
+     */
+    async findWorkflows(options = {}) {
+        const parts = [];
+        if (options.name)
+            parts.push(`nameLIKE${queryValue(options.name, 'name')}`);
+        if (options.table)
+            parts.push(`table=${queryValue(options.table, 'table')}`);
+        if (options.query)
+            parts.push(options.query);
+        parts.push('ORDERBYname');
+        const limit = options.limit ?? 50;
+        const workflows = await this.read(WorkflowManager.WF_WORKFLOW, parts.join('^'), 'sys_id,name,table,description', limit);
+        return await this.summarize(workflows);
+    }
+    /**
+     * Resolve a workflow by name, wf_workflow sys_id, or the sys_id of any of its versions.
+     *
+     * @throws InvalidParameterException when nothing or more than one workflow matches
+     */
+    async resolveWorkflow(nameOrSysId) {
+        const ref = (nameOrSysId ?? '').trim();
+        if (!ref)
+            throw new InvalidParameterException('A workflow name or sys_id is required');
+        let rows = [];
+        if (SYS_ID.test(ref)) {
+            rows = await this.read(WorkflowManager.WF_WORKFLOW, `sys_id=${ref}`, 'sys_id,name,table,description', 1);
+            if (!rows.length) {
+                const version = await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `sys_id=${ref}`, 'workflow', 1);
+                if (version.length) {
+                    rows = await this.read(WorkflowManager.WF_WORKFLOW, `sys_id=${str(version[0].workflow)}`, 'sys_id,name,table,description', 1);
+                }
+            }
+        }
+        if (!rows.length) {
+            rows = await this.read(WorkflowManager.WF_WORKFLOW, `name=${queryValue(ref, 'workflow name')}`, 'sys_id,name,table,description', 10);
+        }
+        if (!rows.length)
+            throw new InvalidParameterException(`No workflow found for '${ref}'`);
+        if (rows.length > 1) {
+            throw new InvalidParameterException(`'${ref}' matches ${rows.length} workflows; use a sys_id: ${rows.map(r => `${str(r.sys_id)} (${str(r.table)})`).join(', ')}`);
+        }
+        return (await this.summarize(rows))[0];
+    }
+    /**
+     * List a workflow's versions, newest first.
+     */
+    async getWorkflowVersions(workflowSysId) {
+        this.requireSysId(workflowSysId, 'workflowSysId');
+        const rows = await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `workflow=${workflowSysId}^ORDERBYDESCsys_created_on`, VERSION_FIELDS, 1000);
+        return rows.map(toVersionSummary);
+    }
+    /**
+     * Read everything that makes up a workflow version: activities with their variables
+     * and exits, transitions and stages.
+     */
+    async getWorkflowDefinition(versionSysId, options = {}) {
+        this.requireSysId(versionSysId, 'versionSysId');
+        const version = await this.readVersion(versionSysId);
+        const [activityRows, conditionRows, transitionRows, stageRows] = await Promise.all([
+            this.read(WorkflowManager.WF_ACTIVITY, `workflow_version=${versionSysId}^ORDERBYsys_created_on`, 'sys_id,name,activity_definition,activity_definition.name,x,y,width,height,stage,parent,input', 10000),
+            this.read(WorkflowManager.WF_CONDITION, `activity.workflow_version=${versionSysId}^ORDERBYorder`, CONDITION_FIELDS, 10000),
+            this.read(WorkflowManager.WF_TRANSITION, `from.workflow_version=${versionSysId}`, 'sys_id,from,to,condition', 10000),
+            this.read('wf_stage', `workflow_version=${versionSysId}^ORDERBYorder`, 'sys_id,name,value,order', 1000),
+        ]);
+        const conditions = conditionRows.map(toCondition);
+        const activities = activityRows.map(row => ({
+            sysId: str(row.sys_id),
+            name: str(row.name),
+            definitionSysId: str(row.activity_definition),
+            definitionName: str(row['activity_definition.name']),
+            x: optNum(row.x),
+            y: optNum(row.y),
+            width: optNum(row.width),
+            height: optNum(row.height),
+            stage: str(row.stage) || undefined,
+            parent: str(row.parent) || undefined,
+            input: str(row.input),
+            conditions: conditions.filter(c => c.activitySysId === str(row.sys_id)),
+        }));
+        if (options.includeVariables !== false && activities.length) {
+            const values = await this.readVariableValues(activities.map(a => a.sysId));
+            for (const activity of activities)
+                activity.variables = values.get(activity.sysId) ?? {};
+        }
+        const definition = {
+            workflowSysId: str(version.workflow),
+            versionSysId,
+            name: str(version.name),
+            table: str(version.table),
+            description: str(version.description),
+            condition: str(version.condition),
+            conditionType: str(version.condition_type),
+            published: str(version.published) === 'true',
+            active: str(version.active) === 'true',
+            checkedOut: str(version.checked_out),
+            checkedOutBy: str(version.checked_out_by),
+            start: str(version.start),
+            fullSequences: str(version.full_sequences).split(',').filter(Boolean),
+            activities,
+            transitions: transitionRows.map((row) => ({
+                sysId: str(row.sys_id), from: str(row.from), to: str(row.to), condition: str(row.condition),
+            })),
+            stages: stageRows.map((row) => ({
+                sysId: str(row.sys_id), name: str(row.name), value: str(row.value), order: num(row.order),
+            })),
+        };
+        if (options.includeStatus !== false) {
+            const graph = await this._diagram.get(versionSysId);
+            definition.status = {
+                readOnly: graph.readOnly,
+                canCheckout: graph.canCheckout,
+                canForceCheckout: graph.canForceCheckout,
+                canPublish: graph.canPublish,
+                statusDisplay: graph.statusDisplay,
+            };
+        }
+        return definition;
+    }
+    /**
+     * Read a version's diagram as the Workflow Editor sees it.
+     */
+    async getWorkflowGraph(versionSysId) {
+        this.requireSysId(versionSysId, 'versionSysId');
+        return await this._diagram.get(versionSysId);
+    }
+    /**
+     * List activity types — core activities and, unless excluded, Activity Designer ones.
+     */
+    async listActivityDefinitions(options = {}) {
+        const parts = [];
+        if (options.name)
+            parts.push(`nameLIKE${queryValue(options.name, 'name')}`);
+        if (options.category)
+            parts.push(`category=${queryValue(options.category, 'category')}`);
+        if (options.includeDesigner === false)
+            parts.push('sys_class_name=wf_activity_definition');
+        parts.push('ORDERBYname');
+        const rows = await this.read('wf_element_definition', parts.join('^'), 'sys_id,name,category,sys_class_name', options.limit ?? 500);
+        return rows.map(toDefinitionSummary);
+    }
+    /**
+     * Describe an activity type as the instance defines it: its own description, the
+     * variables its activities carry (types, defaults, choices, hints) or — for Activity
+     * Designer types — its inputs and outputs, and the exits a new activity starts with.
+     * With `includeScript`, also its implementation, which shows how each variable is used
+     * and which results drive the exits.
+     *
+     * @param nameOrSysId Definition sys_id or exact name (e.g. "Timer")
+     */
+    async getActivityDefinition(nameOrSysId, options = {}) {
+        const summary = await this.resolveActivityDefinition(nameOrSysId);
+        const designer = summary.sysClassName === 'wf_element_activity';
+        const ownFields = designer
+            ? `input_meta,output_meta${options.includeScript ? ',output_process_script' : ''}`
+            : (options.includeScript ? 'script' : '');
+        const [variables, defaults, base, own] = await Promise.all([
+            designer ? Promise.resolve([]) : this._variables.list(`var__m_${summary.sysId}`),
+            this.read('wf_condition_default', `activity_definition=${summary.sysId}^ORDERBYorder`, 'name,condition,order,else_flag,error,skip_during_generate', 200),
+            this.read('wf_element_definition', `sys_id=${summary.sysId}`, 'description,attributes', 1),
+            ownFields ? this.read(summary.sysClassName, `sys_id=${summary.sysId}`, ownFields, 1) : Promise.resolve([]),
+        ]);
+        const detail = {
+            ...summary,
+            description: str(base[0]?.description),
+            attributes: str(base[0]?.attributes),
+            variables,
+            defaultConditions: defaults.map((row) => ({
+                name: str(row.name),
+                condition: str(row.condition),
+                order: num(row.order),
+                elseFlag: str(row.else_flag) === 'true',
+                error: str(row.error) === 'true',
+                skipDuringGenerate: str(row.skip_during_generate) === 'true',
+            })),
+        };
+        const row = own[0];
+        if (designer && row) {
+            detail.inputs = designerFields(str(row.input_meta));
+            detail.outputs = designerFields(str(row.output_meta));
+            if (options.includeScript)
+                detail.script = str(row.output_process_script);
+        }
+        else if (row && options.includeScript) {
+            detail.script = str(row.script);
+        }
+        return detail;
+    }
+    /**
+     * Learn how an activity type is configured on this instance: samples activities of the
+     * type in published workflows and reports, per variable (or Activity Designer input),
+     * how often it is set and its most common values. Use it to follow the instance's own
+     * conventions — which fields approvals reference, how task values are templated, … .
+     *
+     * @param nameOrSysId Definition sys_id or exact name
+     */
+    async getActivityUsage(nameOrSysId, options = {}) {
+        const sampleSize = Math.min(Math.max(options.sampleSize ?? 100, 1), 500);
+        const perField = options.examplesPerField ?? 5;
+        const maxLength = options.maxValueLength ?? 300;
+        const definition = await this.getActivityDefinition(nameOrSysId);
+        const designer = definition.sysClassName === 'wf_element_activity';
+        const query = `activity_definition=${definition.sysId}^workflow_version.published=true`;
+        const activities = await this.read(WorkflowManager.WF_ACTIVITY, `${query}^ORDERBYDESCsys_updated_on`, designer ? 'sys_id,input' : 'sys_id', sampleSize);
+        const total = await this.count(WorkflowManager.WF_ACTIVITY, query);
+        const defs = new Map(definition.variables.map(v => [v.element, v]));
+        const tallies = new Map();
+        const add = (field, value) => {
+            if (value === '')
+                return;
+            const kept = value.length > maxLength ? `${value.slice(0, maxLength)}…` : value;
+            const counts = tallies.get(field) ?? new Map();
+            const entry = counts.get(kept) ?? { count: 0, isDefault: isDefaultValue(defs.get(field), value) };
+            entry.count++;
+            counts.set(kept, entry);
+            tallies.set(field, counts);
+        };
+        let order;
+        if (designer) {
+            order = (definition.inputs ?? []).map(i => i.name);
+            for (const activity of activities) {
+                let input = {};
+                try {
+                    input = JSON.parse(str(activity.input) || '{}');
+                }
+                catch {
+                    continue;
+                }
+                for (const [name, value] of Object.entries(input)) {
+                    if (!order.includes(name))
+                        order.push(name);
+                    add(name, typeof value === 'string' ? value : JSON.stringify(value));
+                }
+            }
+        }
+        else {
+            order = definition.variables.map(v => v.element);
+            const values = await this.readVariableValues(activities.map(a => str(a.sys_id)));
+            for (const byElement of values.values()) {
+                for (const [element, value] of Object.entries(byElement))
+                    add(element, value);
+            }
+        }
+        return {
+            definitionSysId: definition.sysId,
+            definitionName: definition.name,
+            publishedActivities: total,
+            sampled: activities.length,
+            fields: order.map(name => {
+                const counts = [...(tallies.get(name)?.entries() ?? [])].sort((a, b) => b[1].count - a[1].count);
+                return {
+                    name,
+                    setCount: counts.reduce((sum, [, e]) => sum + e.count, 0),
+                    examples: counts.slice(0, perField).map(([value, e]) => ({ value, count: e.count, isDefault: e.isDefault })),
+                };
+            }),
+        };
+    }
+    /**
+     * Export one workflow version as a complete, self-contained definition: the workflow
+     * and version properties, inputs, stages, every activity with its type, labelled
+     * variables (defaults marked) and exits, the transitions, the activity types it uses
+     * (described from the instance, including whether they pause the workflow), display
+     * names for referenced records, the subflows it calls, and what uses it.
+     *
+     * @param workflow Workflow name or sys_id, or a version sys_id (exported as is)
+     */
+    async exportWorkflow(workflow, options = {}) {
+        const versionSysId = await this.resolveVersionToRead(workflow, options.version ?? 'current');
+        const version = (await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `sys_id=${versionSysId}`, `${VERSION_FIELDS},order,run_multiple,after_business_rules,stage_field,on_cancel`, 1))[0];
+        const workflowSysId = str(version.workflow);
+        const definition = await this.getWorkflowDefinition(versionSysId, { includeStatus: false });
+        const typeIds = [...new Set(definition.activities.map(a => a.definitionSysId))];
+        // A session runs one transaction at a time; a wide fan-out only queues (or is refused with 202).
+        const details = await mapLimit(typeIds, 2, id => this.getActivityDefinition(id));
+        const waits = await mapLimit(details, 2, d => this.typeWaits(d));
+        const activityTypes = {};
+        details.forEach((d, i) => {
+            activityTypes[d.sysId] = {
+                sysId: d.sysId, name: d.name, category: d.category, sysClassName: d.sysClassName,
+                attributes: d.attributes, description: d.description, waits: waits[i],
+                ...(d.inputs ? { inputs: d.inputs, outputs: d.outputs } : {}),
+            };
+        });
+        const variableDefs = new Map(details.map(d => [d.sysId, new Map(d.variables.map(v => [v.element, v]))]));
+        const [wfRows, inputRows, subflowRows, catalogRows, parentRows] = await Promise.all([
+            this.read(WorkflowManager.WF_WORKFLOW, `sys_id=${workflowSysId}`, 'sys_id,name,table,description,sys_scope.scope', 1),
+            this.read('var_dictionary', `model_id=${workflowSysId}^ORDERBYorder`, 'element,column_label,internal_type,mandatory,default_value', 500),
+            this.read('wf_workflow_instance', `workflow_version=${versionSysId}`, 'activity,workflow,workflow.name', 1000),
+            this.read('sc_cat_item', `workflow=${workflowSysId}^ORDERBYname`, 'sys_id,name,active', 500),
+            this.read('wf_workflow_instance', `workflow=${workflowSysId}^workflow_version.published=true`, 'workflow_version,workflow_version.workflow,workflow_version.name', 500),
+        ]);
+        const subflows = new Map(subflowRows.map(r => [str(r.activity), { workflowSysId: str(r.workflow), name: str(r['workflow.name']) }]));
+        // Collect the sys_ids variables point at, by table, so they can be named once.
+        const wanted = new Map();
+        const want = (table, id) => {
+            if (!table || !SYS_ID.test(id))
+                return;
+            wanted.set(table, (wanted.get(table) ?? new Set()).add(id));
+        };
+        for (const activity of definition.activities) {
+            const defs = variableDefs.get(activity.definitionSysId);
+            for (const [element, value] of Object.entries(activity.variables ?? {})) {
+                const def = defs?.get(element);
+                if (def?.reference && (def.internalType === 'reference' || def.internalType === 'glide_list')) {
+                    for (const id of value.split(','))
+                        want(def.reference, id.trim());
+                }
+                for (const match of value.matchAll(/variables\.([0-9a-f]{32})/gi))
+                    want('item_option_new', match[1]);
+            }
+        }
+        const references = await this.displayNames(wanted);
+        const activities = definition.activities.map(activity => {
+            const defs = variableDefs.get(activity.definitionSysId);
+            const variables = [];
+            for (const [element, value] of Object.entries(activity.variables ?? {})) {
+                if (value === '')
+                    continue;
+                const def = defs?.get(element);
+                const exported = {
+                    element, label: def?.label ?? element, type: def?.internalType ?? '', value,
+                    isDefault: isDefaultValue(def, value),
+                };
+                const choice = def?.choices?.find(c => c.value === value);
+                const named = value.split(',').map(id => references[id.trim()]?.display).filter(Boolean);
+                if (choice)
+                    exported.display = choice.label;
+                else if (named.length)
+                    exported.display = named.join(', ');
+                variables.push(exported);
+            }
+            const result = {
+                sysId: activity.sysId,
+                name: activity.name,
+                typeSysId: activity.definitionSysId,
+                type: activity.definitionName,
+                x: activity.x,
+                y: activity.y,
+                stage: activity.stage,
+                parent: activity.parent,
+                variables,
+                exits: activity.conditions.map(c => ({
+                    sysId: c.sysId, name: c.name, condition: c.condition, order: c.order, elseFlag: c.elseFlag, error: c.error,
+                })),
+            };
+            if (activity.input && activity.input !== '{}')
+                result.input = parseJsonObject(activity.input);
+            const subflow = subflows.get(activity.sysId);
+            if (subflow)
+                result.subflow = subflow;
+            return result;
+        });
+        const wf = wfRows[0] ?? {};
+        return {
+            format: 'now-sdk-ext/legacy-workflow@1',
+            exportedAt: new Date().toISOString(),
+            workflow: {
+                sysId: workflowSysId, name: str(wf.name), table: str(wf.table), description: str(wf.description),
+                scope: str(wf['sys_scope.scope']),
+            },
+            version: {
+                sysId: versionSysId,
+                name: str(version.name),
+                published: str(version.published) === 'true',
+                active: str(version.active) === 'true',
+                checkedOut: str(version.checked_out),
+                checkedOutBy: str(version.checked_out_by),
+                condition: str(version.condition),
+                conditionType: str(version.condition_type),
+                order: num(version.order),
+                runMultiple: str(version.run_multiple) === 'true',
+                afterBusinessRules: str(version.after_business_rules) === 'true',
+                stageField: str(version.stage_field),
+                onCancel: str(version.on_cancel),
+                start: str(version.start),
+                fullSequences: definition.fullSequences,
+            },
+            inputs: inputRows.map(r => ({
+                name: str(r.element), label: str(r.column_label), type: str(r.internal_type),
+                mandatory: str(r.mandatory) === 'true', defaultValue: str(r.default_value),
+            })),
+            stages: definition.stages,
+            activityTypes,
+            activities,
+            transitions: definition.transitions.map(t => ({ sysId: t.sysId, from: t.from, exit: t.condition, to: t.to })),
+            references,
+            usedBy: {
+                catalogItems: catalogRows.map(r => ({ sysId: str(r.sys_id), name: str(r.name), active: str(r.active) === 'true' })),
+                parentWorkflows: parentRows.map(r => ({
+                    workflowSysId: str(r['workflow_version.workflow']), name: str(r['workflow_version.name']), versionSysId: str(r.workflow_version),
+                })),
+            },
+        };
+    }
+    /**
+     * Plan the move of a workflow version to Flow Designer and write a Fluent (now-sdk)
+     * skeleton for it. Read-only: it exports the version and works from the export (see
+     * {@link planFlowConversion} and {@link generateFluentFlow} to work from a saved export).
+     *
+     * @param workflow Workflow name or sys_id, or a version sys_id
+     */
+    async convertToFlow(workflow, options = {}) {
+        const data = await this.exportWorkflow(workflow, { version: options.version });
+        const plan = planFlowConversion(data);
+        return { export: data, plan, files: generateFluentFlow(plan, { directory: options.directory }) };
+    }
+    /**
+     * Run the Workflow Editor's validation ("Validate Workflow") without publishing.
+     */
+    async validateWorkflow(versionSysId) {
+        this.requireSysId(versionSysId, 'versionSysId');
+        // Rendering the report page is what runs the checks; the results are then
+        // readable as records.
+        const page = await this.request().get({
+            method: 'GET', path: '/validate_workflow.do', headers: null, body: null,
+            query: { sysparm_sys_id: versionSysId }, requires: READ_ONLY, responseFormat: 'text',
+        });
+        const html = typeof page.data === 'string' ? page.data : '';
+        if (!html.includes('id="wf_validation_summary_message"')) {
+            // Without the report page the checks did not run; the table may hold an earlier run.
+            throw new Error(`Could not run the validation for workflow version ${versionSysId} (status ${page.status ?? 'unknown'})`);
+        }
+        const summaryMatch = /id="wf_validation_summary_message"[^>]*>\s*<h4>([\s\S]*?)<\/h4>/.exec(html);
+        const summary = summaryMatch ? decodeEntities(summaryMatch[1]).replace(/\s+/g, ' ').trim() : '';
+        const rows = await this.read('v_wf_validation_report', `workflow_version=${versionSysId}`, 'type,level,message,details', 500);
+        const items = rows.map((row) => ({
+            type: str(row.type), level: str(row.level), message: str(row.message), details: str(row.details),
+        }));
+        if (!summary && !items.length) {
+            throw new Error(`Could not read the validation report for workflow version ${versionSysId}`);
+        }
+        return {
+            versionSysId,
+            summary,
+            valid: !items.some(i => i.level === 'Warn' || i.level === 'Critical'),
+            items,
+        };
+    }
+    // ============================================================
+    // Workflow lifecycle (Workflow Editor parity)
+    // ============================================================
+    /**
+     * Create a workflow the way the Workflow Editor's "New Workflow" does: a version with
+     * Begin and End activities joined by a transition, checked out to the current user.
+     *
+     * @throws InvalidParameterException when a workflow with this name already exists
+     */
+    async newWorkflow(options) {
+        if (!options?.name || options.name.trim().length === 0)
+            throw new InvalidParameterException('Workflow name is required');
+        if (!options.table || options.table.trim().length === 0)
+            throw new InvalidParameterException('Table name is required');
+        const existing = await this.read(WorkflowManager.WF_WORKFLOW, `name=${queryValue(options.name, 'workflow name')}`, 'sys_id', 1);
+        if (existing.length)
+            throw new InvalidParameterException(`A workflow named '${options.name}' already exists (${str(existing[0].sys_id)})`);
+        // Inserting a version without a parent workflow is what the editor does; the
+        // instance's "Workflow initialize" rule then creates the workflow, Begin, End,
+        // the Begin exit and the Begin → End transition.
+        const body = { ...(options.fields ?? {}), name: options.name, table: options.table };
+        if (options.description !== undefined)
+            body.description = options.description;
+        if (options.condition !== undefined)
+            body.condition = options.condition;
+        if (options.conditionType !== undefined)
+            body.condition_type = options.conditionType;
+        this._logger.info(`Creating workflow '${options.name}' on ${options.table}`);
+        const response = await this._tableAPI.post(WorkflowManager.WF_WORKFLOW_VERSION, {}, body);
+        const versionSysId = response?.bodyObject?.result?.sys_id;
+        if (!versionSysId)
+            throw new Error(`Failed to create workflow '${options.name}'. Status: ${response?.status ?? 'unknown'}`);
+        const version = await this.readVersion(versionSysId);
+        const transitions = await this.read(WorkflowManager.WF_TRANSITION, `from.workflow_version=${versionSysId}`, 'sys_id,from,to,condition', 10);
+        const begin = str(version.start);
+        const transition = transitions.find(t => str(t.from) === begin);
+        if (!begin || !transition) {
+            throw new Error(`Workflow '${options.name}' was created (version ${versionSysId}) but its Begin/End activities were not`);
+        }
+        return {
+            workflowSysId: str(version.workflow),
+            versionSysId,
+            beginActivitySysId: begin,
+            endActivitySysId: str(transition.to),
+            beginConditionSysId: str(transition.condition),
+            transitionSysId: str(transition.sys_id),
+        };
+    }
+    /**
+     * Check a workflow out for editing. Like the editor, this creates a draft version —
+     * a full copy of the published one — checked out to the current user. If the
+     * current user already has a draft, that draft is returned.
+     *
+     * @param workflow Workflow name, wf_workflow sys_id or a version sys_id
+     * @throws Error when another user has it checked out (unless `force`)
+     */
+    async checkout(workflow, options = {}) {
+        const summary = await this.resolveWorkflow(workflow);
+        const draft = summary.checkedOutVersion;
+        if (draft) {
+            if (draft.byCurrentUser) {
+                return { workflowSysId: summary.sysId, versionSysId: draft.sysId, alreadyCheckedOut: true };
+            }
+            if (!options.force) {
+                throw new Error(`Workflow '${summary.name}' is checked out by ${draft.checkedOutByName || draft.checkedOutBy} `
+                    + `(since ${draft.checkedOutOn}). Pass force to take over the checkout.`);
+            }
+            const graph = await this._diagram.forceCheckout(summary.publishedVersionSysId ?? draft.sysId);
+            if (graph.id === summary.publishedVersionSysId || graph.readOnly) {
+                throw new Error(`Workflow '${summary.name}' could not be checked out (${graph.statusDisplay || 'no draft was returned'})`);
+            }
+            this._logger.info(`Force-checked out workflow '${summary.name}' as version ${graph.id}`);
+            return { workflowSysId: summary.sysId, versionSysId: graph.id, alreadyCheckedOut: false };
+        }
+        if (!summary.publishedVersionSysId) {
+            throw new Error(`Workflow '${summary.name}' has no published version to check out`);
+        }
+        const graph = await this._diagram.checkout(summary.publishedVersionSysId, summary.name);
+        if (graph.id === summary.publishedVersionSysId || graph.readOnly) {
+            throw new Error(`Workflow '${summary.name}' could not be checked out (${graph.statusDisplay || 'no draft was created'})`);
+        }
+        this._logger.info(`Checked out workflow '${summary.name}' as version ${graph.id}`);
+        return { workflowSysId: summary.sysId, versionSysId: graph.id, alreadyCheckedOut: false };
+    }
+    /**
+     * The draft version of a workflow that the current user has checked out.
+     *
+     * @param workflow Workflow name, wf_workflow sys_id or a version sys_id
+     * @throws Error when the workflow is not checked out, or is checked out by someone else
+     */
+    async getDraftVersion(workflow) {
+        const summary = await this.resolveWorkflow(workflow);
+        const draft = summary.checkedOutVersion;
+        if (!draft)
+            throw new Error(`Workflow '${summary.name}' is not checked out. Check it out first.`);
+        if (!draft.byCurrentUser) {
+            throw new Error(`Workflow '${summary.name}' is checked out by ${draft.checkedOutByName || draft.checkedOutBy}, not the current user.`);
+        }
+        return draft.sysId;
+    }
+    /**
+     * Publish a checked-out draft, as the editor's Publish does: validate, publish, and
+     * retire the previously published version. The instance records the whole workflow
+     * in the current update set.
+     *
+     * @throws WorkflowValidationError when validation finds critical problems, or
+     *         warnings without `allowWarnings`
+     */
+    async publish(versionSysId, options = {}) {
+        await this.requireDraft(versionSysId);
+        let outcome = await this._diagram.publish(versionSysId, true);
+        let warnings = [];
+        if (outcome.messages.validationCritical !== undefined) {
+            const items = await this.findingsOrEmpty(versionSysId);
+            throw new WorkflowValidationError(versionSysId, 'critical', firstLine(outcome.messages.validationCritical, items), items);
+        }
+        if (outcome.messages.validationWarning !== undefined) {
+            const items = await this.findingsOrEmpty(versionSysId);
+            if (!options.allowWarnings) {
+                throw new WorkflowValidationError(versionSysId, 'warning', firstLine(outcome.messages.validationWarning, items), items);
+            }
+            warnings = items;
+            outcome = await this._diagram.publish(versionSysId, false);
+        }
+        if (!outcome.graph?.published) {
+            throw new Error(`Workflow version ${versionSysId} was not published`);
+        }
+        this._logger.info(`Published workflow version ${versionSysId}`);
+        return { versionSysId, warnings, fullSequences: outcome.graph.fullSequences };
+    }
+    /**
+     * Throw away a checked-out draft, keeping the published version.
+     *
+     * @throws Error when the draft is the workflow's only version (use deleteWorkflow)
+     */
+    async discardCheckout(versionSysId) {
+        const version = await this.requireDraft(versionSysId);
+        const others = await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `workflow=${str(version.workflow)}^sys_id!=${versionSysId}`, 'sys_id', 1);
+        if (!others.length) {
+            throw new Error(`Version ${versionSysId} is the only version of workflow '${str(version.name)}'; `
+                + 'discarding it would delete the workflow. Use deleteWorkflow() to do that.');
+        }
+        await this._diagram.delete(versionSysId);
+        if ((await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `sys_id=${versionSysId}`, 'sys_id', 1)).length) {
+            throw new Error(`Draft version ${versionSysId} was not deleted`);
+        }
+        this._logger.info(`Discarded draft version ${versionSysId}`);
+    }
+    /**
+     * Delete a workflow and every version of it.
+     *
+     * @param workflow Workflow name, wf_workflow sys_id or a version sys_id
+     */
+    async deleteWorkflow(workflow) {
+        const summary = await this.resolveWorkflow(workflow);
+        const versions = await this.getWorkflowVersions(summary.sysId);
+        // Drafts first, the published version last: the parent workflow goes with its last version.
+        const ordered = [...versions].sort((a, b) => Number(a.published) - Number(b.published));
+        for (const version of ordered)
+            await this._diagram.delete(version.sysId);
+        if ((await this.read(WorkflowManager.WF_WORKFLOW, `sys_id=${summary.sysId}`, 'sys_id', 1)).length) {
+            throw new Error(`Workflow '${summary.name}' was not fully deleted`);
+        }
+        this._logger.info(`Deleted workflow '${summary.name}' (${versions.length} versions)`);
+    }
+    /**
+     * Activate or deactivate a workflow (the editor's Set Active / Set Inactive).
+     *
+     * @param versionSysId The published version
+     */
+    async setWorkflowActive(versionSysId, active) {
+        this.requireSysId(versionSysId, 'versionSysId');
+        await this._diagram.setActive(versionSysId, active);
+    }
+    /**
+     * Change a draft's workflow properties.
+     */
+    async updateWorkflowProperties(versionSysId, options) {
+        await this.requireDraft(versionSysId);
+        const body = { ...(options.fields ?? {}) };
+        if (options.name !== undefined)
+            body.name = options.name;
+        if (options.description !== undefined)
+            body.description = options.description;
+        if (options.condition !== undefined)
+            body.condition = options.condition;
+        if (options.conditionType !== undefined)
+            body.condition_type = options.conditionType;
+        if (!Object.keys(body).length)
+            return;
+        const response = await this._tableAPI.put(WorkflowManager.WF_WORKFLOW_VERSION, versionSysId, body);
+        if (response?.status !== 200) {
+            throw new Error(`Failed to update workflow version ${versionSysId}. Status: ${response?.status ?? 'unknown'}`);
+        }
+    }
+    // ============================================================
+    // Editing a checked-out draft (Workflow Editor parity)
+    // ============================================================
+    /**
+     * Add an activity to a checked-out draft, configured with variables, and optionally
+     * wire it in. The activity is created through the editor's activity form, so its
+     * variables are written and its default exits are created exactly as in the UI.
+     */
+    async addActivity(versionSysId, options) {
+        await this.requireDraft(versionSysId);
+        if (!options?.name || options.name.trim().length === 0)
+            throw new InvalidParameterException('Activity name is required');
+        const definition = await this.resolveActivityDefinition(options.definition);
+        const insertOn = options.insertOn ? await this.readTransition(versionSysId, options.insertOn) : undefined;
+        const from = options.connectFrom ? await this.readActivity(options.connectFrom.activity, versionSysId) : undefined;
+        if (options.connectTo)
+            await this.readActivity(options.connectTo, versionSysId);
+        let x = options.x;
+        let y = options.y;
+        if (x === undefined || y === undefined) {
+            const position = this.defaultPosition(insertOn, from);
+            x = x ?? position.x;
+            y = y ?? position.y;
+        }
+        const fields = { name: options.name, x, y };
+        if (options.stage !== undefined)
+            fields.stage = await this.resolveStage(versionSysId, options.stage);
+        if (options.input !== undefined)
+            fields.input = typeof options.input === 'string' ? options.input : JSON.stringify(options.input);
+        // Resolve everything that can be checked before anything is written.
+        const fromExit = from
+            ? this.pickExit(await this.readConditions(from.sysId), options.connectFrom.condition, from.name, false)
+            : undefined;
+        this._logger.info(`Adding ${definition.name} activity '${options.name}' to version ${versionSysId}`);
+        const written = await this._forms.insert(WorkflowManager.WF_ACTIVITY, {
+            view: WorkflowManager.ACTIVITY_VIEW,
+            initialQuery: `workflow_version=${versionSysId}^activity_definition=${definition.sysId}`,
+            fields,
+            variables: options.variables && Object.keys(options.variables).length ? options.variables : undefined,
+        });
+        const activitySysId = written.sysId;
+        const conditions = await this.readConditions(activitySysId);
+        // The new activity's exits exist only now (Switch builds them from its variables).
+        // If the one asked for is not there, take the activity out again rather than
+        // leave a half-wired step on the draft.
+        let ownExit;
+        try {
+            if (insertOn || options.connectTo)
+                ownExit = this.pickExit(conditions, options.exitCondition, options.name, true);
+        }
+        catch (error) {
+            await this.removeActivity(activitySysId).catch(cleanup => {
+                this._logger.warn(`Could not remove activity ${activitySysId} after a failed add: ${cleanup.message}`);
+            });
+            throw error;
+        }
+        const transitionSysIds = [];
+        try {
+            if (insertOn) {
+                const outgoing = { id: newSysId(), source: activitySysId, sourcePort: ownExit.sysId, target: insertOn.to };
+                await this._diagram.newEdgeControlNode(versionSysId, { id: activitySysId, x, y }, [{ id: insertOn.sysId, source: insertOn.from, sourcePort: insertOn.condition, target: activitySysId }], [outgoing]);
+                transitionSysIds.push(insertOn.sysId, outgoing.id);
+            }
+            if (from) {
+                const edge = { id: newSysId(), source: from.sysId, sourcePort: fromExit.sysId, target: activitySysId };
+                await this._diagram.newEdge(versionSysId, edge);
+                transitionSysIds.push(edge.id);
+            }
+            if (options.connectTo) {
+                const edge = { id: newSysId(), source: activitySysId, sourcePort: ownExit.sysId, target: options.connectTo };
+                await this._diagram.newEdge(versionSysId, edge);
+                transitionSysIds.push(edge.id);
+            }
+            await this._diagram.updateStages(versionSysId);
+        }
+        catch (error) {
+            const e = error;
+            e.message = `${e.message} (activity '${options.name}' ${activitySysId} was added to the draft; its wiring is incomplete)`;
+            throw e;
+        }
+        return { activitySysId, name: options.name, conditions, transitionSysIds };
+    }
+    /**
+     * Change an activity on a checked-out draft. Variables you do not pass keep their values.
+     */
+    async updateActivity(activitySysId, options) {
+        const activity = await this.readActivity(activitySysId);
+        await this.requireDraft(activity.versionSysId);
+        const fields = {};
+        if (options.name !== undefined)
+            fields.name = options.name;
+        if (options.stage !== undefined)
+            fields.stage = await this.resolveStage(activity.versionSysId, options.stage);
+        if (options.input !== undefined)
+            fields.input = typeof options.input === 'string' ? options.input : JSON.stringify(options.input);
+        const variables = options.variables && Object.keys(options.variables).length ? options.variables : undefined;
+        if (Object.keys(fields).length || variables) {
+            await this._forms.update(WorkflowManager.WF_ACTIVITY, activitySysId, {
+                view: WorkflowManager.ACTIVITY_VIEW, fields, variables,
+            });
+        }
+        if (options.x !== undefined || options.y !== undefined) {
+            await this._diagram.moveNodes(activity.versionSysId, [{
+                    id: activitySysId, x: options.x ?? activity.x ?? 0, y: options.y ?? activity.y ?? 0,
+                }]);
+        }
+        if (fields.stage !== undefined)
+            await this._diagram.updateStages(activity.versionSysId);
+    }
+    /**
+     * Remove an activity (with its exits and variables) from a checked-out draft.
+     */
+    async removeActivity(activitySysId, options = {}) {
+        const activity = await this.readActivity(activitySysId);
+        await this.requireDraft(activity.versionSysId);
+        if (/(^|,)\s*(begin|end)\s*=\s*true/i.test(activity.definitionAttributes)) {
+            throw new InvalidParameterException(`'${activity.name}' is the workflow's ${activity.definitionName} activity and cannot be removed`);
+        }
+        const touching = (await this.read(WorkflowManager.WF_TRANSITION, `from=${activitySysId}^ORto=${activitySysId}`, 'sys_id,from,to,condition', 1000))
+            .map(toEdge);
+        const incoming = touching.filter(e => e.target === activitySysId && e.source !== activitySysId);
+        const outgoing = touching.filter(e => e.source === activitySysId);
+        if (options.reconnect) {
+            if (incoming.length !== 1 || outgoing.length !== 1) {
+                throw new InvalidParameterException(`Cannot reconnect around '${activity.name}': it has ${incoming.length} incoming `
+                    + `and ${outgoing.length} outgoing transitions (exactly one of each is needed)`);
+            }
+            const joined = { ...incoming[0], target: outgoing[0].target };
+            // The path may already exist; the editor never draws the same exit-to-target twice.
+            const duplicate = await this.read(WorkflowManager.WF_TRANSITION, `condition=${joined.sourcePort}^to=${joined.target}^sys_id!=${joined.id}`, 'sys_id', 1);
+            if (duplicate.length) {
+                await this._diagram.deleteNode(activity.versionSysId, activitySysId, [...incoming, ...outgoing]);
+            }
+            else {
+                await this._diagram.deleteNode(activity.versionSysId, activitySysId, outgoing, [joined]);
+            }
+        }
+        else {
+            await this._diagram.deleteNode(activity.versionSysId, activitySysId, touching);
+        }
+        if ((await this.read(WorkflowManager.WF_ACTIVITY, `sys_id=${activitySysId}`, 'sys_id', 1)).length) {
+            throw new Error(`Activity '${activity.name}' was not removed`);
+        }
+        this._logger.info(`Removed activity '${activity.name}' from version ${activity.versionSysId}`);
+    }
+    /**
+     * Reposition activities on checked-out drafts.
+     */
+    async moveActivities(positions) {
+        const byVersion = new Map();
+        for (const position of positions ?? []) {
+            const activity = await this.readActivity(position.sysId);
+            byVersion.set(activity.versionSysId, [...(byVersion.get(activity.versionSysId) ?? []), position]);
+        }
+        for (const [versionSysId, moves] of byVersion) {
+            await this.requireDraft(versionSysId);
+            await this._diagram.moveNodes(versionSysId, moves.map(m => ({ id: m.sysId, x: m.x, y: m.y })));
+        }
+    }
+    /**
+     * Add a transition on a checked-out draft.
+     *
+     * @returns The new transition's sys_id
+     */
+    async addTransition(options) {
+        const from = await this.readActivity(options.from);
+        await this.requireDraft(from.versionSysId);
+        await this.readActivity(options.to, from.versionSysId);
+        const exit = this.pickExit(await this.readConditions(from.sysId), options.condition, from.name, false);
+        const existing = await this.read(WorkflowManager.WF_TRANSITION, `condition=${exit.sysId}^to=${options.to}`, 'sys_id', 1);
+        if (existing.length)
+            throw new InvalidParameterException(`'${from.name}' (${exit.name}) already leads to that activity (${str(existing[0].sys_id)})`);
+        const edge = { id: newSysId(), source: from.sysId, sourcePort: exit.sysId, target: options.to };
+        await this._diagram.newEdge(from.versionSysId, edge);
+        return edge.id;
+    }
+    /**
+     * Point an existing transition at a different activity on a checked-out draft.
+     */
+    async retargetTransition(transitionSysId, toActivitySysId) {
+        const transition = await this.readTransition(undefined, transitionSysId);
+        await this.requireDraft(transition.versionSysId);
+        await this.readActivity(toActivitySysId, transition.versionSysId);
+        await this._diagram.changeEdge(transition.versionSysId, {
+            id: transition.sysId, source: transition.from, sourcePort: transition.condition, target: toActivitySysId,
+        });
+    }
+    /**
+     * Remove a transition from a checked-out draft.
+     */
+    async removeTransition(transitionSysId) {
+        const transition = await this.readTransition(undefined, transitionSysId);
+        await this.requireDraft(transition.versionSysId);
+        await this._diagram.deleteEdge(transition.versionSysId, {
+            id: transition.sysId, source: transition.from, sourcePort: transition.condition, target: transition.to,
+        });
+    }
+    /**
+     * Add an exit to an activity on a checked-out draft.
+     *
+     * @returns The new condition's sys_id
+     */
+    async addCondition(options) {
+        const activity = await this.readActivity(options.activity);
+        await this.requireDraft(activity.versionSysId);
+        if (!options.name || !options.condition)
+            throw new InvalidParameterException('Condition name and condition are required');
+        const body = { activity: activity.sysId, name: options.name, condition: options.condition };
+        if (options.order !== undefined)
+            body.order = options.order;
+        if (options.elseFlag !== undefined)
+            body.else_flag = options.elseFlag;
+        if (options.error !== undefined)
+            body.error = options.error;
+        if (options.shortDescription !== undefined)
+            body.short_description = options.shortDescription;
+        const response = await this._tableAPI.post(WorkflowManager.WF_CONDITION, {}, body);
+        const sysId = response?.bodyObject?.result?.sys_id;
+        if (!sysId)
+            throw new Error(`Failed to add condition '${options.name}'. Status: ${response?.status ?? 'unknown'}`);
+        return sysId;
+    }
+    /**
+     * Change an exit on a checked-out draft.
+     */
+    async updateCondition(conditionSysId, options) {
+        const condition = await this.readCondition(conditionSysId);
+        await this.requireDraft(condition.versionSysId);
+        const body = {};
+        if (options.name !== undefined)
+            body.name = options.name;
+        if (options.condition !== undefined)
+            body.condition = options.condition;
+        if (options.order !== undefined)
+            body.order = options.order;
+        if (options.elseFlag !== undefined)
+            body.else_flag = options.elseFlag;
+        if (options.error !== undefined)
+            body.error = options.error;
+        if (options.shortDescription !== undefined)
+            body.short_description = options.shortDescription;
+        if (!Object.keys(body).length)
+            return;
+        const response = await this._tableAPI.put(WorkflowManager.WF_CONDITION, conditionSysId, body);
+        if (response?.status !== 200)
+            throw new Error(`Failed to update condition ${conditionSysId}. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * Remove an exit, and the transitions leaving from it, from a checked-out draft.
+     */
+    async removeCondition(conditionSysId) {
+        const condition = await this.readCondition(conditionSysId);
+        await this.requireDraft(condition.versionSysId);
+        const leaving = (await this.read(WorkflowManager.WF_TRANSITION, `condition=${conditionSysId}`, 'sys_id,from,to,condition', 1000)).map(toEdge);
+        for (const edge of leaving)
+            await this._diagram.deleteEdge(condition.versionSysId, edge);
+        await this.request().delete({
+            method: 'DELETE', path: `/api/now/table/${WorkflowManager.WF_CONDITION}/${conditionSysId}`,
+            headers: { Accept: 'application/json' }, query: null, body: null,
+        });
+    }
+    // ============================================================
+    // Internals
+    // ============================================================
+    async createActivityThroughForm(options) {
+        if (!options.activityDefinitionSysId) {
+            throw new Error('activityDefinitionSysId is required when variables are given');
+        }
+        // Both go into the form's initial query, which the signed form state carries.
+        this.requireSysId(options.workflowVersionSysId, 'workflowVersionSysId');
+        this.requireSysId(options.activityDefinitionSysId, 'activityDefinitionSysId');
+        const fields = { name: options.name };
+        if (options.x !== undefined)
+            fields.x = options.x;
+        if (options.y !== undefined)
+            fields.y = options.y;
+        if (options.width !== undefined)
+            fields.width = options.width;
+        if (options.height !== undefined)
+            fields.height = options.height;
+        const written = await this._forms.insert(WorkflowManager.WF_ACTIVITY, {
+            view: WorkflowManager.ACTIVITY_VIEW,
+            initialQuery: `workflow_version=${options.workflowVersionSysId}^activity_definition=${options.activityDefinitionSysId}`,
+            fields,
+            variables: Object.keys(options.variables).length ? options.variables : undefined,
+        });
+        this._logger.info(`Created activity '${options.name}' with sys_id=${written.sysId}`);
+        return { activitySysId: written.sysId, name: options.name };
+    }
+    async summarize(workflows) {
+        if (!workflows.length)
+            return [];
+        const ids = workflows.map(w => str(w.sys_id));
+        const versions = await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `workflowIN${ids.join(',')}^published=true^ORchecked_outISNOTEMPTY`, VERSION_FIELDS, 10000);
+        const me = versions.some(v => str(v.published) !== 'true' && str(v.checked_out_by)) ? await this.currentUserSysId() : '';
+        return workflows.map(row => {
+            const own = versions.filter(v => str(v.workflow) === str(row.sys_id));
+            const published = own.find(v => str(v.published) === 'true');
+            const draft = own.find(v => str(v.published) !== 'true' && str(v.checked_out_by));
+            const summary = {
+                sysId: str(row.sys_id),
+                name: str(row.name),
+                table: str(row.table),
+                description: str(row.description),
+                active: str((published ?? draft)?.active) === 'true',
+            };
+            if (published)
+                summary.publishedVersionSysId = str(published.sys_id);
+            if (draft) {
+                summary.checkedOutVersion = {
+                    sysId: str(draft.sys_id),
+                    checkedOutBy: str(draft.checked_out_by),
+                    checkedOutByName: str(draft['checked_out_by.name']) || undefined,
+                    checkedOutOn: str(draft.checked_out),
+                    byCurrentUser: str(draft.checked_out_by) === me,
+                };
+            }
+            return summary;
+        });
+    }
+    async readVersion(versionSysId) {
+        const rows = await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `sys_id=${versionSysId}`, VERSION_FIELDS, 1);
+        if (!rows.length)
+            throw new InvalidParameterException(`Workflow version ${versionSysId} was not found`);
+        return rows[0];
+    }
+    /**
+     * Editing is only allowed on an unpublished draft checked out to the current user —
+     * the same rule the editor enforces (and the wf_condition ACLs require a checkout).
+     */
+    async requireDraft(versionSysId) {
+        this.requireSysId(versionSysId, 'versionSysId');
+        const version = await this.readVersion(versionSysId);
+        if (str(version.published) === 'true') {
+            throw new Error(`Workflow version ${versionSysId} ('${str(version.name)}') is published. Check the workflow out and edit the draft.`);
+        }
+        const holder = str(version.checked_out_by);
+        if (!holder) {
+            throw new Error(`Workflow version ${versionSysId} ('${str(version.name)}') is not checked out; it is a retired version.`);
+        }
+        if (holder !== await this.currentUserSysId()) {
+            throw new Error(`Workflow version ${versionSysId} ('${str(version.name)}') is checked out by ${str(version['checked_out_by.name']) || holder}.`);
+        }
+        return version;
+    }
+    async readActivity(activitySysId, versionSysId) {
+        this.requireSysId(activitySysId, 'activity sys_id');
+        const rows = await this.read(WorkflowManager.WF_ACTIVITY, `sys_id=${activitySysId}`, 'sys_id,name,workflow_version,activity_definition.name,activity_definition.attributes,x,y', 1);
+        if (!rows.length)
+            throw new InvalidParameterException(`Activity ${activitySysId} was not found`);
+        const row = rows[0];
+        if (versionSysId && str(row.workflow_version) !== versionSysId) {
+            throw new InvalidParameterException(`Activity ${activitySysId} ('${str(row.name)}') belongs to a different workflow version`);
+        }
+        return {
+            sysId: activitySysId,
+            name: str(row.name),
+            versionSysId: str(row.workflow_version),
+            definitionName: str(row['activity_definition.name']),
+            definitionAttributes: str(row['activity_definition.attributes']),
+            x: optNum(row.x),
+            y: optNum(row.y),
+        };
+    }
+    async readTransition(versionSysId, transitionSysId) {
+        this.requireSysId(transitionSysId, 'transition sys_id');
+        const rows = await this.read(WorkflowManager.WF_TRANSITION, `sys_id=${transitionSysId}`, 'sys_id,from,to,condition,from.workflow_version,from.x,from.y,to.x,to.y', 1);
+        if (!rows.length)
+            throw new InvalidParameterException(`Transition ${transitionSysId} was not found`);
+        const row = rows[0];
+        const owner = str(row['from.workflow_version']);
+        if (versionSysId && owner !== versionSysId) {
+            throw new InvalidParameterException(`Transition ${transitionSysId} belongs to a different workflow version`);
+        }
+        return {
+            sysId: transitionSysId, from: str(row.from), to: str(row.to), condition: str(row.condition), versionSysId: owner,
+            fromX: optNum(row['from.x']), fromY: optNum(row['from.y']), toX: optNum(row['to.x']), toY: optNum(row['to.y']),
+        };
+    }
+    async readCondition(conditionSysId) {
+        this.requireSysId(conditionSysId, 'condition sys_id');
+        const rows = await this.read(WorkflowManager.WF_CONDITION, `sys_id=${conditionSysId}`, `${CONDITION_FIELDS},activity.workflow_version`, 1);
+        if (!rows.length)
+            throw new InvalidParameterException(`Condition ${conditionSysId} was not found`);
+        return { ...toCondition(rows[0]), versionSysId: str(rows[0]['activity.workflow_version']) };
+    }
+    async readConditions(activitySysId) {
+        return (await this.read(WorkflowManager.WF_CONDITION, `activity=${activitySysId}^ORDERBYorder`, CONDITION_FIELDS, 500)).map(toCondition);
+    }
+    async readVariableValues(activitySysIds) {
+        const values = new Map();
+        for (let i = 0; i < activitySysIds.length; i += 100) {
+            const chunk = activitySysIds.slice(i, i + 100);
+            const rows = await this.read('sys_variable_value', `document=wf_activity^document_keyIN${chunk.join(',')}^ORDERBYorder`, 'document_key,variable.element,value', 10000);
+            for (const row of rows) {
+                const key = str(row.document_key);
+                const element = str(row['variable.element']);
+                if (!element)
+                    continue;
+                values.set(key, { ...(values.get(key) ?? {}), [element]: str(row.value) });
+            }
+        }
+        return values;
+    }
+    async resolveActivityDefinition(nameOrSysId) {
+        const ref = (nameOrSysId ?? '').trim();
+        if (!ref)
+            throw new InvalidParameterException('An activity definition name or sys_id is required');
+        const fields = 'sys_id,name,category,sys_class_name';
+        let rows = SYS_ID.test(ref) ? await this.read('wf_element_definition', `sys_id=${ref}`, fields, 1) : [];
+        if (!rows.length)
+            rows = await this.read('wf_element_definition', `name=${queryValue(ref, 'activity definition name')}`, fields, 20);
+        if (!rows.length)
+            throw new InvalidParameterException(`No activity definition found for '${ref}'`);
+        if (rows.length > 1) {
+            // A core activity wins over same-named Activity Designer ones.
+            const core = rows.filter(r => str(r.sys_class_name) === 'wf_activity_definition');
+            if (core.length === 1)
+                rows = core;
+            else {
+                throw new InvalidParameterException(`'${ref}' matches ${rows.length} activity definitions; use a sys_id: `
+                    + rows.map(r => `${str(r.sys_id)} (${str(r.sys_class_name)}${str(r.category) ? `, ${str(r.category)}` : ''})`).join(', '));
+            }
+        }
+        return toDefinitionSummary(rows[0]);
+    }
+    async resolveStage(versionSysId, stage) {
+        if (stage === '')
+            return '';
+        const stages = await this.read('wf_stage', `workflow_version=${versionSysId}`, 'sys_id,name,value', 1000);
+        const byId = stages.find(s => str(s.sys_id) === stage);
+        const byName = stages.filter(s => str(s.name).toLowerCase() === stage.toLowerCase());
+        const byValue = stages.filter(s => str(s.value).toLowerCase() === stage.toLowerCase());
+        const candidates = byId ? [byId] : byName.length ? byName : byValue;
+        if (candidates.length > 1) {
+            throw new InvalidParameterException(`${candidates.length} stages match '${stage}' on workflow version ${versionSysId}; `
+                + `use a sys_id: ${candidates.map(c => str(c.sys_id)).join(', ')}`);
+        }
+        const match = candidates[0];
+        if (!match) {
+            const known = stages.map(s => str(s.name)).join(', ') || '(this version has no stages)';
+            throw new InvalidParameterException(`No stage '${stage}' on workflow version ${versionSysId}. Available: ${known}`);
+        }
+        return str(match.sys_id);
+    }
+    /**
+     * Pick an exit by name or sys_id. With no reference, a single exit is unambiguous;
+     * for several, `firstWhenAmbiguous` takes the first in order (what the editor does
+     * when you drop onto a line), otherwise the caller must choose.
+     */
+    pickExit(conditions, ref, activityName, firstWhenAmbiguous) {
+        if (!conditions.length)
+            throw new InvalidParameterException(`'${activityName}' has no exits to connect from`);
+        const names = conditions.map(c => c.name).join(', ');
+        if (ref) {
+            const byId = conditions.find(c => c.sysId === ref);
+            if (byId)
+                return byId;
+            const byName = conditions.filter(c => c.name.toLowerCase() === ref.toLowerCase());
+            if (byName.length > 1) {
+                throw new InvalidParameterException(`'${activityName}' has ${byName.length} exits named '${ref}'; use a sys_id: `
+                    + byName.map(c => c.sysId).join(', '));
+            }
+            if (!byName.length)
+                throw new InvalidParameterException(`'${activityName}' has no exit '${ref}'. Exits: ${names}`);
+            return byName[0];
+        }
+        if (conditions.length === 1 || firstWhenAmbiguous)
+            return conditions[0];
+        throw new InvalidParameterException(`'${activityName}' has several exits; specify one of: ${names}`);
+    }
+    defaultPosition(insertOn, from) {
+        if (insertOn) {
+            return {
+                x: Math.round(((insertOn.fromX ?? 0) + (insertOn.toX ?? 0)) / 2),
+                y: Math.round(((insertOn.fromY ?? 0) + (insertOn.toY ?? 0)) / 2),
+            };
+        }
+        if (from)
+            return { x: (from.x ?? 0) + 180, y: from.y ?? 0 };
+        return { x: 200, y: 200 };
+    }
+    /**
+     * The version to read for a workflow reference: a version sys_id as is; otherwise the
+     * current user's draft and/or the published version, as asked.
+     */
+    async resolveVersionToRead(ref, which) {
+        if (SYS_ID.test(ref ?? '') && (await this.read(WorkflowManager.WF_WORKFLOW_VERSION, `sys_id=${ref}`, 'sys_id', 1)).length) {
+            return ref;
+        }
+        const summary = await this.resolveWorkflow(ref);
+        const mine = summary.checkedOutVersion?.byCurrentUser ? summary.checkedOutVersion.sysId : undefined;
+        const chosen = which === 'draft' ? mine
+            : which === 'published' ? summary.publishedVersionSysId
+                : mine ?? summary.publishedVersionSysId ?? summary.checkedOutVersion?.sysId;
+        if (!chosen)
+            throw new Error(`Workflow '${summary.name}' has no ${which === 'current' ? 'readable' : which} version`);
+        return chosen;
+    }
+    /**
+     * Whether a core activity type can pause the workflow, read from its handler script:
+     * it sets `activity.state` / `executing.state` to `'waiting'`, itself or in a handler it
+     * extends. Some only wait conditionally (tasks honour `wait_for_completion`).
+     */
+    async typeWaits(detail) {
+        if (detail.sysClassName !== 'wf_activity_definition')
+            return undefined;
+        let query = `sys_id=${detail.sysId}`;
+        for (let depth = 0; depth < 5; depth++) {
+            const rows = await this.read('wf_activity_definition', query, 'script', 1);
+            if (!rows.length)
+                return undefined;
+            const script = str(rows[0].script).replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+            if (/\b(activity|executing)\.state\s*=\s*['"]waiting['"]/.test(script))
+                return true;
+            const parent = /extendsObject\(\s*(\w+)ActivityHandler\b/.exec(script)?.[1];
+            if (!parent || parent === 'WF')
+                return false;
+            query = `js_class_name=${parent}`;
+        }
+        return false;
+    }
+    /** Display names for sys_ids, grouped by table. Unknown tables or records are skipped. */
+    async displayNames(wanted) {
+        const names = {};
+        await mapLimit([...wanted.entries()], 2, async ([table, ids]) => {
+            if (!/^[a-z0-9_]+$/i.test(table))
+                return;
+            const list = [...ids];
+            for (let i = 0; i < list.length; i += 100) {
+                let rows = [];
+                try {
+                    rows = await this.read(table, `sys_idIN${list.slice(i, i + 100).join(',')}`, 'sys_id,name,label,question_text,user_name,number,short_description,title', 100);
+                }
+                catch {
+                    return;
+                }
+                for (const row of rows) {
+                    const display = ['name', 'question_text', 'label', 'title', 'user_name', 'number', 'short_description']
+                        .map(f => str(row[f])).find(Boolean);
+                    if (display)
+                        names[str(row.sys_id)] = { table, display };
+                }
+            }
+        });
+        return names;
+    }
+    async findingsOrEmpty(versionSysId) {
+        try {
+            const report = await this.validateWorkflow(versionSysId);
+            return report.items.filter(i => i.level === 'Warn' || i.level === 'Critical');
+        }
+        catch (error) {
+            this._logger.warn(`Could not read validation details for ${versionSysId}: ${error.message}`);
+            return [];
+        }
+    }
+    async currentUserSysId() {
+        if (this._currentUser === undefined) {
+            this._currentUser = this.read('sys_user', 'sys_id=javascript:gs.getUserID()', 'sys_id', 2).then(rows => {
+                // Anything but exactly one row means the query was not evaluated as written.
+                const id = rows.length === 1 ? str(rows[0].sys_id) : '';
+                if (!id)
+                    throw new Error('Could not determine the current user');
+                return id;
+            });
+            this._currentUser.catch(() => { this._currentUser = undefined; });
+        }
+        return this._currentUser;
+    }
+    async read(table, query, fields, limit) {
+        const params = { sysparm_query: query, sysparm_fields: fields, sysparm_limit: String(limit), sysparm_exclude_reference_link: 'true' };
+        let response = await this._tableAPI.get(table, params);
+        // 202: the instance queued the request behind others in this session; ask again.
+        for (let attempt = 1; response?.status === 202 && attempt <= 3; attempt++) {
+            await new Promise(resolve => setTimeout(resolve, 500 * attempt));
+            response = await this._tableAPI.get(table, params);
+        }
+        if (response?.status !== 200 || !Array.isArray(response.bodyObject?.result)) {
+            throw new Error(`Failed to read ${table}. Status: ${response?.status ?? 'unknown'}`);
+        }
+        return response.bodyObject.result;
+    }
+    async count(table, query) {
+        const get = () => this.request().get({
+            method: 'GET', path: `/api/now/stats/${table}`, headers: { Accept: 'application/json' }, body: null,
+            query: { sysparm_query: query, sysparm_count: 'true' }, requires: READ_ONLY,
+        });
+        let response = await get();
+        for (let attempt = 1; response?.status === 202 && attempt <= 3; attempt++) {
+            await new Promise(resolve => setTimeout(resolve, 500 * attempt));
+            response = await get();
+        }
+        const count = response?.bodyObject?.result?.stats?.count;
+        if (response?.status !== 200 || count === undefined) {
+            throw new Error(`Failed to count ${table}. Status: ${response?.status ?? 'unknown'}`);
+        }
+        return Number(count) || 0;
+    }
+    request() {
+        return SessionManager.getInstance().getRequest(this._instance);
+    }
+    requireSysId(value, label) {
+        if (!SYS_ID.test(value ?? ''))
+            throw new InvalidParameterException(`${label} must be a 32-character sys_id`);
+    }
+}
+function str(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (value && typeof value === 'object' && 'value' in value)
+        return str(value.value);
+    return '';
+}
+function num(value) {
+    return Number(str(value)) || 0;
+}
+function optNum(value) {
+    const text = str(value);
+    if (text === '')
+        return undefined;
+    const n = Number(text);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** A value embedded in an encoded query must not be able to add conditions of its own. */
+function queryValue(value, label) {
+    if (/[\^\r\n]/.test(value))
+        throw new InvalidParameterException(`The ${label} cannot contain '^' or line breaks`);
+    return value;
+}
+function normalizeSpace(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Whether a stored variable value is the variable's default. Booleans are stored as `1`/`0`
+ * but defaulted as `true`/`false` (or empty).
+ */
+function isDefaultValue(def, value) {
+    if (!def)
+        return false;
+    if (def.internalType === 'boolean') {
+        const truth = (v) => ['1', 'true'].includes(String(v ?? '').trim().toLowerCase());
+        return truth(def.defaultValue) === truth(value);
+    }
+    return normalizeSpace(def.defaultValue ?? '') === normalizeSpace(value);
+}
+function parseJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        // fall through: keep the raw text
+    }
+    return { raw: text };
+}
+/** Map with at most `limit` calls in flight. */
+async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await fn(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+function newSysId() {
+    return randomBytes(16).toString('hex');
+}
+function decodeEntities(text) {
+    return text
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&');
+}
+/** The processor's validation text is a canned prompt; the report summary line says more. */
+function firstLine(message, items) {
+    const summary = /Validate Summary[^\n]*/.exec(message)?.[0]?.replace(/\s+/g, ' ').trim();
+    return summary || message.split('\n')[0] || `${items.length} findings`;
+}
+/** Parse Activity Designer `input_meta` / `output_meta` (a DATA_OBJECT with properties). */
+function designerFields(meta) {
+    if (!meta)
+        return [];
+    try {
+        const parsed = JSON.parse(meta);
+        return (parsed.properties ?? []).map(p => ({ name: String(p.name ?? ''), type: String(p.type ?? ''), mandatory: p.mandatory === true }));
+    }
+    catch {
+        return [];
+    }
+}
+function toEdge(row) {
+    return { id: str(row.sys_id), source: str(row.from), sourcePort: str(row.condition), target: str(row.to) };
+}
+function toCondition(row) {
+    return {
+        sysId: str(row.sys_id),
+        activitySysId: str(row.activity),
+        name: str(row.name),
+        condition: str(row.condition),
+        order: num(row.order),
+        elseFlag: str(row.else_flag) === 'true',
+        error: str(row.error) === 'true',
+        event: str(row.event) === 'true',
+        eventName: str(row.event_name),
+        shortDescription: str(row.short_description),
+        skipDuringGenerate: str(row.skip_during_generate) === 'true',
+    };
+}
+function toDefinitionSummary(row) {
+    return { sysId: str(row.sys_id), name: str(row.name), category: str(row.category), sysClassName: str(row.sys_class_name) };
+}
+function toVersionSummary(row) {
+    return {
+        sysId: str(row.sys_id),
+        workflowSysId: str(row.workflow),
+        name: str(row.name),
+        table: str(row.table),
+        published: str(row.published) === 'true',
+        active: str(row.active) === 'true',
+        checkedOut: str(row.checked_out),
+        checkedOutBy: str(row.checked_out_by),
+        createdOn: str(row.sys_created_on),
+        updatedOn: str(row.sys_updated_on),
+    };
 }
 //# sourceMappingURL=WorkflowManager.js.map